Push registration

This article covers the process through which a user gets assigned a push token, and how Braze sends push messages to your users.

Push tokens

Understanding push tokens and what they are is a fundamental piece of understanding how we send push messages here at Braze. Push tokens are a unique anonymous identifier generated by a user’s device and sent to Braze to identify where to send each recipient’s notification. If a device doesn’t have a push token, there is no way to send push to it.

Push tokens are generated by push service providers. Braze connects 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.

There are two ways a push token can be classified that are essential to understanding how a push notification can be sent to your users.

1. Foreground push provide the ability to send regular visible push notifications to the foreground of a user’s device.
2. Background push are available regardless of whether a particular device has opted-in to receive push notifications from that brand. Background push allows brands to send silent push notifications - notifications that intentionally aren’t displayed - to devices to support key functionalities like uninstall tracking.

When a user profile has a valid foreground push token associated with an app, Braze considers the user “push registered” for the given app. Braze, then, provides a specific segmentation filter, Push enabled for App, to help identify these users.

Multiple users on one device

Push tokens are specific to both a device and app, so it isn’t possible to use push tokens to distinguish between multiple users who are using the same device.

For example, say you have two users: Charlie and Kim. If Charlie has enabled push notifications for your app on his phone and Kim uses Charlie’s phone to log out of Charlie’s profile and log into her own, the push token will be re-assigned to Kim’s profile. The push token will then remain assigned to Kim’s profile on that device until she logs out and Charlie logs back in again.

An app or website can only have one push subscription per device. So when a user logs out of a device or website, and a new user logs in, the push token gets reassigned to the new user. This is reflected on the user’s profile in Contact Settings section of the Engagement tab:

Because there isn’t a way for push providers (APNs/FCM) to distinguish between multiple users on one device, we pass the push token to the last user who was logged in to determine which user to target on the device for push.

Push token registration

Platforms deal with push token registration and push permissions in different ways:

• Android:
  • Android 13:
    Push permission must be asked of and granted by the user. Receives a token after permission is granted by the user. Your app can manually request permission from the user at opportune times, but if not, users will be prompted automatically after your app creates a notification channel.
  • Android 12 and earlier:
    All users are considered Subscribed upon their first session when Braze automatically requests a push token. At this point, the user is push enabled with a valid push token for that device and a default subscription state of Subscribed.
    
    
• iOS: Not automatically registered for push.
  • iOS 12 (with Provisional Authorization):
    Your app can request provisional authorization or authorized push. Authorized push requires explicit permission from a user before sending any notifications (receives a token after permission is granted by user), whereas [provisional push][provisional-blog] lets you send notifications quietly, directly to the notification center without any sound or alert.
  • iOS 11 and later & iOS 12 (without Provisional Authorization):
    All users must explicitly opt-in to receive push notifications. Will receive a token after users opted-in.
    
    
• Web: You must request explicit opt-in from users via the native browser permission dialog. Will receive a token after users opt-ed in. Unlike iOS and Android, which let your app show the permission prompt at any time, some modern browsers will only show the prompt if triggered by a “user gesture” (mouse click or keystroke). If your site tries to request push notification permission on page load, it will likely be ignored or silenced by the browser.

Get a push token	Send a push token
Applications must register with a push provider in order to get a push token for a device.	Developers can then target the device using the push token generated by FCM/APNs.

Check user’s push subscription state

There are two ways you can check a user’s push subscription state with Braze:

1. User Profile: You can access individual user profiles through the Braze dashboard on the User Search page. After finding a user’s profile (via email address, phone number, or external user ID), you can select the Engagement tab to view and manually adjust a user’s subscription state.
   
2. Rest API Export: You can export individual user profiles in JSON format using the export Users by segment or Users by identifier endpoints. Braze will return a push tokens object that contains push enablement information per device.

Checking push registration status

On the Engagement tab in a user’s profile, you will see Push Registered For followed by an app name. If no app information exists for that device, you will see two dashes (--). There will be an entry for every device that belongs to the user.

If the device entry’s app name is prefixed by Foreground:, the app is authorized to receive both foreground push notifications (visible to the user) and background push notifications (not visible to the user) on that device.

On the other hand, if the device entry’s app name is prefixed by Background:, the app is only authorized to receive background push and cannot display user-visible notifications on that device. This usually indicates the user has disabled notifications for the app on that device.

If a push token is moved to a different user on the same device, that first user will no longer be push registered.

Push token management

Check out the following chart for actions that lead to push tokens changes or removal from user profiles.

Action	Description
changeUser() method called	The Braze changeUser() method switches the user ID that the SDKs are assigning user behavior data to. This method is usually called when a user logs into an application. When changeUser() is called with a different or new user ID on a specific device, that device’s push token will be moved to the appropriate Braze profile with corresponding user ID.
Push error occurs	Some common push errors that lead to token removal include MismatchSenderId, InvalidRegistration, and other types of push bounces. Check out our full list of common push errors.
User uninstalls	When a user uninstalls the application from a device, Braze will remove the user’s push token from the profile.

What does this look like on a broader scale?

When a user opens a new application and grants push access from a push prompt, a call is made from the Braze SDK to the push providers. When that call is made, the push provider runs a check to see if everything is set up correctly. If so, a push token gets passed into your device. When that token arrives, the SDK communicates this to Braze. After Braze has received the token from the push provider, we update or create a new user profile. These users are now considered registered.

If we want to launch a campaign, we create a campaign in Braze that generates a push payload to send to the push provider. From there, the provider delivers the push payload to the user’s device and the SDK passes the messaging state to Braze.

Registration steps	Messaging steps
1. Customer (device) registers to push provider 2. Provider generates and delivers push token 3. Flush tokens in Braze	1. Braze sends push payload to provider 2. Provider delivers the push payload to the device 3. SDK passes messaging stats to Braze

Frequently asked questions

What happens when an opted-in user deletes and then redownloads my app?

Suppose a user opts-in for push, receives some push messaging, and then later deletes the app. This will remove the push consent at the device level. From here, the first bounced push after the uninstall will automatically result in that user being opted-out of future push messaging. After this, if a user were to reinstall the app but not launch it, Braze won’t be able to send a push to the user because push tokens have not been re-granted for your app.

Additionally, if a user were to re-enable foreground push, it would require a session start to update this information in their user profile to begin receiving push messaging.

When do push tokens expire?

Unfortunately, APNs and FCM don’t really define this. Push 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. For the most part, we don’t really have insight into why push providers will expire certain push tokens.

To account for that ambiguity, our SDK push integrations always register and flush tokens on session start to ensure we have the most up-to-date token.