Customer.io
GitHub project

Identify profiles

You need to identify a user before you can send them messages or track the things they do in your app.

Identify a profile

Identifying a person:

  1. Adds or updates the person in your workspace. This is basically the same as an identify call to our server-side API.
  2. 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.
  3. Associates the current device token with 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 profile—an ID or email address that represents a profile in Customer.io (and your downstream destinations). If you treat phone as an identifier, you should identify profiles by id or email and send the phone number as a phone attribute.
  • traits (Optional): Contains attributes that you want to set for a profile. 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(
    userId = "USER_ID",
    traits = mapOf("first_name" to "firstName")
  )

Update a profile’s attributes

You store information about a profile in Customer.io as attributes. When you call the identify() function, you can update a profile’s attributes on the server-side.

If a profile is already identified, and the user updates their preferences, provides additional information about themselves, or performs other attribute-changing actions, you can update their profile attributes with profileAttributes.

CustomerIO.instance().setProfileAttributes(mapOf("favorite_food" to "pizza"))

You only need to pass the attributes that you want to set. For example, if you identify a new profile with the attribute "first_name": "Dana", and then you call CustomerIO.instance().setProfileAttributes(mapOf("favorite_food" to "pizza")), the profile’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 attributes for each device. You can use these attributes in segments and other automation workflow conditions to target the device owner, just like you would use a profile’s other attributes. You cannot, however, use device attributes to personalize messages with liquid 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 profile’s devices and each device’s attributes when you go to Journeys > Profiles > Select a profile, and click Devices.

device attributes on a profile

Your integration shows device attributes in the context object

When you inspect calls from the SDK (in your integration’s data in tab), you’ll see device information in the context object. We flatten the device attributes that you send into your workspace, so that they’re easier to use in segments. For example, context.network.cellular becomes network_cellular.

  • idstringrequired
    The device token.
  • last_usedinteger(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.
  • platformstringrequired
    The device/messaging platform.
    Accepted values: ios, android
  • attributesobject
    Attributes that you can reference to segment your audience—like a person's attributes, but specific to a device. These can be either the attributes defined below or custom key-value attributes.
    • device_osstring
      The operating system, including the version, on the device.
    • device_modelstring
      The model of the device a person uses.
    • app_versionstring
      The 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_versionstring
      The version of the Customer.io SDK in the app.
    • _last_statusstring
      The 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
    • device_localestring
      The device's IETF language code, such as en-MX or es-ES.
    • push_enabledstring
      If "true", the device is opted-in and can receive push notifications.
      Accepted values: true, false
    • network_bluetoothboolean
      If true, the device's bluetooth connection is on.
    • network_cellularboolean
      If true, the device's cellular connection is on.
    • network_wifiboolean
      If true, the device's WiFi connection is on.
    • screen_heightinteger
      The height of the device's screen in pixels.
    • screen_widthinteger
      The width of the device's screen in pixels.
    • timezonestring
      The time zone of the device.
    • Custom Device Attributes *string
      Custom properties that you want to associate with the device.

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, time zone, or other custom values specific to the device.

CustomerIO.instance().setDeviceAttributes(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 profile more broadly. If you want an attribute to persist beyond the life of the device, you should apply it to the profile 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 profile

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 profile (if there was one).

// Future calls to the SDK are anonymous
CustomerIO.instance().clearIdentify()

Identify a different profile

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