20

Registering device tokens

Device (push) tokens are how we identify devices in your audience. This page provides information about how to register tokens, associate them with people in your workspace, and what to do when they expire or are otherwise no longer useful.

What is a device token?

Device tokens—sometimes known as push tokens in other products or push services—are unique, anonymous identifiers for the app-device combination that are issued by push notification services: they’re basically device addresses, so you can send push notifications to your app’s users. If a person doesn’t have a device token, they can’t receive push notifications and their device won’t appear in Customer.io.

In Customer.io, we reflect device tokens as devices (or device_id in our APIs and SDKs).

The key thing is that a device token by itself is anonymous. You have to identify a user to associate the device token with a person in Customer.io, so you can send them messages.

The device lifecycle

In general, the token lifecycle begins when your app registers for a token. That’s when push services like Firebase Cloud Messaging (FCM) and Apple’s Push Notification service (APNs) issue tokens to a device.

When a device gets a token, it’s anonymous until you identify the user—like when they log into your app or give their email address.

The token will be valid during the user’s session in your app, but it can become invalid for any number of reasons. The most obvious reason is when a user logs out of your app. But, beyond that, push services can invalidate tokens for any reason on their end. So, whenever a person opens your app, you should make sure that you register for a device token to ensure that your user has a valid token.

Invalid tokens are not reusable. Once a token is invalid, it won’t become valid again. Customer.io does some work to prune invalid device tokens to help you maintain a tidy workspace. For example, when a person logs out of your app and you run our SDKs’ clearIdentify() method, we’ll remove their device token. Or if you send a push notification to a token that’s no longer valid, we’ll know that the token is bad and remove it from the person’s profile in Customer.io.

When should I register for a device token?

You should register for a device token whenever someone opens your app‚ even if a person already has a device token associated with them or you haven’t yet asked them for permission to receive push notifications. If someone already has a token, push services (FCM or APNs) can invalidate device tokens for any number of reasons at any time. Registering for a device token gets a new token if a current token doesn’t exist or is invalid. Otherwise, it ensures that the current token is valid.

You should also call the registration function after a person grants authorization to receive push notifications.

Remember, even if you register for a token, you still need to identify someone before you can send them notifications. Identifying a person associates a token with a person, so you can send messages to that device. A person can have multiple devices, and each of a person’s devices can receive messages.

Android device tokens

Android 13 and Later requires you to ask for permission to send push notifications. Your app’s users are assigned a token when the user grants permission to receive notifications.

Android 12 and Earlier assume that users permit to receive push notifications by default. You can request a push token by default.

iOS device tokens

You should register for a device token at app startup, but iOS users must grant permission to receive push notifications. If you use our iOS SDK, you’ll need to add our registration method. If you use our other iOS-supporting SDKs, they’ll do this for you.

Beginning in iOS 12, you can request provisional authorization and send provisional push notifications—messages that don’t have an alert or play sounds. Our native iOS SDK supports provisional push notifications, but our other iOS-supporting SDKs do not support provisional push.

You still need to identify people

Remember that device tokens are anonymous on their own. Customer.io doesn’t support anonymous push notifications, so you can’t simply target any individual device token in your workspace.

You still have to identifyThe Customer.io operation that adds or updates a person. When you identify a person, Customer.io either adds a person if they don’t exist in your workspace, or updates them if they do. Before you identify someone (by their email address or an ID), you can track them anonymously. someone to associate a token with a person, so you can send them messages. This ensures that you send messages to the right people in your audience.

Can I target a specific device?

You can target specific devices that belong to people in your workspace with:

• Transactional Push notifications, because these are one-to-one messages; they’re intended to respond to an event from an individual device with a notification that the user implicitly expects.
• The Custom device token option when you send an event-triggered campaign. This can be helpful if you store the current device token in your event data—so you can send a message directly to the device that triggered an event.

When you send a push notification as a part of non-event-triggered campaigns, you can target your audience’s Last Active Device, which is likely the device that you want to target anyway.

If you set up a campaign and don’t use the Last Active setting, we’ll send your push notification to all of your audience’s push-eligible devices.

What to do when someone logs out of your app

When a person logs out of your app, you should use our SDKs’ clearIdentify method to disassociate the device token from the user in the current session. This ensures that you respect the privacy of your users and don’t inadvertently send push notifications to the wrong user (if the device has multiple users).

What happens to old/invalid device tokens?

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

Device _last_status

Devices have a status (represented by _last_status in the API), that we update automatically when you identify someone or send them a push notification. This status represents the state of the last push notification sent to the push notification service, and can be one of unused, sent, bounced, or suppressed.

The unused status means that you either haven’t sent a push notification to a device, or the pushes you’ve sent to the device failed.

