Push Enablement and Subscription

Push subscription states are filters that allow your users to control whether they receive messages or not. For your user to receive your messages through push, they must be Subscribed or Opted-In, as well as Push Enabled.

Opt-in Option

Push Subscription State

Opt-in State Description
Subscribed Default status.
Opted-In A user has explicitly expressed a preference to receive push notifications. Braze will automatically move a user’s opt-in state to “Opted-In”.
Unsubscribed A user explicitly unsubscribed from push through your application UI or other methods that your brand provides. By default, Braze push campaigns only target users that are “Subscribed” or “Opted-in” for push.

Subscription states are helpful flags for brands to use when deciding which users to target for push notifications. Brands may provide simple toggles in their applications to make it simple for users to determine their push notification status. This helps prevent users from going into device settings and removing push tokens completely.

Note that even though users may not have a push token (e.g., They turn off push tokens at the device level through settings, opting not to receive messages), they still may be subscribed. Being subscribed does not guarantee that a push will be delivered; users must also be Push enabled or Push registered to receive these notifications. This is done in part because users have a single Push Subscription State but may have multiple devices with different levels of push permissions.

Two Ways to Check a User’s Push Subscription State:

Push Example

  1. User Profile: Individual user profiles can be accessed through the Braze dashboard by selecting User Search from the right sidebar. Here, you can look up user profiles by email address, phone number, or external user ID. Once in a user profile, under the Engagement tab, you can view and manually adjust a user’s subscription state.

  2. Rest API Export: Individual user profiles can be exported in the JSON format using the users/export/ segment or identifier endpoints by using Braze’s REST API. Braze will return a push tokens object that contains push enablement information per device.

Push Enablement

A user is “Push Enabled” or “Push Registered” if they have an active push token for an app in your app group.

Push Enablement

On the User Engagement tab in the dashboard, you will see: Push Registered For followed by an App Name(s) or followed by --. 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 can not display user-visible notifications on that device. This usually indicates the user has disabled notifications for the app on that device. Push Changelog

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

iOS & Android Push Details

iOS Push

iOS Push States
Push Enabled - If Braze has a push token for the device
Push Opt-In State - If the user has expressed a preference to send them push notifications.

For iOS, to receive a push token, you must request whether the user would like to receive push. Dependent on the user’s response, Braze will adjust the user’s push subscription state to opted in if accepted or keep the push subscription state as subscribed if rejected. Before this, the opt-in state will be subscribed. Upon receiving a response, Braze will attempt to register the user for push. After Braze successfully receives a token, we will update the user’s push-enabled state.

Enabled State
There exist two enabled states, Foreground push enabled (opted-in), and Background push enabled (opted-out). Regardless of the response to the opt-in prompt, the user will receive a background push token (you must have “Remote Notifications” enabled in Xcode), allowing them to be sent silent push. If your app is provisionally authorized, or the user has opted into push, they will receive a foreground push token as well, allowing them to be sent all types of push. Within Braze, we consider a user on iOS who is foreground push enabled to be ‘push enabled’, either explicitly (app-level) or provisionally (device-level).

Enabled State and Opt-In
For iOS, on the subsequent app open, the SDK will detect that push has been disabled and will notify Braze. At this point, Braze will update the push-enabled state to disabled. When you attempt to send a push to a user, Braze is already aware of whether we have a token, so notifications only get sent to the people who explicitly state they want them.

Provisional Authorization and Quiet Push
In iOS 12, Apple introduced Provisional Authorization, allowing brands the option to send quiet push notifications to their users’ Notification Centers before they officially explicitly opt-in, giving you a chance to demonstrate the value of your messages early. Check out our documentation to learn more about provisional authorization.

On devices running iOS 11 or below, your users must explicitly opt-in to receive your push messages. You must request whether the user would like to receive push from you.

Android Push

You do not need to request permission to send push notifications to Android users. As the user has not explicitly requested to receive push, Braze will not automatically update the user’s opt-in state. Upon a user’s first session on Android, Braze will automatically request a new token, and upon successfully receiving that token, an update to the user’s push enabled state will happen. At this point, a user has push enabled at both the app-level and the device-level.

If the user disables push, Braze will mark them as foreground push disabled and no longer attempt to send them push messages. The filter Push Enabled will result in false for this user. You may continue to send background (silent) push notifications with the segmenting filter Background Push Enabled = true.

On Android, Braze will move a user to be push disabled if:

  • A user uninstalls the app from their device.
  • Braze receives a bounce when sending to a specific token (sometimes caused by app updates, uninstalls, new push token version, or format).
  • Push registration fails to FCM (sometimes caused by poor network connections or a failure to connect to or on FCM to return a valid token).
  • The user blocks push notifications for the app within their device settings and subsequently logs a session.
New Stuff!