You are viewing documentation for an older version.

Click here to view the latest documentation.

Load JavaScript SDK

You can load the JavaScript SDK using the load API method to track and send events from your website to RudderStack. It can be defined as:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, [loadOptions]);

Replace the write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. and data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL in the home page of your RudderStack dashboard. with their actual values in the snippets (wherever applicable) throughout this guide.

Loading options

You can use loadOptions in the above load call to define various options while loading the SDK. It includes the following parameters:

{
  logLevel: "DEBUG" | "INFO" | "WARN",
  integrations: IntegrationOpts,
  configUrl: string,  // defaults to https://api.rudderlabs.com
  getSourceConfig: function,
  queueOptions: QueueOpts,
  loadIntegration: boolean, // defaults to true.
  sessions: SessionOpts,
  secureCookie: boolean, // defaults to false.
  destSDKBaseURL: string, // defaults to https://cdn.rudderlabs.com/v1.1/js-integrations
  useBeacon: boolean, // defaults to false.
  beaconQueueOptions: BeaconQueueOpts,
  cookieConsentManager: cookieConsentManager,
  anonymousIdOptions: AnonymousIdOptions,
  setCookieDomain: string, // defaults to current domain.
  sameSiteCookie: "Strict" | "Lax" | "None", // defaults to Lax.
  lockIntegrationsVersion: boolean, // defaults to false.
  polyfillIfRequired: boolean, // defaults to true.
  onLoaded: callback function,
  uaChTrackLevel: "none" | "default" | "full", // defaults to None.
  sendAdblockPage: boolean,
  sendAdblockPageOptions: object,
  useGlobalIntegrationsConfigInEvents: boolean // defaults to false.
  sameDomainCookiesOnly: boolean // defaults to false.
}

The detailed description of these parameters is as follows:

The following sections contain the detailed definitions and usage of some of the above parameters:

IntegrationOpts

You can use this parameter to send the event data only to the selective destinations. Its structure is defined as follows:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: boolean, // default true
    <Destination1>: boolean, // or object.
    <Destination2>: boolean, // or object.
    ...
  }
});

The following table describes the above (optional) parameters in detail:

You must specify the actual destination name (as listed in the RudderStack dashboard) in the <Destination> parameter and not the name you have assigned to the destination. For example, the below sample snippet sends the event data only to Amplitude and Intercom destinations:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
    integrations: {
        All: false,
        "Amplitude": true,
        "Intercom": true
    }
});

getSourceConfig

The getSourceConfig function returns the custom configuration which can be used in place of control plane’s dashboard configuration:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  getSourceConfig: function() {
    return {
      // custom configuration
    };
  },
  // other load options
});

QueueOpts

The queueOpts object contains the options to control the behavior of the persistence queue that buffers the events before sending them to RudderStack. Its structure is defined as follows:

{
  maxRetryDelay: 360000,
  minRetryDelay: 1000,
  backoffFactor: 2,
  maxAttempts: 10,
  maxItems: 100,
}

The following table describes the above integer type (optional) parameters in detail:

SessionOpts

The SessionOpts object contains the options related to the SDK’s automatic session tracking behavior. Refer to the Session Tracking guide for more information. Its structure is defined as follows:

cookieConsentManager

Once a user provides the consent, you can load the JavaScript SDK and enable the OneTrust integration via the cookieConsentManager object:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  cookieConsentManager: {
    oneTrust: {
      enabled: true
    }
  }
});

anonymousIdOptions

You can use the anonymousIdOptions object to automatically capture the anonymous ID from a source and set it as RudderStack’s anonymousId.

For example, if you are migrating from a particular source and want to retain its anonymous ID, you can enable the anonymousIdOptions to set the source’s anonymous ID as the anonymousId in RudderStack.

The structure of anonymousIdOptions is defined as follows:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  anonymousIdOptions: {
    autoCapture: {
      enabled: true,
      source: "segment"
    }
  }
});

The following table describes the above (required) parameters in detail:

If the RudderStack anonymousId is already set in your browser, anonymousIdOptions will not take effect.

You can call the reset API to clear the persisted anonymous ID and force the SDK to generate a new ID when the next tracking API is called (irrespective of whether anonymousIdOptions is enabled or disabled). However, if the anonymousIdOptions object is enabled and the SDK is loaded again (as a result of webpage reload, navigate to a different webpage, etc.), the setAnonymousId call will trigger automatically and the specified source’s anonymous ID will again be set as the RudderStack anonymousId.

uaChTrackLevel

You can use the uaChTrackLevel option to configure the information a user should get in the context object regarding the client hints. The JavaScript SDK fetches this information using the user-agent client hints API. It can take the below values:

