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

# Tolstoy SDK

> Send your own storefront events, such as clicks on a button, to Tolstoy analytics with the Tolstoy SDK, and read their counts with the Tolstoy CLI or MCP.

The Tolstoy SDK sends your own events to Tolstoy analytics. Use it to count anything that shoppers do on your storefront, for example how many times shoppers click **Expand product details**.

> [!NOTE]
>
> Your events never count toward Shoppable Videos view billing, and they never change the numbers of your Tolstoy widgets: they are not opens, engaged shoppers, try-ons, add to carts or revenue.

## Add the SDK

The SDK is an ES module on the Tolstoy CDN. Create one SDK on the page, and send each event with `tolstoy.analytics.track()`:

```javascript theme={null}
import { TolstoySDK } from 'https://widgets-sdk.gotolstoy.com/tolstoy-sdk.js';

const tolstoy = new TolstoySDK({ appKey: 'YOUR_APP_KEY' });

document.querySelector('#expand-details').addEventListener('click', () => {
  tolstoy.analytics.track('expand_product_details', { productId: '123' });
});
```

| Value | What it is |
| - | - |
| `appKey` | The app key of your workspace. It is in the code that Tolstoy shows in **Website setup & tracking**: open a widget, click its status button, and then click **Website setup & tracking**. |
| `eventName` | The first argument of `track()`. Tolstoy records the event as `tolstoy-sdk.<eventName>`, for example `tolstoy-sdk.expand_product_details`. With its prefix, the name can have up to 200 characters. |
| Parameters | The optional second argument of `track()`: an object of strings, numbers and booleans. Tolstoy keeps it with the event. As JSON, it can have up to about 10,000 characters. |

The SDK throws an error when `appKey` or the event name is empty. It sends the events in batches: every 10 seconds, when 10 events are in the queue, and when the shopper leaves the page. Tolstoy drops an event that is larger than the limits above.

## Shopper consent

The SDK sends no event and stores no shopper ID until the shopper allows analytics. It drops the events from before that; it does not keep them for later. At each event, the SDK reads the `tolstoy-cookie-policy` value in `localStorage`: `accepted` allows analytics, and `rejected` blocks it. Your page sets this value from the consent tool of your store, before the first event and again when the shopper changes the answer. The SDK does not load a consent tool and does not wait for one. See [Cookie Consent](https://developers.gotolstoy.com/storefront/cookie-consent.md#the-tolstoy-sdk) for what the SDK does without the value.

On Shopify, get the answer from Shopify's [Customer Privacy API](https://shopify.dev/docs/api/customer-privacy):

```javascript theme={null}
const passConsent = (analyticsAllowed) =>
  localStorage.setItem('tolstoy-cookie-policy', analyticsAllowed ? 'accepted' : 'rejected');

window.Shopify.loadFeatures([{ name: 'consent-tracking-api', version: '0.1' }], (error) => {
  if (error) throw error;
  passConsent(window.Shopify.customerPrivacy.analyticsProcessingAllowed());
  startTracking(); // your code: create TolstoySDK and add the listeners that call track()
});

document.addEventListener('visitorConsentCollected', (event) => passConsent(event.detail.analyticsAllowed));
```

Put this code after `startTracking` and the code that it uses: when the page already loaded the API, Shopify calls the callback at once. With a different consent tool, call `passConsent` from the consent callback of that tool.

## Read the results

The report reads tables that Tolstoy builds each night. It covers full UTC days before today. The events of today show after the next build, from about 06:30 UTC.

With the [Tolstoy CLI](https://developers.gotolstoy.com/agents/cli.md):

```bash theme={null}
tolstoy analytics get-store-analytics \
  --date-from 2026-11-01 \
  --date-to 2026-11-09 \
  --sections '["details"]' \
  --json
```

In the details, `events` lists each of your events with the widget type `tolstoy-sdk`, its name, the number of events and the number of shoppers who sent it:

```json theme={null}
{ "widgetType": "tolstoy-sdk", "eventName": "tolstoy-sdk.expand_product_details", "events": 412, "shoppers": 298 }
```

* `--app-url` selects a store from `tolstoy stores list`. Without it, the CLI uses your default store.
* `--channel` (`web` or `app`) limits the report to your website or your Tapcart app.

With the [Tolstoy MCP](https://developers.gotolstoy.com/agents/connect.md), the `get_store_analytics` tool returns the same report. Ask for the `details` section.

The CLI and the MCP read only the stores of the workspace that you signed in to.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.