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:

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

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

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

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:

Copy
rudderanalytics.getAnonymousId();

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.

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.

An example is shown below:

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

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

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

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

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 the cookies related to the user (associated with the userId and traits) and updates them with the newly provided values.

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 the traits associated with that user. An example is shown below:

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

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:

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

The JavaScript SDK defines the page method as shown:

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

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

A sample page call is shown below:

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

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

The following table describes the above parameters in detail:

A sample track call is shown below:

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

Alias

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

The JavaScript SDK defines the alias method as shown:

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

The following table describes the above parameters in detail:

A sample alias call is shown below:

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

The JavaScript SDK defines the group method as shown:

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

The following table describes the above parameters in detail:

A sample group call is shown:

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

The JavaScript SDK defines the reset method as shown:

Copy
rudderanalytics.reset();

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

Copy
rudderanalytics.reset(true);

Callbacks to common methods

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

An example is shown below:

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

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

Querystring API

RudderStack's Querystring 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 querystring parameters:

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

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

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:

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

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