When you send a push notification to a device, we update the status of that device as reported by the push notification service (FCM or APNs).

• sent: The push was accepted by the push notification service.
• bounced: The last push notification bounced. This means that the user uninstalled your app, or the device was unable to receive your notification because it device was off, no longer exists, was in airplane mode, etc.
• suppressed: The last two push notifications bounced. We will stop attempting to send push notifications to this device.

If the last status of the device is bounced or suppressed, and you identify the user with the same device token, we’ll clear this status, and it will return to “unused” (or, in the API, an empty string). You should refresh device tokens and identify people when they open your app or log in to help refresh this status.

How do I know if someone is opted into push notifications?

Our SDKs record whether or not a device is opted-into notifications with the push_enabled attributeA 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.. This attribute is set to true if a customer has enabled push notifications for your app, and false if they disabled notifications.

The push_enabled attribute does not actually determine whether or not a person can receive push notifications. It simply records their status the last time they opened your app. A person’s opt-in status is set at the operating system level and logged by your push provider (APN or FCM)—and all of that happens outside your app.

While you can use this attribute to get a general idea of which devices and people are opted into push notifications, it may not give you a perfectly accurate picture of your app audience in some situations for a few reasons:

1. It’s a lagging indicator of opt-in status: people set their opt-in status outside of your app, and the app must be open to record changes to this attribute.
2. If you use our Subscription CenterCustomer.io’s subscription center feature provides a way for customers to subscribe to, or unsubscribe from, specific topics. This helps you manage your audience’s preferences and make sure that they only get the messages they’re interested in., the push_enabled attribute does not account for your audience’s subscription preferences.
3. People must have a version of your app with our SDK installed to record this attribute.

The third issue above is the trickiest, especially if you’re coming to Customer.io from another push provider. When you import your push audience, these devices may be opted into push notifications, but they won’t have a push_enabled attribute until your audience updates to a version of your app that includes the Customer.io SDK. This can make it challenging to get a sense of your total audience size.

Push preferences are set outside your app

Your audience changes their push preferences outside your application. The push_enabled attribute simply records this setting when your audience opens your app. If a person changes their push preference, and your app isn’t open, the SDK cannot record the change until the next time they open your app.

Some users are opted-out of push notifications by default

In many cases, people who first open your app must opt into push notifications before they can receive messages from you. The default opt-in status is determined by each device’s operating system:

• iOS: People are opted out by default. They must opt in to receive push notifications.
• Android 13 or newer: People are opted out by default. They must opt in to receive push notifications.
• Android 12 or older: People are opted in by default. They must opt out to stop receiving push notifications.

When your audience first opens your app, you can expose a system prompt to opt people into notifications, but their opt-in status is recorded by the operating system. Your audience can opt-into or out of notifications at any time, and this all happens outside of your app.

For versions of your app using our SDK, we’ll record this status as the push_enabled attribute the next time your audience opens your app.

People can be unsubscribed when push_enabled is true

Imagine you have a customer who has opted into push notifications on their device. Their push_enabled attribute is set to true.

Then, later, they get an email from you and decide to opt out of all notifications. This sets their unsubscribed attribute to true. This attribute prevents them from receiving email, push, and SMS messages—despite the person having explicitly opted into push notifications. You can override this setting and send to unsubscribed people, but you should be careful to observe your audience’s subscription preferences where possible.

This person may have devices where the push_enabled attribute is true (and accurately reflects their push opt-in status), but they won’t receive push notifications because they’ve unsubscribed from all of your messages. Where push_enabled is a lagging indicator of push preferences, unsubscribed is an immediate and deterministic preference. A person with unsubscribed set to true will not receive push notifications, regardless of their push_enabled attribute.

Transactional push notifications are an exception to this rule. Unsubscribed people are still eligible for transactional push notifications.

Using push_enabled as segment criteria

You may not want to use the push_enabled attribute as criteria for a segmentA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions., especially if you’re migrating from another push provider. The push_enabled attribute is a lagging indicator of push preferences, and it may not reflect the real push audience.

If you look at a segmentA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. of people with push_enabled set to true, your segment may:

• Include people whose unsubscribed attribute or subscription preferences exclude them from push notifications.
• Exclude people with versions of your app that don’t have the Customer.io SDK.
• Not reflect your audience’s most recent preferences.

In general, you should probably use more actionable criteria to target your audience. You likely don’t want to send a message to everybody who is opted-into push notifications. You’d rather send targeted messages to people who:

• Need to update your app (i.e. their app version is below a certain number).
• Haven’t engaged with a specific screen or feature in your app.
• Have items in their cart and haven’t completed their purchase.