30

Managing your audience's identities

How it works

Our JavaScript source manages the identities of your audience, first as an anonymousId. Then, when you identify them, you know them by their userId. Then we remove those values when a person logs out and you call analytics.reset();.

We store user identity information in cookies and local storage. You can retrieve or override this information as necessary to support destinations and other integrations. This page provides information about the values we store, where we store them, and how to get or override them.

ID Persistence

We write the user’s IDs to their browser’s local storage, and use that as the user ID on cookies whenever possible.

If a user returns to your site after the cookie expires, we’ll look for an old ID in the user’s localStorage. If we find an ID, we’ll set it as the user’s ID again in the new cookie. If a person clears their cookies and localstorage, they’ll remove all IDs, and they’ll get a completely new anonymousID the next time they visit your site.

Anonymous IDs

We generate a universally unique ID (UUID) for website visitors when our JavaScript initializes, and we set this value as the anonymousId for each new visitor to your site. This happens before we load direct-connection destinations, so they don’t generate their own user IDs.

Example:

ajs_anonymous_id=%2239ee7ea5-b6d8-4174-b612-04e1ef3fa952

You can override the auto-generated anonymousID in code using the methods described below:

• Set anonymousId (before the ready method returns)
• Use a call to override the anonymousID
• Set anonymousId in the options object of a call

Retrieve the Anonymous ID

You can get the user’s current anonymousId with the user method.

analytics.user().anonymousId();

If the user doesn’t have an anonymousId (it’s null) this call will automatically generate and sets a new anonymousId for the user.

Refreshing the Anonymous ID

A user’s anonymousId changes in any of the following situations:

• They clear their cookies and localstorage.
• Your site or app calls analytics.reset() during a user’s browser session.
• Your site or app calls analytics.identify() with a userId that is different from the current userId.

Override the Anonymous ID

You can also set the anonymousId immediately, even before the ready method returns.

 analytics.load('writekey');
 analytics.page();
 analytics.setAnonymousId('ABC-123-XYZ');

You might use this method if you queue calls before ready returns and those methods require a custom anonymousId. Keep in mind that setting the anonymousId in Analytics.js does not overwrite the anonymous tracking IDs for any destinations you’re using.

Override the default Anonymous ID

If the default anonymous UUID doesn’t meet your needs, you can override anonymousId for the current user using either of the following methods.

analytics.user().anonymousId('ABC-123-XYZ');

analytics.setAnonymousId('ABC-123-XYZ')

Override Anonymous IDs using the options object

You can override an anonymousId in the options object of identify, page, or track calls. The custom anonymousId persists when you use the methods below, even if you don’t specify the anonymousId in the calls.

analytics.identify('user_123', {
  name: 'Jane Kim'
}, {
  anonymousId: 'ABC-123-XYZ'
});

analytics.page({}, { anonymousId: 'ABC-123-XYZ' });

analytics.track('Email Clicked', {
  callToAction: 'Signup'
}, {
  anonymousId: 'ABC-123-XYZ'
});

Saving traits to the context object

Traits are things that you know about a user or a group, and which can change over time—like attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. in Customer.io Journeys.

The options object contains a child object called context that automatically captures data depending on the event and source-type. See Data Pipelines API schemas to learn more.

The context object contains an optional traits dictionary. This dictionary contains traits about the current user. You can use this to retrieve information about a user that you set or stored as a result of previous identify calls. This might be useful if you also want to send traits as properties in track or page calls.

The information you pass in traits does not appear in your downstream tools (like Salesforce, Mixpanel, or Google Analytics). But this data does appear in warehouses and storage destinations.

Imagine that you sent this identify call.

analytics.identify('12091906-01011992', {
    plan_id: 'Paid, Tier 2',
    email: 'cool.person@example.com'
});

You can pass the plan_id into context.traits, so you can use them in track and page events that the user triggers later, as shown below.

analytics.track('Clicked Email', {
  	emailCampaign: 'First Touch'
  },
  {
    traits: {
      plan_id: 'Paid, Tier 2'
    }
  }
);

This appends the plan_id trait to the track event. This does not add the name or email, since those traits were not in the context object. You must do this for every event that you want these traits to appear on, because context does not persist between calls.

Clearing Traits

You can pass an empty object to the traits object to clear all cached traits for a User or Group.

Traits are cached by default when you call the Identify and Group methods. You can clear the traits object for the user or group by passing traits an empty object:

analytics.user().traits({});

analytics.group().traits({});

Using analytics.user() and analytics.group()

You can use the user or group method as soon as the Analytics.js library loads, to return information about the currently identified user or group. This information is retrieved from the user’s cookie.

analytics.ready(function() {

  var user = analytics.user();
  var id = user.id();
  var traits = user.traits();

});

analytics.ready(function() {

  var group = analytics.group();
  var id = group.id();
  var traits = group.traits();

});

Anonymizing IP addresses

We automatically collect the user’s IP address for device-based events.

You can pass a value for options.context.ip to prevent us from recording IP addresses like this:

  analytics.track("Order Completed", {}, { context: { ip: "0.0.0.0" }});

You must add this override to every track call to explicitly override IP collection. If you reset this trait in the context object, we’ll default to the normal IP collection behavior.