JavaScript

RudderStack's JavaScript SDK leverages the rudder-analytics.js library to track and send user events from your website to RudderStack. You can then further transform and route this event data to the destination platform of your choice.

Installing the SDK

To quickly set up and start using the RudderStack JavaScript SDK, go through our quick start guide.

Supported APIs

The JavaScript SDK makes it very easy for you to send your event data to any destination without implementing a new API every time.

The following sections detail all the API calls supported by RudderStack for this SDK.

Load

The load method loads the rudder-analytics.js file with the source write key. It is defined as follows:

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

Write key and data plane URL

To integrate and initialize the JavaScript SDK, you need the source write key and the data plane URL.

• To get the source write key, follow this guide.

• To get the data plane URL, follow this guide.

The options parameter

The options parameter in the above load call looks like the following:

Copy
{
  logLevel: "DEBUG" | "INFO" | "WARN",
  integrations: IntegrationOpts,
  configUrl: string,  // defaults to https://api.rudderlabs.com
  queueOptions: QueueOpts,
  loadIntegration: boolean // defaults to true.
}

It includes the following details:

For more details, refer to the section on the options parameter.

Loading the SDK for self-hosted control plane

If you are self-hosting the control plane using the RudderStack Control Plane Lite utility, your load call will look like the following:

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

Loading selective destinations

RudderStack lets you send your event data to selective destinations specified by you and disable sending events to the rest of the destinations. You can specify these destinations through the load call, as shown in the following snippet:

Copy
rudderanalytics.load(<WRITE_KEY>, <DATA_PLANE_URL>, {
  integrations: { All: false, destination_name: true },
});

For more information, check the Filtering selective destinations section.

Identify

The identify method allows you to link the users and their actions to a specific userid. You can also add additional information as traits to a user. Once the identify call is made, the SDK persists the user information and passes it to the subsequent track or page calls.

To reset the user identification, you can use the reset method.

The SDK defines the identify method as shown below:

Copy
rudderanalytics.identify(userId, [traits], [options], [callback]);

The identify method has the following parameters:

A sample identify call is shown below:

Copy
rudderanalytics.identify(
  "userId",
  { email: "name@domain.com" },
  {
    page: {
      path: "",
      referrer: "",
      search: "",
      title: "",
      url: ""
    }
  },
  () => {
    console.log("Sample identify call");
  }
);

In the above example, information such as the userId and email along with the contextual information is captured.

anonymousId

The anonymousId is a UUID (Universally Unique Identifier) generated to uniquely identify the user.

For more information on the setAnonymousId method, refer to the Overriding the anonymousId using setAnonymousId section below.

How RudderStack uses anonymousId

The JavaScript SDK generates a unique anonymousId, stores it in a cookie named rl_anonymous_id in the top-level domain, and attaches to every subsequent event. This helps RudderStack in identifying the unknown users from other sites that are hosted under a sub-domain.

For example, if you include the RudderStack JavaScript SDK in both admin.samplewebsite.com and app.samplewebsite.com, the SDK will store the cookie in the top-level domain samplewebsite.com.

There are two options that you can use to identify anonymous users with the JavaScript SDK:

Overriding anonymousId in the options parameter

There can be scenarios where you may want to provide your own anonymousId instead of an SDK-generated ID. To do so, you can provide the anonymousId in the options parameter of the identify call, as mentioned above. This will send the value provided by you in the anonymousId key of the event.

An example of this approach is as shown in the code snippet below:

Copy
rudderanalytics.identify(
  "12345",
  { email: "name@domain.com" },
  {
    anonymousId: "my-anonymous-id"
  },
  () => {
    console.log("in identify call");
  }
);

Overriding the anonymousId using setAnonymousId

You can also override the anonymousId for all the future events using the setAnonymousId() method.

An example of this is shown in the following snippet:

Copy
rudderanalytics.setAnonymousId("my-anonymous-id");

// All event payloads will have the anonymousId key set "my-anonymous-id".
rudderanalytics.identify("userId", { email1: "name@domain.com" }, () => {
  console.log("in identify call");
});

