Identify people

How it works

Identifying people adds them to, or updates them in, your workspace, and makes them eligible to receive in-app messages. After you identify someone, calls to the SDK will automatically reference the identified person until you identify someone else or send a reset call.

Before you identify someone, we’ll attribute their activity on your website—page and track events—to an anonymous user. When you identify a person, we’ll automatically associate their anonymous activities with their profile in your workspace.

You can only identify one customer at a time. The SDK “remembers” the most recently-identified customer. If you identify person A, and then call the identify function for person B, the SDK “forgets” person A and assumes that person B is the current app user. You can also stop identifying a person, which you might do when someone logs out or stops using your app for a significant period of time.

sequenceDiagram actor a as Website visitor participant b as Your Website participant c as Customer.io a->>b: Person visits page note over a,c: Visitor is anonymous and cannot receive messages b->>c: anonymous page event a->>b: person logs in b->>c: identify person note over a,c: Future calls represent identified person.
Anonymous activity attributed to identified person c->>c: associate anonymous activity with person a->>b: person adds item to cart b->>c: track event/trigger campaign c-->>a: person enters campaign/receives messages a->>b: person logs out note over a,c: Visitor is anonymous again

Identify a person

Identifying a person creates or updates a person in Customer.io, and makes future calls reference this person. For example, after you send an identify call, any track calls you make will be associated with the identified person.

You identify a person with the _cio.identify function. Your identify call must include an id. But in most cases, an id can either be a person’s canonical identifier or an email address. Learn more about using email address as an identifier below.

When you first identify someone, we strongly recommend that you send created_at—a timestamp (in seconds since epoch) representing the moment you first identified and created a person. You shouldn’t pass this value with subsequent identify calls, or you’ll overwrite a person’s created_at attribute.

You can also send in additional 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. that are of value to you. In the above example we send first_name, last_name and plan_name attributes. You can use these attributes to segment your audience or to personalize messages for people.

_cio.identify({
    id: 'YOUR_USER_ID_HERE',   // Required to identify a person.

    // Strongly recommended when you first identify someone
    created_at: 1339438758,   // When a person first signed up in Unix epoch format.

    // Example attributes (you can name attributes anything you want)
    email: 'user@domain.com',  // Email of the currently signed in user.
    first_name: 'John',       // First name and last name are shown on people pages.
    last_name: 'Smith',       
    plan_name: 'premium'      
});

We also have a Custom forms JavaScript snippet that automatically identifies people when they fill out a form on your website. See Custom form integrations for more information.

Using email as an identifier

In most cases, you can use an email address as a person’s unique identifier. While our JavaScript snippet requires an id value, you can pass an email address as an id and we’ll detect it as such.

When you use an email address as an id and a person does not exist, we’ll create that person and set their email attribute. This leaves their id attributeA 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. open, so you can assign it later. This is helpful for people who you might identify as leads (by email address) before they become a customer and generate an ID in your backend systems—like someone who signs up for a webinar by email address but hasn’t yet purchased your product.

If an id is a non-email address value, you can also set an email attribute.

_cio.identify({
    // Use email as ID
    id: 'cool.person@example.com',

    // Strongly recommended when you first identify someone
    created_at: 1339438758
});
flowchart LR a(_cio.identify)-->b{Does person exist?} b--->|yes|c(Update person) b-->|no|d{What is id?} d-->|id|e(Add person with id) d-->|email|f(Add person with email
id is empty)

Automatically identify people who click tracked links

By default (for workspaces created after July 12, 2021), Customer.io automatically appends a _cio_id parameter containing a person’s cio_idAn identifier for a person that is automatically generated by Customer.io and cannot be changed. This identifier provides a complete, unbroken record of a person across changes to their other identifiers (id, email, etc). to tracked linksA link in a message that logs when a person clicks it. You can gather metrics for tracked links and use them to determine your audience’s level of engagement.. If your tracked links send people to a webpage containing our JavaScript snippet, the snippet automatically identifies people.

Even if you don’t use our JavaScript Snippet, you can still take advantage of the _cio_id parameter in tracked links to identify people. If you integrate directly with our API or one of our libraries, you can identify people using cio_<_cio_id-param-value> rather than a person’s ID or email address.

To change or disable this setting:

  1. Go to Settings > Workspace Settings.

  2. Go to URL Parameters. If you already have URL parameters enabled, click Settings; otherwise, click Get Started.

  3. Click Add _cio_id URL parameter.

    Auto-identify setting
    Auto-identify setting

This setting affects messages you send after you enable or disable it. It does not affect messages that you’ve already sent.

Support for arrays in identify calls

To maintain the integrity of arrays in identify calls and support complex JSON attributes—like if you want to set relationships on people—you need to make sure that the JavaScript snippet includes the line: t.setAttribute('data-use-array-params', 'true');.

If you comment this line out or set it to false, the web SDK reshapes arrays as objects with integer keys. For example, the following event with an array results in a payload formatted as an object.

Identify callReshaped payload
  _cio.identify({ my_array: ['one', 'two'] })
  

  
{
  "my_array": {
    0: "one"
    1: "two"
  }
}

Session management with browser cookies

Our web SDK sets cookies to determine whether someone is anonymous or has already been identified.

  • _cioanonid: contains an anonymous ID that the tracking snippet sets automatically on a person who has not been identified yet. When you identify a person, we associate their anonymous activity (like page views) with the identified person.
  • _cioid: contains the id used when you call _cio.identify with the tracking snippet. Once set, these cookies persist until they expire - after 365 days or after a user clears their cache, for instance.

Some browsers are shifting away from supporting 3rd-party cookies, but because these two cookies are only set for your domain, browsers will not block them. Keep in mind, some browser extensions may still prevent our JS snippet from loading, which would prevent you from identifying people or our snippet from setting cookies.

If you use a third party platform like Shopify, you may want to enable the data-cross-site-support or data-enable-in-memory-storage parameters to support your implementation. See Cross Site Cookie Support and In-memory storage fallback for more information.

Update a person’s attributes

To update an existing user’s attributes, just send the _cio.identify call again. You must include a valid identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. value—normally id or email—and any attribute you want to set or change for that person. If the attributes already exist in their profile, we overwrite them. If your request includes new attributes we add them to the profile.

Relate people to objects

Objects are grouping mechanisms in Customer.io, like accounts that people belong to, flights they’ve booked, or online courses they’ve enrolled in. You can relate people to objectsNot to be confused with a JSON object, an object in Customer.io is a non-person entity that you can associate with one or more people—like a company, account, or online course. You can use objects to message people based on changes to their company, account, or colege course itinerary. using the cio_relationships array in your identify call.

This call contains a single action, letting you add_relationships or remove_relationships. The relationships array can contain any number of object relationships that you might want to set for the identified person.

_cio.identify({
  id: 'userid_34',
  email: 'customer@example.com',
  cio_relationships: {
        action: "add_relationships",
        relationships: [
            {
                identifiers: {
                    object_type_id: "1",
                    object_id: "acme"
                }
            }
        ]
    }
});

Stop identifying a person

When a person logs out of your website or app, you can clear the session by calling _cio.reset().

_cio.reset();

If you want to identify a new person—like when someone switches profiles on your website, etc—you can simply call _cio.identify() for the new person. The new person then becomes the currently-identified person, with whom all new information—messages, events, etc—is associated.

Copied to clipboard!
  Contents
Is this page helpful?