Tracking SDK

JavaScript SDK

Install and configure the TrustData JavaScript SDK.

Installation

Standard installation

Add this snippet before the closing </head> tag:

<script>
(function(w,d,s,u,n){
  w[n]=w[n]||[];
  w[n].push(['init','ATTRIBUTION_ID',{sendPageView:true}]);
  var f=d.getElementsByTagName(s)[0],j=d.createElement(s);
  j.async=1;j.src=u;f.parentNode.insertBefore(j,f);
})(window,document,'script','https://t.trustdata.tech/t.js','trustdata');
</script>

Replace ATTRIBUTION_ID with your Attribution's ID from the dashboard.

NPM installation

npm install @trustdata/sdk

import trustdata from '@trustdata/sdk';

trustdata.init('ATTRIBUTION_ID', {
  sendPageView: true
});

Configuration options

trustdata.init('ATTRIBUTION_ID', {
  // Send a pageview event on initialization
  sendPageView: true,

  // Initial consent state
  consent: {
    analytics: false,
    advertising: false,
    preferences: false,
    sale_of_data: false
  },

  // Domains to ignore for referrer tracking
  ignoreDomains: ['stripe.com', 'paypal.com'],

  // Event server endpoint (default: TrustData cloud)
  apiHost: 'https://t.trustdata.tech'
});

Configuration reference

Option	Type	Default	Description
`sendPageView`	boolean	`true`	Send pageview on init
`consent`	object	all `false`	Initial consent state (4 levels)
`ignoreDomains`	array	`[]`	Domains to exclude from referrer
`apiHost`	string	`https://t.trustdata.tech`	Event server endpoint

API methods

trustdata.event(name, props)

Track custom events:

trustdata.event('button_click', {
  button_id: 'signup',
  page: '/pricing'
});

trustdata.event('add_to_cart', {
  id: 'SKU123',
  value: 49.99
});

trustdata.consent(options)

Update consent state:

// Grant all consent
trustdata.consent({
  analytics: true,
  advertising: true
});

// Revoke advertising consent
trustdata.consent({
  analytics: true,
  advertising: false
});

trustdata.setUserId(id)

Associate events with a known user:

// After user logs in
trustdata.setUserId('user_123');

The user ID persists across sessions and is used for cross-device attribution.

trustdata.getVisitorId()

Get the current visitor's anonymous ID:

const visitorId = trustdata.getVisitorId();
console.log(visitorId); // "v_abc123..."

trustdata.setUser(data)

Set customer data for enhanced conversions. Fields are sent with conversion events to improve match rates on ad platforms.

trustdata.setUser({
  email: '[email protected]',
  phone: '+15551234567',        // E.164 format
  first_name: 'Jane',
  last_name: 'Doe',
  address: {
    city: 'Paris',
    postal_code: '75001',
    country: 'FR'              // ISO 3166-1 alpha-2
  }
});

trustdata.clearUser()

Clear stored user data (e.g., on logout):

trustdata.clearUser();

Links the anonymous pre-consent fingerprint (fp_xxx) to the new cookie-based visitor ID after a consent upgrade. This ensures touchpoints captured before consent (landing pages, ad clicks) are still attributed to the eventual conversion.

The GTM template calls this automatically when analytics_storage is granted. Only call it manually if you manage consent outside GTM:

// After the user grants analytics consent
trustdata.consent({ analytics: true });
trustdata.linkIdentity(); // sends identity_link event, no-op if no ID transition

trustdata.debug(enabled)

Enable or disable debug logging:

trustdata.debug(true);  // Enable debug mode
trustdata.debug(false); // Disable debug mode

Debug output:

[TrustData] Initialized with attribution_id: TD-abc123
[TrustData] Pageview: /products/widget
[TrustData] Event: add_to_cart {id: "SKU123", value: 49.99}

Identity and storage

The SDK keeps a stable visitor identity so touchpoints can be linked to later conversions. Storage is only written once the visitor grants analytics consent.

Key	Where	Lifetime	Purpose
`_trdt_vid`	First-party cookie + `localStorage`	365 days	Visitor ID
`_trdt_uid`	`localStorage`	Until cleared	User ID set via `setUserId`
`_trdt_adblock`	`localStorage`	Session	Cached adblock detection result

A few details worth knowing:

Consent gating. Before analytics consent, nothing is stored. The SDK uses a short-lived fp_ fingerprint so anonymous visits are still counted, then linkIdentity() stitches that fingerprint to the new _trdt_vid once consent is granted.
Cross-subdomain. On a multi-level domain the cookie is set on the registrable domain (for example Domain=.example.com), so identity is shared across www, shop, and other subdomains. On localhost or raw IPs the domain attribute is omitted.
Server fallback. When a site routes tracking through a reverse proxy on its own domain, the event server can set an HttpOnly _td_vid cookie as an ITP-resilient fallback. This is only sent for proxied requests, never on the default tracking domain.

Single page applications (SPA)

For SPAs, track pageviews on route changes:

// React Router example
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    trustdata.event('page_view', {
      path: location.pathname
    });
  }, [location]);

  return <Routes>...</Routes>;
}

// Vue Router example
router.afterEach((to) => {
  trustdata.event('page_view', {
    path: to.path
  });
});

Integrate with your consent management platform:

// Initialize without automatic page_view
trustdata.init('ATTRIBUTION_ID', {
  sendPageView: false,
  consent: {
    analytics: false,
    advertising: false
  }
});

// After user grants consent
function onConsentGranted() {
  trustdata.consent({
    analytics: true,
    advertising: true
  });
  trustdata.linkIdentity(); // links pre-consent fingerprint to new cookie ID
  trustdata.event('page_view');
}

// If user only grants analytics consent
function onAnalyticsOnlyConsent() {
  trustdata.consent({
    analytics: true,
    advertising: false
  });
  trustdata.linkIdentity();
  trustdata.event('page_view');
}

Overview

First-party event tracking with full visibility, including consent rates and adblock detection.

Events reference

Track page views and conversions with TrustData.