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
Opted-In, as well as Push Enabled.
Push Subscription State
|Opted-In||A user has explicitly allowed 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 Users Push Subscription State:
- 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.
- 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.
A user is “Push Enabled” or “Push Registered” if they have an active push token for an app in your app group.
On the User Engagement tab in the dashboard, you will see: Push Registered For followed by an App Name(s) or followed by No Apps. 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.
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 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.
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.
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).
- (For Android SDK v2.2.2+) The user blocks push notifications for the app within their device settings and subsequently logs a session.
Before Android SDK v2.2.2
Here are some details you should know if you aren’t using our most up-to-date Android SDK.
- The previous version of the Android SDK does not detect that a user has disabled push, and so the user’s push enabled state remains enabled. When you attempt to send to a device in this state, the push is ‘sent’, and the device receives the payload but is suppressed by the device, so it is not displayed to a user. Braze refers to this as ‘silently failing’.
- The previous version of the Android SDK does not have the
notifications_enabledparameter and will not return a value for it if user data is called using the Braze REST API.