Events & users

Most events need no code: the SDK captures them as soon as the website and the visitor’s consent allow them. Every event has a category that says what kind of data it is and which collection group of the website it belongs to. This page lists them and shows the calls for everything else. The examples use the script tag’s trustanalytics; with npm, call the same methods on your Analytics instance.

Only names travel, never what a visitor typed, watched or read.

All of them are ordinary events: goals, funnels and Explore use them by name.

What every event carries besides its own data: the page address (filtered as described in Without consent), the page title and the referrer of the page. Every batch also says whether the browser sends Do Not Track or Global Privacy Control and whether it reports being controlled by automation software (navigator.webdriver), and the page leave carries how long the page was actively used, measured from mouse, keyboard, scroll and touch events. The server adds country, region and city, browser and its version, operating system, device class and the language from the address, user agent and Accept-Language header of the request, and discards address and user agent afterwards. Only where Automatic interactions are collected for the visitor does the script also read from the device: time zone, screen and window size, the scroll depth of the page leave, and in Chromium browsers the exact operating system version and, on Android, the device model from the client hints — the user agent of Chromium no longer carries them. Reports of these values show visitors for whom they were not collected as Without consent. While Replace e-mail addresses is on (the default, Settings › Data collection & privacy › Pages), e-mail addresses in a title are replaced, and a page whose path a rule replaces keeps no title; to leave a title out on certain pages, remove pageTitle in beforeSend.

Every click on an interactive element — link, button, form control, summary, [role=button], [data-track], … — is one click event. Give important elements a name:

<button data-track="signup-button">Start free trial</button>

