You need to identify a person using a mobile device before you can send them messages or track events for things they do in your app.
You must have have the Tracking SDK to use this feature.
This page is part of an introductory series to help you get started with the essential features of our SDK. The highlighted step(s) below are covered on this page. Before you continue, make sure you've implemented previous features—i.e. you can't identify people before you initialize the SDK!
When you identify a customer, you:
- Add or update the person in your workspace. This is basically the same as an
identifycall to our server-side API.
- Save the person’s information on the device. Future calls to the SDK reference the identified person. For example, after you identify a person, any events that you track are automatically associated with that person.
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 off or stops using your app for a significant period of time.
CustomerIO.instance() .identify( identifier = "989388339", attributes = mapOf("first_name" to "firstName") )
An identify request takes the following parameters:
- identifier (required): The unique value representing a person—an ID, email address, or the 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). (when updating people), depending on your workspace settings.
- attributes (Optional): Contains attributesA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages. that you want to add to, or update on, a person; accepts strings, enums, primitives (int, float, char, etc.), their boxed counterparts (Integer, Float, Character, etc.), arrays, collections, lists, sets, and maps.
You store information about a person in Customer.io as attributesA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages.. When you call the
identify() function, you can update a person’s attributes on the server-side.
If a person is already identified, and then updates their preferences, provides additional information about themselves, or performs other attribute-changing actions, you can call
identify() again to update their attributes on the server-side.
When you register a device token to a person, we automatically collect device attributesA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages.. You can use these attributes in segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. and other campaign workflow conditions to target the device owner, just like you would use a person’s other attributes. You cannot, however, use device attributes to personalize messages with liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable
For each device, we automatically collect the device
platform attribute. Within your workspace, we also automatically set a
last_used timestamp indicating when the device owner was last identified, and the
last_status of a push notification you sent to the device. By default, we also automatically capture a series of
attributes, like the device’s operating system, model,
push_enabled preference. You can add custom attributes to the
- _last_status stringThe delivery status of the last message sent to the device—sent, bounced, or suppressed. An empty string indicates that that the device hasn’t received a push yet.
- app_version stringThe version of your app that a customer users. You might target app versions to let people know when they need to update, or expose them to new features when they do.
- cio_sdk_version stringThe version of the Customer.io SDK in the app.
- device_locale stringThe four-letter IETF language code for the device. For example,
en-MX(indicating an app in Spanish formatted for a user in Mexico) or
es-ES(indicating an app in Spanish formatted for a user in Spain).
- device_model stringThe model of the device a person uses.
- device_os stringThe operating system, including the version, on the device.
- push_enabled stringIf
"true", the device is opted-in and can receive push notifications.
- Custom Device Attributes* stringCustom properties that you want to associate with the device.
- id stringRequired The device token.
- last_used integer (unix timestamp)The
timestampwhen you last identified this device. If you don’t pass a timestamp when you add or update a device, we use the time of the request itself. Our SDKs identify a device when a person launches their app.
- platform stringRequired The device/messaging platform.
When we collect device attributes, you can also set custom device attributes with the
deviceAttributes method. You might do this to save app preferences, timezone, or other custom values specific to the device.
CustomerIO.instance().deviceAttributes = mapOf("key" to "value")
However, before you set custom device attributes, consider whether the attribute is specific to the
device or if it applies to the person broadly. Device tokens are ephemeral—they can change based on user behavior, like when a person uninstalls and reinstalls your app. If you want an attribute to persist beyond the life of the device, you should apply it to the person rather than the device.
By default, the SDK automatically collects the device attributes defined above. You can change your config to prevent the SDK from automatically collecting these attributes.
// set before you build builder.autoTrackDeviceAttributes(false)
When a person logs out, or does something else to tell you that they no longer want to be tracked, you should stop identifying them.
clearIdentify() to stop identifying the previously identified person (if there was one).
// Calls to the Customer.io SDK will be ignored until you identify a new person. CustomerIO.instance().clearIdentify()
If you want to identify a new person—like when someone switches profiles on a streaming app, etc—you can simply call
identify() for the new person. The new person then becomes the currently-identified person, with whom all new information—messages, events, etc—is associated.