@aftership/web-pixels/README.md

AfterShip Web Pixels for data anaylsis

# What is AfterShip Pixel Web SDK

AfterShip Pixel is a powerful tool for marketing campaign optimization and analytics with a strong commitment to data science. The AfterShip Pixel Web SDK and API make it simple to integrate.

# Getting started

Begin using AfterShip Pixel APIs with a few simple steps. Log in, get your API credentials, and start developing.

## Get Pixel ID

Currently, Pixel ID is available only to whitelisted users. Contact us to obtain one.

## Install

AfterShip provides two common integration methods in web development. Depending on how your store is deployed, you can choose one of them to quickly integrate AfterShip Pixel into your store.


### Using npm or yarn or pnpm or bun (Recommend)

```sh
$ npm install @aftership/web-pixels --save
```

or

```sh
$ yarn add @aftership/web-pixels
```


### Add the AfterShip Pixel snippet
Currently, AfterShip Pixel ID is only available to whitelisted users. Please contact us to obtain the AfterShip Pixel snippet

## Report the First Event

### Initialization
> If you installed using Add the AfterShip Pixel snippet, you can skip this step as the snippet already calls the initialization API.

Before reporting the first event, we need to call `ASPixel.init` to complete the SDK initialization, allowing AfterShip Pixel to know the source of upcoming events.

If this step isn't correctly executed, subsequent events reported via Track won't reach the server.

```javascript
ASPixel.init({
  pixelId:"<AfterShipPixelId>"
})
```


### Report Events
The ASPixel.events contains a variety of semantic event methods that you can choose to bury events in the right scenarios. Each event method has an explicit typescript type.

> SDK will send the request after calling ASPixel.events. Before calling this API, please make sure that your website is compliant with privacy regulations (e.g. GDPR, CCPA, etc.)

```javascript
// Track search terms
ASPixel.events.clicked({
	linkUrl: "test.com",
	label: "test",
});

// Track a simpler version.
ASPixel.events.pageViewed();
```

## Identify Users
After initializing ASPixel, you can call ASPixel.identify() to identify individual users. This method accepts customerId, and all subsequent event reports will include this customerId.

```javascript
// Track search terms
// Add a customer ID
ASPixel.identify({
	customerId: 'test customerId',
});
```

After identifying the user, it is also possible to resetIdentity the user by calling ASPixel.resetIdentiy(). After calling this,all events will not carry the user id.
```javascript
// Track a simpler version.
// Add a user ID
ASPixel.track('$page_viewed', {
	customer_id: "e4b0f8a6c9d64a2b8e2f0c67a8d4f9e2"
});
```

## Make a test API request
> Enabling this won't report events but will print logs in the console.
### Enable Debug Mode
Method: Call `window.ASPixel.debug(true)` in the console.

### Disable Debug Mode
Method:  Call `window.ASPixel.debug(false)` in the console.


# API Basic

1. init
- Description: To initialize the SDK, you need to provide a pixelId to identify the store. This process is asynchronous, so be sure to handle it accordingly.
- Parameter:
```javascript
await ASPixel.init({
  pixelId:"<AfterShipPixelId>"
})
```
2. events
- Description: For the event reporting method, provide the event name along with the corresponding parameters to report the event.
- Parameter:
```javascript
ASPixel.events.pageViewed()
```
3. debug
- Description: To debug data reporting, you can call the debug method under the window.ASPixel in the console to enable the debugging environment. Once enabled, events will not call the API; they will only output the event calls in the console.
- Parameter:
```javascript
// fisrt time is open
window.ASPixel.debug()
// second time is close
window.ASPixel.debug()
```