Using AMP Analytics

You can also parse the AMP Linker ID and set the anonymousId, as shown:

Copy
rudderanalytics.setAnonymousId(
  null,
  "<version>*<checkSum>*<idName1>*<idValue1>*<idName2>*<idValue2>..."
);

Here, the second parameter is the AMP Linker ID format in accordance with the specified structure. For the links decorated with the RudderStack Linker parameter, the <idName1> value will be rs_amp_id.

Calling the above method will parse the Linker ID and set the anonymousId as the value of the rs_amp_id key.

Setting a blank userId

If you would like to set a blank userid, pass an empty string or " ".

Use-case

Suppose an anonymous user is identified with a userid and then logs out of their account. You can then identify("", {isLoggedIn: false}) and the user will continue to be identified by their anonymousId for future events.

Identifying new users

To identify new users in scenarios like new logins, you can take one of the following two approaches:

Calling the identify API with a new userid

In this case, RudderStack will reset all the cookies related to the user associated with the userid and traits and update them with the new values provided by you.

Explicitly calling reset followed by identify

This approach has the exactly same outcome as described in the first approach.

Updating user traits

For updating the user traits, you can call identify with the same userId multiple times with the new traits. This results in all the traits associated with that user getting appended or modified. An example is shown below:

Copy
rudderanalytics.identify("userId", { email1: "name@domain.com" }, () => {
  console.log("in identify call");
});

rudderanalytics.identify("userId", { email2: "name@domain.com" }, () => {
  console.log("in identify call");
});

In the above example, both email1 and email2 will be sent in the payload for the second identify call.

Page

The page call lets you record your website's page views with any additional relevant information about the viewed page.

The page() method is defined as follows:

Copy
rudderanalytics.page(category, name, [properties], [options], [callback]);

The page method has the following parameters:

A sample page() call is shown below:

Copy
rudderanalytics.page(
  "Cart",
  "Cart Viewed",
  {
    path: "",
    referrer: "",
    search: "",
    title: "",
    url: ""
  },
  () => {
    console.log("in page call");
  }
);

In the above example, the SDK also captures the information such as the page category and page name along with the contextual information.

Track

The track call lets you record the customer events, i.e. the actions that they perform, along with any properties associated with those actions.

The SDK defines the track() method as follows:

Copy
rudderanalytics.track(event, [properties], [options], [callback]);

The track method has the following parameters:

A sample track call is as shown:

Copy
rudderanalytics.track(
  "test track event GA3",
  {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  },
  () => {
    console.log("in track call");
  }
);

In the above example, the method tracks the event test track event GA3 along information like the revenue, currency, and the user ID.

Alias

Many destination platforms need an explicit alias call for mapping the already identified users to a new identifier that you may want to use, to track them in the future. The alias call lets you implement this functionality.

The SDK defines the alias() method as shown:

Copy
rudderanalytics.alias(to, from, [options], [callback]);

The alias call has the following parameters:

A sample alias() method is shown below:

Copy
rudderanalytics.alias("test_new_id", "old_user_id", () => {
  console.log("alias call");
});

Group

The group call lets you link an identified user with a group such as a company, organization, or an account. It also lets you record any custom traits associated with that group such as the name of the company, the number of employees, etc.

The group() method is defined as shown below:

Copy
rudderanalytics.group(groupId, [traits], [options], [callback]);

The group method has the following parameters:

A sample group() call is as shown:

Copy
rudderanalytics.group("sample_group_id", {
  name: "CompanyA",
  location: "USA",
});

Reset

The reset method resets the userId and the associated user traits and properties.

The following snippet shows an example of the reset() method:

Copy
rudderanalytics.reset();

Parameter definitions

This section details the type definitions of the parameters used in some of the API methods described above:

options

The structure of options parameter is as shown:

Copy
{
  integrations: IntegrationOpts,
  anonymousId: string,
  originalTimestamp: ISO 8601 date string,
  <other keys>: <value> // merged with event's contextual information
}

