In order to send push notifications, a device token (also known a push token) is required. Push service providers generate device tokens. Customer.io SDKs connect with push service providers like Firebase Cloud Messaging Service (FCMs) for Android and Apple Push Notification Service (APNs) for iOS, and those providers send unique device tokens that identify your app. Each device has one, unique token that is used for messaging. Tokens can expire or be updated.
Creation and management of device tokens
When a user opens a new application and grants push access from a push prompt, a call is made from the Customer.io SDK to the push providers. When that call is made, the push provider checks to see if everything is set up correctly.
If so, a push token gets passed into the user’s device. When that token arrives, the SDK communicates this to Customer.io. Once Customer.io has received the token from the push provider, we update or create a new user profile. These users are now considered registered. When you send a user a push notification via Customer.io, we send a push payload to the push provider. From there, the provider delivers the push payload to the user’s device, and then the SDK passes the messaging state back to Customer.io.
Subsequent new device tokens are generated when the user restores a device from a backup, when the user installs your app on a new device, and when the user reinstalls the operating system.
Device tokens are created and managed by push notification providers so they are not controlled by Customer.io but there is ways that you can gain insight into the status of a device token in Customer.io.
Device token expiry
Unfortunately, push providers APNs and FCM don’t explicitly define the circumstances under which they expire device tokens. Device tokens can expire when an app is updated, when users transfer their data to a new device, or when they re-install an operating system. However, none of these reasons are guaranteed circumstances in which a device token will be reset and it’s possible to have a user that has continuously updated their app but still has the same device token. For the most part, no one push messaging provider has insight into why push providers will expire certain tokens.
Status of device tokens in Customer.io
Device tokens in Customer.io must be associated with an identified user; this means that your app requires people to log in or otherwise make themselves known to you; a device token cannot be “anonymous” in Customer.io.
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 indicates the response received from the push notification service (FCM or APNs) when you last sent a push notification to that user and it will be one of the following statuses: unused, sent, bounced, or suppressed.
- Unused: This status means that you either haven’t sent a push notification to a device, or the pushes you’ve sent to the device failed.
- 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 the 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).
Automatic clean-up
Beginning January 31, 2023, Customer.io introduced automatic device clean-ups to help you maintain a better understanding of your audience’s devices, so you know which devices are relevant and can get a real device count—without having to clean up old devices yourself.
This means that we remove device tokens if we try to send a push and the push service tells us that the token is invalid.
You can see in the example below that a push notification was sent to the user that failed to send for the reason that “The user has uninstalled the application”, so in response Customer.io removes the device token that was used to send that message.
If you're using a segment to define your campaign or broadcast audience, a person would remain in the segment if they still have other tokens (other devices that could receive a push) or rejoin the segment when Customer.io identifies their device again.
An unregistered token can’t get a message, so the result of having bad or no tokens is the same.
Scenarios
To help contextualize these details a little more, I thought sharing a few examples with you might be helpful.
Scenario One:
A new user signs up via the app, creates an account, and enables push notifications. They become an identified user in Customer.io with a device token. They don't log out of the app or change their device. Their device token remains the same, and they continue to receive push notifications from you as expected. You can see an example of a customer on the latest version of an app here but who’s device token hasn’t changed since they downloaded the app.
Scenario Two:
A user signs up to your application as per scenario one, and they receive push notifications. However, they decide to delete your app. You send a user a push notification, and Customer.io receives an update from the push provider that they have uninstalled your app. This means the device token is invalid, and we delete this unregistered device. You can see an example of this below. Specifically, you can see under Source: Customer.io Automated Device Clean-up Reason Reason: APNS_Unregistered. Apple Push Notifications informs Customer.io that the user has deleted their mobile app.
Scenario Three:
A user signs up to your application as per scenario one, and they receive push notifications. You send a user a push notification, and Customer.io receives an update from the push provider that the device token is invalid. This could be because the user has logged out of your app or the push provider has randomly changed the device token.
You can identify these users by reviewing users in your account who had received a push notification in the past but don't have a device token now.
Lastly, don’t forget to check out our full documentation for additional details on device tokens in Customer.io.
Do you have any other questions about device tokens and how they work in Customer.io?
