Tolstoy SDK

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.

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():

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. 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 for what the SDK does without the value. On Shopify, get the answer from Shopify’s Customer Privacy API:

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:

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:

{ "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, 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.

Home

Tolstoy for AI agents

Storefront

Add the SDK

Read the results

​Add the SDK

​Shopper consent

​Read the results

Add the SDK

Shopper consent

Read the results