Skip to main content

Initialization and configuration

caution
You are reading documentation for an outdated version. Here’s the latest one!

Tracker initialization is started by calling the "newTracker" function and takes three arguments:

  1. The tracker namespace (sp in the below example)
  2. The collector endpoint
  3. An optional configuration object containing other settings

Here is a simple example of how to initialise a tracker, setting a few configuration options:

snowplow('newTracker', 'sp', '{{collector_url_here}}', {
  appId: 'my-app-id',
  discoverRootDomain: true,
  cookieSameSite: 'Lax', // Recommended
  contexts: {
    webPage: true // default, can be omitted
  }
});

The tracker will be named sp (tracker namespace) and will send events to the a collector url you specify by replacing {{collector_url_here}}. The final argument is the configuration object. Here it is just used to set the app ID and the common webPage context for each event. Each event the tracker sends will have an app ID field set to “my-app-id”.

If newTracker is called multiple times with the same namespace, only the first call is taken into account.

For Single Page Apps

Initialize one tracker per initial page load.

The following table shows all the various configuration parameters. Note that these are all optional. In fact, you aren’t required to provide any configuration object at all.

PropertyDescriptionDefault (if applicable)Type
appIdSet the application ID.string
platformSet the application platform."web"string enum
cookieDomainSet the cookie domain.
discoverRootDomainAutomatic discovery and setting of the root domain, to facilitate tracking over multiple subdomains.trueboolean
cookieNameSet the cookie name.string
cookieSameSiteSet the cookie samesite attribute.nullstring enum
cookieSecureSet the cookie secure attribute.trueboolean
encodeBase64Enable Base64 encoding for JSONs (context entities and custom self-describing events).trueboolean
respectDoNotTrackChoose to respect browser Do Not Track option.falseboolean
eventMethodChoose to send events by GET, POST, or Beacon API.poststring enum
bufferSizeHow many events to send in one request.1int
maxPostBytesSet a limit for the size of one request.40000int
maxGetBytesSet a limit for the size of one request.int
postPathChange the collector POST path.string
crossDomainLinkerDecorate links for cross-domain tracking.function
cookieLifetimeSet the cookie lifetime.63072000 s (2 years)int
stateStorageStrategyHow to store tracker state.cookieAndLocalStoragestring enum
maxLocalStorageQueueSizeHow many events to queue in local storage when they are failing to send.1000int
resetActivityTrackingOnPageViewChoose to reset page ping timers when a page view is tracked.trueboolean
connectionTimeoutSet request connection timeout.5000 msint
anonymousTrackingDo not track user identifiers.falseboolean
customHeadersAdd custom headers to requests.object
withCredentialsChoose whether to use the withCredentials flag in collector requests.trueboolean
contextsConfigure context entities to add to all events.variousobject
retryStatusCodesSet HTTP response codes to retry requests on.[int]
dontRetryStatusCodesSet HTTP response codes not to retry requests on.[int]
retryFailedRequestsChoose to retry failed requests or not.trueboolean
onSessionUpdateCallbackA callback to run every time the session updates.function
onRequestSuccessA callback to run every time a request is successfully sent to the collector.function
onRequestFailureA callback to run every time a request fails to send.function
preservePageViewIdForUrlOption to change when a new page view ID is generated. Makes it possible to generate a new page view on URL change instead of when tracking a page view, which enables tracking events before the page view event with the same ID.falsefalse, true, full, pathname, pathnameAndSearch

Here is a longer code example in which every tracker configuration parameter is set:

snowplow('newTracker', 'sp', '{{collector_url_here}}', {
  appId: 'my-app-id',
  platform: 'web',
  cookieDomain: null,
  discoverRootDomain: true,
  cookieName: '_sp_',
  cookieSameSite: 'Lax', // Recommended
  cookieSecure: true,
  encodeBase64: true,
  respectDoNotTrack: false,
  eventMethod: 'post',
  bufferSize: 1,
  maxPostBytes: 40000,
  maxGetBytes: 1000, // available in v3.4+
  postPath: '/custom/path', // Collector must be configured
  crossDomainLinker: function (linkElement) {
    return (linkElement.href === 'http://acme.de' || linkElement.id === 'crossDomainLink');
  },
  cookieLifetime: 63072000,
  stateStorageStrategy: 'cookieAndLocalStorage',
  maxLocalStorageQueueSize: 1000,
  resetActivityTrackingOnPageView: true,
  connectionTimeout: 5000,
  anonymousTracking: false,
  // anonymousTracking: { withSessionTracking: true },
  // anonymousTracking: { withSessionTracking: true, withServerAnonymisation: true },
  customHeaders: {}, // Use with caution. Available from v3.2.0+
  withCredentials: true, // Available from v3.2.0+
  contexts: {
    webPage: true, // Default
    session: false, // Adds client session context entity to events, off by default. Available in v3.5+.
    browser: false, // Adds browser context entity to events, off by default. Available in v3.9+.
    performanceTiming: true,
    gaCookies: true,
    geolocation: false,
    clientHints: true,
    // clientHints: { includeHighEntropy: true }, // Optional
  },
  retryStatusCodes: [],
  dontRetryStatusCodes: [],
  retryFailedRequests: true,
  onSessionUpdateCallback: function(clientSession) { }, // Allows the addition of a callback, whenever a new session is generated. Available in v3.11+.
  onRequestSuccess: function(data) => { }, // Available in v3.18.1+
  onRequestFailure: function(data) => { }, // Available in v3.18.1+
});

You can further extend the tracker functionality by installing plugins. Read more about them here.