Manage devices

If you want to send push notifications, you can register your users devices with us. Our SDKs automatically associate device tokens with profiles when you identify a profile, but you can also use our API to add devices.

You’ll find a profile’s devices by going to the Profiles page, selecting a profile, and going to their Devices tab.

For each device, we show the device platform platform, token, and when the device was “last used”. Last used indicates the last time you identified a device—something you typically do when someone logs into your app, or opens your app and is already logged in!

You can hover over the truncated token to see the full string and copy it to your clipboard. This is especially useful when you need a device token for sending a test push notification from the composer.

And in the activity stream, you can click on each individual row for more details. Here’s an example with an initial API call to add a device:

Add and Delete devices

In general, we suggest that you integrate with our SDKs to add and delete devices. They can help you associate device tokens with profiles you identify and remove tokens when you stop identifying them.

Otherwise, you can integrate directly with our API to add and delete devices.

You can’t add devices in the UI, but you can delete as many as you like.

We automatically delete unregistered devices

Device tokens are ephemeral: they become invalid when a person logs out of your app, and a push service can change them at any time. Beginning January 31, 2023, when a device token becomes unregistered, it is invalid and will never become valid again; if a person logs into your app again, they’ll get a new device token.

To prevent invalid tokens from stacking up on profiles in your workspace, we automatically remove devices when they’re invalidated by your push services. If, when you send a push notification, your push service (FCM or APNs) responds with an unregistered message, we’ll automatically remove the token from your workspace.

flowchart LR a[send push]-->b{Is the push <code>sent</code>?} b-->|yes|c[display push] b-.->|no, device token<br>is <code>unregistered</code>|d[delete device] class d mermaid-error classDef mermaid-error fill: #ffedf0,color: #69002c, stroke:#69002c

Device attributes

Devices have their own attributes. We collect last_status automatically. We also set a last_used attribute based on either the timestamp in your request to add or update a device, or the time of the request itself. When you add or update a device using our SDKs, we’ll set the platform automatically for you; otherwise, you must send the platform with each request to our API.

If you use our SDKs, you’ll automatically collect additional device attributes by default. Whether or not you use our SDKs, you can also set custom attributes for each device—similar to attributes you set for profiles, but specific to each mobile device token.

When you go to a profile’s Devices tab, you’ll see each device’s PLATFORM, DEVICE LAST USED and LAST RESULT attributes. Click a device to reveal additional information and attributes attached to it.

You can use device attributes anywhere you would otherwise use a profile’s other attributes—True/False branches, Action Conditions, or segments. But you cannot use device attributes with Liquid today.

Custom device attributes

When you identify or update a device, you can pass an attributes object containing additional attributes specific to a device. If you use our SDKs, we capture a number of predefined attributes automatically—unless you disable automatic attribute collection.

You can segment and filter audience members based on these attributes. However, device tokens can change—sometimes based on user behavior, like when a profile uninstalls and reinstalls your app, and sometimes based on your messaging service (FCM or APNs). When you set attributes on a device, consider wether you need to retain an attribute past the life of the device token, and if an attribute is truly relevant to the device.

The following attributes are automatically collected by alpha versions of the SDK, set automatically by Customer.io, or available to our APIs. If you disable automatic attribute collection in the SDK, we’ll stop automatically collecting properties other than platform, last_used, and last_status.

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
- Custom Device Attributes *string
  Custom properties that you want to associate with the device.

Segment profiles based on their devices

When you create segments, you can segment profiles based on their device attributes—their platform, the status of their last message, or when devices were last_used.