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 recognizes a person. When you call the method or API to identify a person, Customer.io either adds a person if they don’t exist in your workspace, or otherwise updates/associates data with a person. Activities before a person is identified may be attributed to an anonymous ID. 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.
• 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 Statuses

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.