Device management

We automatically set the last status of a push notification sent to devices, helping you determine who is, and who isn’t, getting your messages.

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.

flowchart LR a[person opens app
or logs in] --> |"identify call"|h{has device been sent
a successful push?} h -->|yes|d[last status
is sent] h -->|no|i[last status
is unused] d --> e[send push] i --> e e --> k{did push provider
accept the push?} k --> |yes|b[last status
is sent] k --x |no|c{is this the first
failed push?} c --> |yes|l[last status
is bounced] c --> |no|m[last status
is suppressed]

 Do not segment your audience using last status yet

Segmenting on devices today selects a person, not a device, and a person can have multiple devices. So, if you segment based on device values like last status, your segment may inadvertently include or exclude people (and, by extension, their devices).

We’re working on a solution to help you target devices specifically. But, until then, you probably don’t want to use last status in segments.

Device lifecycles

Whether you use our SDKs or write your own integration, you should refresh the device token and identifyThe operation that recognizes a person. When you call the method or API to identify a person, 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. a user whenever someone opens your app or logs in. Identifying a person and associating a device with them does a few things:

  • It ensures you’re working with a valid device token.
  • It associates the device with a person, if it isn’t already, so that you can send messages, track events for that person, etc.
  • If you use our SDKs: this automatically associates future calls with the current device and user.
  • It resets the last status for the person if they previously had a status of bounced or suppressed, so that they can continue receiving messages.

When a person logs out of your app, you should delete the device. This ensures that that respect the privacy of your users and don’t inadvertently send push notifications to the device that are intended for another person who might log in after the previous user logged out. Deleting the device makes sure that it is no longer associated with a person and cannot receive messages intended for that person.

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

flowchart LR a[send push]-->b{Is the push sent?} b-->|yes|c[display push] b-.->|no, device token
is unregistered|d[delete device] class d mermaid-error classDef mermaid-error fill: #ffedf0,color: #69002c, stroke:#69002c
Copied to clipboard!
Is this page helpful?