Identify people
UpdatedYou 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.
Identify a person
Identifying a person:
Adds or updates the person in your workspace. This is basically the same as an
identify
call to our server-side API.Saves 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.
Associates the current device token with the the 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.
An identify request takes the following parameters:
- userId (required): The unique value representing a person—an ID or email address that represents a person in Customer.io (and your downstream destinations).
- traits (Optional): Contains 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. that you want to set for a person. The
traits
object accepts strings, enums, primitives (int, float, char, etc.), their boxed counterparts (Integer, Float, Character, etc.), arrays, collections, lists, sets, and maps.
We also offer a Kotlin serialization library that can help make it easier to set keys and values for the traits
object.
CustomerIO.instance().identify("USER_ID", buildJsonObject {
put("username", "MisterWhiskers")
put("email", "mister.whiskers@example.com")
put("plan", "premiumCatFood")
});
CustomerIO.instance()
.identify(
userId = "USER_ID",
traits = mapOf("first_name" to "firstName")
)
Update a person’s attributes
You store information about a person in Customer.io as 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.. 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 update their attributes with profileAttributes
.
CustomerIO.profileAttributes = ["favorite_food": "pizza"]
You only need to pass the attributes that you want to set. For example, if you identify a new person with the attribute "first_name": "Dana"
, and then you call CustomerIO.profileAttributes = ["favorite_food": "pizza"]
, the person’s first_name
attribute will still be Dana
. And Dana will now have a favorite_food
attribute with the value pizza
.
Device attributes
By default (if you don’t set .autoTrackDeviceAttributes(false)
in your config), the SDK automatically collects a series of 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. for each device. 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 {{customer.first_name}}
. yet.
Along with these attributes, we automatically set a last_used
timestamp for each device indicating when the device owner was last identified, and the last_status
of a push notification you sent to the device. You can also set your own custom device attributes. You’ll see a person’s devices and each device’s attributes when you go to Journeys > People > Select a person, and click Devices.
![device attributes on a person's profile](/docs/images/device-attributes.png)
![device attributes on a person's profile](/docs/images/device-attributes.png)
Your source shows device attributes in the context
object
When you inspect calls from the SDK (the sourceA source is a website or server that you want to capture data from—it’s a source of data! in Data Pipelines), you’ll see device information in the context
object. We flatten the device attributes that you send into your workspace/Journeys, so that they’re easier to use in segmentsA segment is a group of people in your audience that you want to target with campaigns, messages, etc. You can join groups of people manually, or by attribues and event data.. For example, context.network.cellular
becomes network_cellular
.
- id stringRequired The device token.
-
- _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.
Accepted values:
,
bounced
,sent
,suppressed
- app_version stringThe version of your app that a customer uses. 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) ores-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.
- network_bluetooth booleanIf
true
, the device’s bluetooth connection is on. - network_cellular booleanIf
true
, the device’s cellular connection is on. - network_wifi booleanIf
true
, the device’s WiFi connection is on. - push_enabled stringIf
"true"
, the device is opted-in and can receive push notifications.Accepted values:
true
,false
- screen_height integerThe height of the device’s screen in pixels.
- screen_width integerThe width of the device’s screen in pixels.
- timezone stringThe timezone of the device.
- Custom Device Attributes* stringCustom properties that you want to associate with the device.
- last_used integer (unix timestamp)The
timestamp
when 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.
Accepted values:
ios
,android
Custom device attributes
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 a person more broadly. If you want an attribute to persist beyond the life of the device, you should apply it to the person rather than the device.
Disable automatic device attribute collection
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)
Stop identifying a person
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.
Use clearIdentify()
to stop identifying the previously identified person (if there was one).
// Future calls to the SDK are anonymous
CustomerIO.instance().clearIdentify()
Identify a different person
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.