• none: Specifies that uaChTrackLevel field is absent in the context object.
• default: Specifies that uaChTrackLevel field is present in the context object and contains an object similar to the one below:

{
  "brands": [{
    "brand": "Chromium",
    "version": "110"
  }, {
    "brand": "Not A(Brand",
    "version": "24"
  }, {
    "brand": "Google Chrome",
    "version": "110"
  }],
  "mobile": false,
  "platform": "macOS"
}

• full: Specifies that uaChTrackLevel field is present in the context object and contains an object similar to the one below:

{
  "architecture": "arm",
  "bitness": "64",
  "brands": [{
    "brand": "Chromium",
    "version": "110"
  }, {
    "brand": "Not A(Brand",
    "version": "24"
  }, {
    "brand": "Google Chrome",
    "version": "110"
  }],
  "fullVersionList": [{
    "brand": "Chromium",
    "version": "110.0.5481.77"
  }, {
    "brand": "Not A(Brand",
    "version": "24.0.0.0"
  }, {
    "brand": "Google Chrome",
    "version": "110.0.5481.77"
  }],
  "mobile": false,
  "model": "",
  "platform": "macOS",
  "platformVersion": "13.1.0",
  "uaFullVersion": "110.0.5481.77",
  "wow64": false
}

onLoaded

The onLoaded callback function takes the rudderanalytics instance as an argument and executes after the JavaScript SDK loads and before the native device-mode destination SDKs are loaded.

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  onLoaded: function(rudderanalytics) {
    console.log("All set!");
  }
});

useGlobalIntegrationsConfigInEvents

You can use this option to use the integrations object of the load method at the event level when it is not present at the event level.

For example, if the integrations object is defined in the load method and the useGlobalIntegrationsConfigInEvents option is set to true:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: true,
    "Google Analytics": false,
    ...
  },
  useGlobalIntegrationsConfigInEvents: true,
  // other load options
});

Case 1: integrations option is present at the event level:

rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  }, {
    integrations: {
      All: true,
      Amplitude: false
    },
  },
  () => {
    console.log("track call");
  }
);

In this case, the JavaScript SDK uses the integrations option from the track event.

Case 2: integrations option is not present at the event level:

rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  }, {},
  () => {
    console.log("track call");
  }
);

In this case, the SDK uses the integrations option from the load method.

Loading SDK for self-hosted control plane

If you are self-hosting the control plane using the Control Plane Lite utility, the load call should be made as below:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  configUrl: < CONTROL_PLANE_URL > ,
});

Verifying if the SDK has loaded correctly

You can verify if the JavaScript SDK has loaded correctly by opening the JavaScript console in your browser:

• Safari: Ctrl+Alt+I (Windows) or Command+Option+I (Mac) and go to the Console tab.
• Chrome: Ctrl+Shift+J (Windows) or Command+Option+J (Mac).
• Firefox: Ctrl+Shift+K (Windows) or Command+Option+K (Mac) and select the Console tab.
• Internet Explorer: Press F12 and go to the Console tab.

Run the rudderanalytics command in the console. If it returns the following code snippet, it means that the analytics.js file has loaded successfully:

{Integrations: Object, _integrations: Object, _readied: true, _timeout: 300, _user: n_}

If it gives an undefined error, you need to verify the SDK installation.

Allowlist destination domain

While using the JavaScript SDK with destinations supporting the device mode, you might need to allowlist the domain from where the destination SDK will load in your content security policy (CSP).

A content security policy adds an extra layer of protection from any type of cross-site scripting, clickjacking, and data injection attacks.

See the specific destination’s documentation to obtain the domain to be allowlisted. For example, Braze.

RudderStack expects the following (minimum) CSP header configuration to load the JavaScript SDK without any errors:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline' https: //cdn.rudderlabs.com/ https://cdn.rudderstack.com/;">

If you don’t want to allow unsafe inline and use the CDN package with its loading snippet, use nonce attribute to the script tag for the loading snippet:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'nonce-rAnd0m' https: //cdn.rudderlabs.com/ https://cdn.rudderstack.com/;">

In case you use the npm package, no inline loading snippet is required:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' https: //cdn.rudderlabs.com/ https://cdn.rudderstack.com/;">

Tracking user sessions

By default, the JavaScript SDK automatically tracks the user sessions. This means that RudderStack automatically determines the start and end of a user session depending on the inactivity time configured in the SDK (default time is 30 minutes).

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  sessions: {
    autoTrack: true,
    timeout: 10 * 60 * 1000,  // 10 min in milliseconds
  },
  ...<otherLoadOptions>
});

To disable automatic session tracking, you can set the load option autoTrack to false.

For more information on the user sessions and how to track them using the JavaScript SDK, refer to the Session Tracking guide.

Questions? Contact us by email or on Slack