20

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.

Identify a person

You identify a person with the _cio.identify function. Your identify call must include at least one identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. for the person you want to represent. Depending on your workspace settings, this can be either:

• id: the person’s unique identifier that maps a person to your backend systems.
• email: the person’s email address.

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({
    // Required attributes — you must include at least one of the following
    id: 'YOUR_USER_ID_HERE',   // Unique id for the user in your application.
    email: 'user@domain.com',  // Email of the currently signed in user.

    // 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)
    first_name: 'John',       // Add any attributes you'd like to use in the email subject or body.
    last_name: 'Smith',       // First name and last name are shown on people pages.
    plan_name: 'premium'      // To use the example segments, set this to 'free' or '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.

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.

   

   

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.

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

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

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.