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:

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

Loading options

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

Copy
{
  logLevel: "DEBUG" | "INFO" | "WARN",
  integrations: IntegrationOpts,
  configUrl: string,  // defaults to https://api.rudderlabs.com
  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.
}

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:

Copy
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: boolean, // default true
    <Destination1>: boolean, // specify destination like Google Analytics, Amplitude etc.
    <Destination2>: boolean, // specify destination like Google Analytics, Amplitude etc.
    ...
  }
});

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 Google Analytics and Intercom destinations:

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

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:

Copy
{
  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. 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, as shown:

Copy
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:

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

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

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:

Copy
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:

Copy
{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).

You can refer to the Getting started section of the specific destination's documentation to obtain the domain that might need to be allowlisted.

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).

Copy
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.