The following table describes each of the above parameters in detail:

IntegrationOpts

The structure of IntegrationOpts looks like the following:

Copy
{
  All: boolean, // default true
  <Destination1>: boolean,
  <Destination2>: boolean,
  ...
}

The following table describes each of the above parameters in detail:

More information on using IntegrationOpts can be found in the Filtering selective destinations section.

QueueOpts

The structure of QueueOpts is shown below:

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

The following table describes each of the above parameters in detail:

Adding callbacks to standard methods

RudderStack lets you define callbacks to the common methods of the rudderanalytics object.

An example is shown below:

Copy
<script>
rudderanalytics.syncPixelCallback = obj => {
  rudderanalytics.track(
    "sync lotame",
    {
      destination: obj.destination
    },
    {
      integrations: {
        All: false,
        S3: true
      }
    }
  );
};
</script>

<script src="https://cdn.rudderlabs.com/rudder-analytics.min.js"></script>

In the above example, RudderStack defines a syncPixelCallback on the rudderanalytics object loading the SDK. This will lead to RudderStack calling this registered callback with the parameter {destination: <destination_name>} whenever a sync call is made from the SDK to the relevant integrations, e.g. Lotame.

You can also add the callback in the options parameter as shown below:

Copy
rudderanalytics.load(<WRITE_KEY>, <DATA_PLANE_URL>, {
  clientSuppliedCallbacks: {
    syncPixelCallback: () => {
      console.log("sync done!");
    },
  },
});

Filtering selective destinations

RudderStack lets you load or send your event data to only the destinations specified by you. You can do so by passing an integrations object in the options parameter of the API methods. RudderStack then loads or sends events only to those destinations that are specified and enabled.

The format of the load method with the integration names passed as arguments is as shown:

Copy
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
  integrations: {
    All: false,
    destination_name: true
  }
});

Here, <destination_name> is the name of the destination.

Examples

• The format of the track method with the integration names passed as arguments is as shown below:

Copy
rudderanalytics.track(
  "test track event GA3",
  {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  },
  {
    integrations: {
      All: false,
      destination_name: true
    }
  }
);

• The following example shows how to load only the Google Analytics and Intercom destinations:

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

• The following example highlights how you can send the track type of events only to Google Analytics:

Copy
rudderanalytics.track(
  "test track event GA3",
  {
    revenue: 30,
    currency: "USD",
    user_actual_id: 12345
  },
  {
    integrations: {
      All: false,
      "Google Analytics": true
    }
  }
);

Common destination names

The following table lists some of the popular destinations along with their supported names that RudderStack uses as values when sending the event data.

Context and traits

RudderStack gives you the option to automatically capture certain event-specific and user-specific data, based on the type of the event.

In this section, we cover two specific dictionaries within the options parameter included in the supported API methods.

Context

A context is a dictionary of additional information about a particular event data, such as a user’s locale.

Traits

Traits is an optional dictionary included within context which specifies the user's unique traits. This is a very useful field for linking the user's information from a previously made identify() call to the subsequent track() or page() calls.

Use-case

To better understand how contexts and traits work, refer to the following identify event:

Copy
rudderanalytics.identify("userId", {
  plan: "Paid, Premium",
  email: "name@surname.org"
});

The trait in the above event is plan. If you wish to include this trait in a subsequent track() or page()event triggered by the user, you can establish the association by passing it in context.traits as shown:

Copy
rudderanalytics.track(
  "Subscribed",
  {
    campaign: "Subscribe"
  },
  {
    context: {
      traits: {
        plan: "Paid, Premium"
      }
    }
  }
);

The above snippet will append plan as a trait to the track event. Note that the trait email will not be appended, as it was not specified in the context.traits field.

FAQs

Refer to the FAQs section for solutions to some of the commonly faced issues while using the JavaScript SDK on your website.

Contact us

For more information on any of the sections covered in this guide, you can contact us or start a conversation on our Slack channel.

If you come across any issues while using this SDK, feel free to submit them on our GitHub issues page.