You are viewing documentation for an older version.

Click here to view the latest documentation.

JavaScript SDK API

The JavaScript SDK provides a comprehensive API that lets you track and send your event data to any destination.

Identify

The identify method lets you identify a user and associate them to their actions. It also lets you record any traits about them like their name, email, etc.

Once you make the identify call, the SDK persists the user information and passes it to the subsequent calls.

The JavaScript SDK defines the identify method as shown:

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

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

apiOptions

The structure of the apiOptions parameter is as shown:

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

The following table describes the above parameters in detail:

A sample identify call is shown below:

rudderanalytics.identify(
  "1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
    firstName: "Alex",
    lastName: "Keener",
    email: "alex@example.com",
    phone: "+1-202-555-0146"
  }, {
    page: {
      path: "/best-seller/1",
      referrer: "https://www.google.com/search?q=estore+bestseller",
      search: "estore bestseller",
      title: "The best sellers offered by EStore",
      url: "https://www.estore.com/best-seller/1"
    }
  },
  () => {
    console.log("identify call");
  }
);

In the above example, the JavaScript SDK captures the userId, email and the contextual information.

If you specify the IP address in the event payload, RudderStack uses that instead of automatically capturing it in the backend. You can use this feature to anonymize your users’ IP addresses.

Anonymous ID

The anonymousId is an auto-generated UUID (Universally Unique Identifier) that gets assigned to each unique and unidentified visitor to your website.

Retrieving anonymous ID

To retrieve the anonymous ID of any visitor, run the following:

rudderanalytics.getAnonymousId();

If the anonymousId is null in the SDK and you call the above function, RudderStack will automatically set a new anonymousId.

How the SDK uses anonymousId

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

If you identify a user with your application’s unique identifier like email, database ID, etc., RudderStack stores this ID in the rl_user_id cookie and attaches it to every event.

Refer to the Data Storage guide for more information on how the JavaScript SDK stores persistent user data in cookies.

Overriding anonymous ID

You can use any of the following three methods to override the anonymousId generated by the JavaScript SDK:

• Provide the anonymousId in the apiOptions parameter of the identify call.

Note that all other events will have the anonymousId persisted from the cookie except the particular event where you override the apiOptions parameter.

An example is shown below:

rudderanalytics.identify(
  "1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
    email: "alex@example.com"
  }, {
    anonymousId: "my-anonymous-id"
  },
  () => {
    console.log("identify call");
  }
);

• Set the anonymousId for all future events using the setAnonymousId() method. An example is shown below:

rudderanalytics.setAnonymousId("my-anonymous-id");
// All event payloads will have the anonymousId key set "my-anonymous-id".
rudderanalytics.identify("1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
  email1: "alex@example.com"
}, () => {
  console.log("identify call");
});

• Parse the AMP Linker ID and set the anonymousId using AMP Analytics:

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

Here, the second parameter is the AMP Linker ID format in the specified structure. For websites using the RudderStack AMP Analytics SDK, the <idName1> value will be rs_amp_id.

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

Setting a blank user ID

To set a blank user ID, you can pass an empty string or " " to userId.

Do not pass an identify call with null as RudderStack will not allow you to pass a traits object and retain the current userId.

Use-case

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

Identifying new users

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

• Call identify with a new userId
  OR
• Call reset followed by the identify

RudderStack resets all cookies related to the user (associated with the userId and traits) and updates them with the newly provided values.

The anonymousId will remain unchanged in this case. It will be the auto-generated value set by the SDK or the one explicitly set using the setAnonymousId method.

Updating user traits

For updating the user traits, you can call identify method with the same userId multiple times with the new traits. This will append or modify all traits associated with that user. An example is shown below:

rudderanalytics.identify("1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
    email1: "alex@example.com"
}, () => {
    console.log("identify call");
});

rudderanalytics.identify("1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
    email2: "john@example.com"
}, () => {
    console.log("identify call");
});

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

Calling reset() method resets the existing user traits and calling identify() method with new traits updates the new user traits.

Setting a custom user ID

You can pass a custom userId along with the standard userId in your identify call. RudderStack adds this value under context.externalId.

The following code snippet highlights how you can add an externalId to your identify request:

rudderanalytics.identify(
  "1hKOmRA4GRlm", {
    firstName: "Alex",
    city: "New Orleans",
    country: "Louisiana",
    phone: "+1-202-555-0146",
    email: "alex@example.com",
    custom_flavor: "chocolate",
  } {
    externalId: [{
      id: "some_external_id_1",
      type: "brazeExternalId",
    }, ],
  }
);

