Customer.io

Managing your audience's identities

How it works

Our JavaScript client manages the identities of your audience. At first, a customer has an anonymousId. Then when they provide an email or other id, they’re assigned a userId. When a person logs out and you call cioanalytics.reset();, the user becomes anonymous again.

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

flowchart LR a(person<br>visits site)-->|generate<br>anonymousId|z subgraph z [anonymous activity] direction TB b(visit<br>a page) b-->|page|c(add item<br>to cart) c-->|track|d(person<br>logs in) end subgraph y [identified activity] direction TB e(person initiates<br>checkout)-->|track|f(person finishes<br>transaction) f-->|track|g(person logs out) end d-->|identify|e g-->|reset|h(person is<br>anonymous again)

Your workspace automatically merges anonymous activity into an identified profile, so long as the activities occurred no more than 30 days before identification.

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 integrations, 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:

Retrieve the Anonymous ID

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

cioanalytics.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 cioanalytics.reset() during a user’s browser session.
  • Your site or app calls cioanalytics.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.

 cioanalytics.load('writekey');
 cioanalytics.page();
 cioanalytics.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 other integrations you use.

Direct-connection integrations might have their own anonymous IDs

In some rare cases, integrations might not use Customer.io’s anonymousId. Read the documentation for your integration to find out if it sets its own ID.

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.

cioanalytics.user().anonymousId('ABC-123-XYZ');
cioanalytics.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.

cioanalytics.identify('user_123', {
  name: 'Jane Kim'
}, {
  anonymousId: 'ABC-123-XYZ'
});
cioanalytics.page({}, { anonymousId: 'ABC-123-XYZ' });
cioanalytics.track('Email Clicked', {
  callToAction: 'Signup'
}, {
  anonymousId: 'ABC-123-XYZ'
});

Merge anonymous activity with an identified profile

Your workspace automatically merges anonymous activity into an identified profile, so long as the activities occurred no more than 30 days before identification.

For example, if a person adds items to their cart before they log in and you track custom events, your workspace automatically associates this event with their profile when they log in.

// Send an anonymous event
cioanalytics.track('addedToCart', {
  product: "shoes",
  price: 39.95,
  qty: 1,
  size: 9
});

// Identify the person
cioanalytics.identify('abcd1234', {
  email: 'karl@example.com',
  name: 'Karl Smith'
});

// The addedToCart event is now associated with this person

Learn more about using anonymous activity in Customer.io.

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 attributes in Customer.io Journeys.

The options object contains a child object called context that automatically captures data depending on the event and the SDK or library you use. See our the context object 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 integrations.

Imagine that you sent this identify call.

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

cioanalytics.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:

cioanalytics.user().traits({});
cioanalytics.group().traits({});

Using cioanalytics.user() and cioanalytics.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.

Use the ready function

You can wrap any reference to user() or group() in a ready function block to make sure that cioanalytics.js fully loads and these methods are available.

cioanalytics.ready(function() {

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

});
cioanalytics.ready(function() {

  var group = cioanalytics.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:

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

Updated September 1, 2026