Without data-track the label is the link target (link /pricing), the element id (#cta), the name attribute (button plan) or the tag (button) — never the visible text. Mark custom widgets that do not look interactive with data-ta-interactive. At most 100 clicks per page are reported.

Heatmap data is extra data on the same event, not a second event.

• outbound_click — a link to another site, with host and path, never the query. Hostnames of the website’s linked domains count as the same site.
• file_download — a link with a download or data-ta-download attribute (for endpoints without a file ending), or with a common file ending (pdf, zip, docx, xlsx, csv, mp4, dmg, exe, …). Add your own endings with data-download-extensions="stl,step" / downloadExtensions: ['stl', 'step']. The click is reported, not whether the download finished.
• page_not_found — the browser cannot see the HTTP status of a page, so the page has to say it: add <meta name="ta:404"> to your error page, or call trustanalytics.notFound() from your router’s not-found route. If consent arrives later, the event is sent then.

For every form, the SDK sends form_start (first interaction), form_submit, form_invalid (field and validity reason) and form_abandon (last field touched). Field values are never read.

<form data-ta-form="signup">
  <input name="email" data-ta-field="E-mail">
  <fieldset data-ta-step="Company">…</fieldset>
  <fieldset data-ta-step="Payment">…</fieldset>
</form>
<form data-ta-ignore>…</form>

• data-ta-form and data-ta-field give readable names; data-ta-ignore leaves a form out.
• Multi-step forms: mark each part with data-ta-step. Reaching a part sends form_step once, numbered in page order, and submit and abandon carry the last step plus the field the visitor spent the longest in.
• Confirmed success: a submit is not a success. Call trustanalytics.trackForm('success', 'signup') once your backend accepted the form. form_success therefore exists only as a call (only your site knows it), while form_invalid and form_step exist only automatically (the browser sees them).

• Video and audio: media_play (resumes carry isResume), media_pause, media_progress at 25, 50 and 75 % and media_complete for every <video> and <audio> element. The name is data-ta-media, the id, the title or the source path without query. Players in iframes (YouTube, Vimeo) are not covered; report them with trustanalytics.trackMedia('play', 'intro-video').
• Content blocks: data-ta-content="pricing-faq" reports content_view once half of the block (or half of the screen) was visible for a second, and content_read once its end was on screen and it was visible for ten seconds (data-ta-read-seconds="20" changes that).
• Site search: a term in ?q=, ?query=, ?search=, ?s= or ?keyword= is sent as search three seconds after the page loads. Set other parameters with data-search-params="term,k". To add the result count, call trustanalytics.trackSearch(query, results) within those three seconds — it replaces the detected search; 0 marks a search without results.

• Errors (ERRORS): uncaught errors and unhandled promise rejections with message, stack, page and release, grouped by cause. Report caught errors yourself:

try { … } catch (error) {
  trustanalytics.captureException(error, { feature: 'checkout' });
}

At most 20 errors per page are sent; the server keeps the first occurrence of an error per session.

• Web vitals (WEB_VITALS): LCP, INP, CLS, FCP and TTFB per page, plus the total blocking time (TBT, from long tasks) and the scripts that kept the page busy longest (long animation frames, up to five per page). TBT and blocking scripts are measured in Chromium browsers only, and neither is a Core Web Vital.
• Network (NETWORK_DIAGNOSTICS): fetch and XMLHttpRequest calls that fail (status 0 or 400 and above) or take at least three seconds (data-slow-request-ms), and scripts, stylesheets and images that do not load — including those that failed before the SDK started. Only origin and path travel, never query, body or headers. Requests to the analytics API and aborted requests are left out; at most 30 per page.
• Console (CONSOLE_DIAGNOSTICS): with data-console="true", console.error calls become error groups of type console.error, at most 10 per page. Off by default, because console messages can carry personal data.
• Release: set data-release="2026.11.1" / release so errors and vitals can be compared between versions of your site.

trustanalytics.track('newsletter_signup', { list: 'weekly', position: 2 });

• Names up to 100 characters. Do not reuse the names of the automatic events or identify, purchase and refund — the server treats them by their meaning.
• Up to 50 properties per event with string, number or boolean values (strings up to 500 characters). A value that is a number can be summed or averaged in Explore.
• The category is CUSTOM_EVENTS unless you pass another as third argument, e.g. trustanalytics.track('pricing_toggle', {}, 'AUTOCAPTURE'). The category decides which plan feature and collection group applies and what rules can drop.

// after sign-in
trustanalytics.identify('user-4711', { plan: 'pro' });
// on every page load, for the events of this page
trustanalytics.setSessionProperties({ variant: 'b' });
// on sign-out
trustanalytics.reset();

• identify(userId, properties) links the session to an id of your own system. Never pass an e-mail address or a name — a user id that looks like an e-mail address is ignored while Replace e-mail addresses is on (the default). The session continues; the user properties travel with every further event of the page until reset().
• setSessionProperties(properties) adds properties to every further event of the page. Like the user properties they live in the memory of the page: call it again on every page load, as with identify.
• Precedence: an event’s own properties win over session properties, those over user properties — every event carries the state at the time it happened.
• reset() forgets user, user and session properties, session and visitor id. Call it on sign-out so the next person on the same device starts fresh.
• Consent: user id and user properties belong to the group Recognition and cookie. Where it is not collected for a visitor, events still arrive, but without them, and identify itself is not sent. The server applies the same rule to the user id. Session properties describe the visit — plan, variant, signed in — and belong to Custom events; they must never make a person recognisable.
• Link prior events (website setting): when a visitor identifies, earlier events of the same session get the user id too.
• Nothing is kept in the browser: call identify (or pass userId to start()) on every page load of a signed-in user, the page knows the user anyway.
• Other ids of yours — an attribution id, a customer number, your own session id — travel as user properties, never as session properties.

Where custom events are collected and the plan includes commerce:

trustanalytics.trackCommerce('product_view', { id: 'sku-2041', name: 'Trail running shoe', category: 'Shoes', priceMinor: 2495, currency: 'EUR' });
trustanalytics.trackCommerce('cart_add', { id: 'sku-2041', quantity: 2 });
trustanalytics.trackCommerce('cart_remove', { id: 'sku-2041', quantity: 1 });
trustanalytics.trackCommerce('checkout_start');
trustanalytics.trackCheckoutStep(1, 'Shipping address');
trustanalytics.trackCheckoutStep(2, 'Payment');
trustanalytics.trackPurchase({
  orderId: 'order-10045',
  amountMinor: 5490,
  taxMinor: 877,
  shippingMinor: 490,
  discountMinor: 490,
  coupon: 'AUTUMN10',
  currency: 'EUR',
  products: [
    { id: 'sku-2041', name: 'Trail running shoe', quantity: 2, priceMinor: 2495 },
    { id: 'sku-0007', priceMinor: 500 },
  ],
});

• Amounts are in the minor unit of the currency (cents for EUR); currencies are ISO 4217 codes.
• Checkout steps are numbered from 1 (up to 20) in the order your checkout shows them; the commerce report shows how many sessions reached each one between the checkout start and the purchase.
• Purchases: amountMinor is the total the customer paid — gross, with tax and shipping, after discounts. Pass either itemCount or the order lines as products (up to 50; a line without id or priceMinor is left out). Lines give revenue per product, and the item count becomes the sum of their quantities. An order id counts once per website — a repeated call is dropped as DUPLICATE_ORDER.
• Tax, shipping, discount and coupon are optional: taxMinor and shippingMinor are the parts of amountMinor that are tax and shipping, discountMinor is what was already taken off it (a positive number), coupon is the code the customer redeemed (cut after 100 characters). They are stored with the order as your shop reports them; amountMinor keeps its meaning and is never computed from them. An amount below 0 or above 1000000000000 drops the purchase as MALFORMED, like an amountMinor outside that range.
• Confirmed orders and refunds belong to your server. A browser purchase can be blocked, lost or faked; send the confirmed order from your backend through the server API and pass trustanalytics.getPageViewId() along with the order so it joins this visit:

await fetch('/api/orders', { method: 'POST', body: JSON.stringify({ …order, analyticsPageViewId: trustanalytics.getPageViewId() }) });

• Browser and server together: a server purchase replaces the browser purchase of the same order id, never the other way round. If the server purchase has no order lines, the lines of the browser purchase are kept. Refunds — full or partial — are server events only.

Where custom events are collected and the plan includes experiments, report when a visitor sees a variant:

trustanalytics.exposeExperiment('pricing-headline', 'variant-b');

TrustAnalytics does not assign variants — your site or testing tool does. The experiment report compares every variant with the one called control (otherwise the first by name), counted from the first exposure. A visitor (or a session, without a visitor id) that saw two variants of one experiment is left out.