Page

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

Many destinations require the page call to be made at least once every page load.

The JavaScript SDK defines the page method as shown:

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

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

A sample page call is shown below:

rudderanalytics.page(
  "Cart",
  "Cart Viewed", {
    path: "/best-seller/1",
    referrer: "https://www.google.com/search?q=estore+bestseller",
    search: "estore bestseller",
    title: "The best sellers offered by EStore",
    url: "https://www.estore.com/best-seller/1"
  },
  () => {
    console.log("page call");
  }
);

In the above example, the JavaScript SDK captures the page category, name and the contextual information.

Track

The track call lets you capture user events along with the associated properties.

The JavaScript SDK defines the track method as shown:

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

The following table describes the above parameters in detail:

A sample track call is shown below:

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

In the above example, the track method tracks the Order Completed event along with other information like revenue, currency, and the user_actual_id.

Refer to the Ecommerce Events Specification for more information on the ecommerce events captured by RudderStack.

Alias

The alias call lets you merge different identities of a known user.

The JavaScript SDK defines the alias method as shown:

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

The following table describes the above parameters in detail:

A sample alias call is shown below:

rudderanalytics.alias("new_id", "old_id", () => {
  console.log("alias call");
});

Group

The group call lets you associate an identified user with a group such as a company, organization, or an account.

RudderStack does not support associating a user to more than one group per group call.

The JavaScript SDK defines the group method as shown:

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

The following table describes the above parameters in detail:

A sample group call is shown:

rudderanalytics.group("sample_group_id", {
  name: "Apple Inc.",
  location: "USA",
});

Reset

The reset method resets the ID and traits of both the user and the group.

In session tracking, calling the reset method clears the current sessionId and generates a new one.

The JavaScript SDK defines the reset method as shown:

rudderanalytics.reset();

You can also reset the anonymousId along with the above-mentioned details by passing true to the reset() method:

rudderanalytics.reset(true);

The reset() method only clears the cookies and local storage set by RudderStack. It does not clear the information stored by the integrated destinations.

Callbacks to common methods

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

This functionality is supported only for the syncPixel method which is called by the SDK while making synchronization calls for the relevant destinations.

An example is shown below:

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

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

Here, RudderStack defines syncPixelCallback on the rudderanalytics object while loading the SDK. Further, RudderStack calls this registered callback with the parameter {destination: <destination_name>} whenever a SDK makes a sync call the SDK to the relevant integration - in this case, Lotame.

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

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

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. in the snippet with their actual values.

Query string API

RudderStack’s Query string API lets you trigger the track and identify calls using the query parameters within the URL. The query parameters are listed in the following table:

For example, consider the following URL containing the query string parameters:

http://hostname.com/?ajs_uid=12345&ajs_event=test%20event&ajs_aid=abcde&ajs_prop_testProp=prop1&ajs_trait_name=Firstname+Lastname

It will trigger the following API calls:

// Sets the user ID/anonymous ID
rudderanalytics.setAnonymousId("abcde");

// Identify call
rudderanalytics.identify("12345", {
  name: "Firstname Lastname"
});

// Track call
rudderanalytics.track("test event", {
  testProp: "prop1"
});

Context and traits

The JavaScript SDK automatically captures certain event-specific and user-specific data based on the event type.

The context and traits dictionaries are provided in the apiOptions parameter of the supported API methods.

Context

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

A context is a complete and specific piece of information. Any other information provided outside this specification is ignored.

Traits

The traits object is an optional dictionary included within context specifying 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 calls, for example, track or page.

Use-case

To understand the concept of context and traits better, refer to the following identify event:

rudderanalytics.identify("1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
  name: "Alex Keener",
  email: "alex@example.com",
  subscriptionStatus: "subscribed",
  plan: "Silver"
});

The traits in the above event are name, email, subscriptionStatus, and plan. If you wish to add or override any traits in the subsequent track or page event triggered by the user, you can do so by passing it in traits as shown:

rudderanalytics.track(
  "Subscription Update", {
    campaign: "Subscribe"
  }, {
    traits: {
      plan: "Gold",
      addOn: true
    }
  }
);

The above snippet will add a new trait addOn and update the user trait plan to Gold.

Questions? Contact us by email or on Slack