Identify profiles

Use CustomerIO.identify() to identify a profile. 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!

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

• userId (Required): The unique value representing a profile—an ID, email address, or the cio_id. 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): An object containing attributes that you want to add to, or update on, a profile

CustomerIO.instance.identify(userId: email, traits: {
  "name": user.displayName,
  "email": user.email,
  "age": user.age,
});

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 in Customer.io.

If you’ve already identified a profile, and they update their preferences, provide additional information about themselves, or perform other attribute-changing actions, you can update their attributes with profileAttributes.

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

CustomerIO.instance.setProfileAttributes(traits: {
  "first_name": "Cool",
  "last_name": "User",
  "is_premium": false,
});

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.

Set custom device attributes

You can also set custom device attributes with the setDeviceAttributes method. You might do this to save app preferences, time zone, 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 profile 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 profile rather than the device.

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

Disable automatic device attribute collection

By default, the SDK automatically collects the device attributes defined above. You can disable the autoTrackDeviceAttributes setting to prevent the SDK from automatically collecting these attributes.

CustomerIO.initialize(
  config: CustomerIOConfig(
      cdpApiKey: '<your API Key>',
      autoTrackDeviceAttributes: false,
      inAppConfig: InAppConfig(siteId: '<your siteId>'),
  ),
);

Manually add device to profile

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

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

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.

CustomerIO.instance.identify(identifier: "new.person@example.com", attributes: {"first_name": "New", "last_name": "Person"});