Identify people

Updated

Use CustomerIO.identify() to identify a person. You need to identify a mobile user before you can send them messages or track events for things they do in your app.

This page is part of a setup flow for the SDK. Before you continue, make sure you've implemented previous features—i.e. you can't identify people before you initialize the SDK!

graph LR getting-started(Install SDK) -->B(Initialize SDK) B --> identify(identify people) identify -.-> track-events(Send events) identify -.-> push(Receive push) identify -.-> in-app(Receive in-app) click getting-started href "/sdk/flutter/getting-started/#install" click B href "/sdk/flutter/getting-started/#initialize-the-sdk" click identify href "/sdk/flutter/identify" click track-events href "/sdk/flutter/track-events/" click register-token href "/sdk/flutter/push" click push href "/sdk/flutter/push" click rich-push href "/sdk/flutter/rich-push" click in-app href "/sdk/flutter/in-app" click test-support href "/sdk/flutter/test-support" style identify fill:#B5FFEF,stroke:#007069

Identify a person

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 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 two parameters:

import 'package:customer_io/customer_io.dart';

// Call this method whenever you are ready to identify a user
CustomerIO.identify(identifier: "person@example.com", attributes: {"first_name": "Dana"});

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 CustomerIO.identify() function, you can update a person’s attributes on the server-side.

You can update a person’s attributes after you identify them using setProfileAttributes—like when a person updates their preferences or provides additional information about themselves that you want to store in Customer.io.

You only need to pass the attributes that you want to create or modify to setProfileAttributes. For example, if you identify a new person with the attribute {"first_name": "Dana"}, and then you call CustomerIO.setProfileAttributes(attributes: {"favorite_food": "pizza"}); after that, the person’s first_name attribute will still be Dana.

const profileAttributes = {
      "favouriteFood": "Pizza",
      "favouriteDrink": "Mango Shake",
    };
CustomerIO.setProfileAttributes(attributes: profileAttributes);

Device attributes

When you register a device token to a person, we automatically collect device 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.. 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.

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 attributes object.

  • id string
    Required The device token.
    • _last_status string
      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

    • app_version string
      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_version string
      The version of the Customer.io SDK in the app.
    • device_locale string
      The 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 string
      The model of the device a person uses.
    • device_os string
      The operating system, including the version, on the device.
    • push_enabled string
      If "true", the device is opted-in and can receive push notifications.

      Accepted values:true,false

    • Custom Device Attributes* string
      Custom 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 string
    Required The device/messaging platform.

    Accepted values:ios,android

Set custom device attributes

You can also set custom device attributes with the setDeviceAttributes method. You might do this to save app preferences, timezone, or other custom values specific to the device. Like profile attributes, you can pass nested JSON to device attributes.

However, before you set custom device attributes, consider whether the attribute is specific to the device or if it applies to the person more 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.

const deviceAttributes = {
      "type" : "primary_device",
      "parentObject" : {
        "childProperty" : "someValue",
      },
    };
CustomerIO.setDeviceAttributes(attributes: deviceAttributes);

Manually add device to profile

In the standard flow, identifying a person automatically associates the token with the identified person in your workspace. If you need to manually add or update the device elsewhere in your code, call the method CustomerIO.registerDeviceToken(token).

const registerDevice = () => {
     // Customer.io expects a valid token to send push notifications
     // to the user.
     const token = 'token'

     CustomerIO.registerDeviceToken(token)
 }

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).

CustomerIO.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.

CustomerIO.identify(identifier: "new.person@example.com", attributes: {"first_name": "New", "last_name": "Person"}); 
Copied to clipboard!
  Contents
Current release
 1.5.2
Is this page helpful?