> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser SDK reference

> Page views, product views, cart, checkout, custom events, and visitor identity.

The script exposes `window.sideshift` after loading. Calls made before consent do not queue events for later delivery. Connect consent using the [installation guide](/pixel/installation).

## Standard events

Call these methods after the script has loaded. Do not include customer names, addresses, email addresses, payment details, or other personal information in event properties.

### Product view

```javascript theme={"system"}
window.sideshift.productViewed({
  productId: 'shirt-blue',
  productName: 'Blue shirt',
  price: 32.50,
  currency: 'USD'
});
```

A product view is sent once per product and page path for the current document.

### Add to cart

Call this after your cart confirms that the item was added:

```javascript theme={"system"}
window.sideshift.addToCart({
  productId: 'shirt-blue',
  quantity: 2,
  price: 32.50,
  currency: 'USD'
});
```

Repeated events for the same product and quantity within two seconds are skipped.

### Checkout started

```javascript theme={"system"}
window.sideshift.checkoutStarted({ value: 65, currency: 'USD' });
```

### Checkout completed

Call this on your order confirmation page:

```javascript theme={"system"}
window.sideshift.checkout({
  orderId: 'order-1042',
  value: 65,
  currency: 'USD'
});
```

The pixel deduplicates each order ID within the browser session. Submit the order to the server API as well.

### Custom event

```javascript theme={"system"}
window.sideshift.track('size_guide_opened', { productId: 'shirt-blue' });
```

Custom events appear in tracking diagnostics. They do not change commission amounts.

### Visitor ID

```javascript theme={"system"}
const visitorId = window.sideshift.getVisitorId();
```

This returns `null` before consent. After consent, the ID is stored in the `ss_vid_YOUR_STORE_ID` cookie for up to 30 days. The attribution window is seven days; cookie lifetime does not extend it.

Pass the ID to your server with the checkout request and store it with the order. If your server receives the store cookie, it can read that cookie directly. Do not replace a missing ID with a guessed or shared ID.

## Event IDs and delivery

Methods that accept a data object accept an optional `event_id` string (1–200 characters). Use a stable ID when retrying the same action. Otherwise, the pixel generates one. Its bounded network retries reuse that ID. Custom event deduplication includes both event name and ID; use a new ID for a new action.

```javascript theme={"system"}
window.sideshift.track('lead', {
  event_id: 'lead-form-submission-1042',
  value: 0,
  currency: 'USD'
});
```

Custom names are trimmed to 250 characters. SideShift's stored generic properties are limited to product name, event name, currency, price, value, and quantity, plus a sanitized page origin. Product and order IDs use the corresponding standard methods. Arbitrary custom properties are not stored. Prices and values here are major-unit display values, never authoritative purchase amounts.

Do not use `track('purchase')` as an order integration. Browser purchase, checkout, subscription, and trial aliases do not create verified orders or advertising purchases. Use the [Orders API](/pixel/orders-api).

## Utility methods

| Method | Result |
| - | - |
| `setConsent(boolean)` | Grants or withdraws the pixel's consent state. |
| `getVisitorId()` | SideShift visitor ID, or `null` before consent. |
| `getAdvertisingContext()` | Currently available advertising context, or `null`. |
| `getAdvertisingContextAsync()` | Resolves after a bounded attempt to load the optional advertising destination; may return `null`. |
| `shopifyCartAttributes(existing)` | Preserves existing cart attributes and replaces `sideshift_visitor_id`; returns an empty visitor value without consent. |

Advertising context is optional and is not a substitute for `getVisitorId()`. See [advertising measurement](/pixel/advertising).