Skip to content

Push enablement and push subscription

This reference article covers the concepts of push enablement and push subscription states in Braze, including the fundamental differences in behavior across iOS, Android, and Web.

Push subscription states

A “Push Subscription State” in Braze identifies a user’s global preference for their desire to receive push notifications. Because the subscription state is user-based, it is not specific to any individual app. Subscription states become helpful flags when deciding which users to target for push notifications.

There are three push subscription state options: Subscribed, Opted-In, and Unsubscribed.

By default, for your user to receive your messages through push, their push subscription state must be either Subscribed or Opted-In, and they must be push enabled. You can override this setting if needed when composing a message.

Opt-in State Description
Subscribed Default push subscription state when a user profile is created in Braze.
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 if a user accepts an OS-level push prompt.

This does not apply to Android 12 or below users.
Unsubscribed A user explicitly unsubscribed from push through your application or other methods your brand provides. By default, Braze push campaigns only target users that are Subscribed or Opted-in for push.

Updating push subscription states

There are three ways a user’s push subscription state can be updated:

  1. SDK integration
    Use the Braze SDK to update a user’s subscription state. For example, you can add a settings page to your app where users can turn push notifications for their profile on or off.
    To do this, use the setPushNotificationSubscriptionType method on Web, Android, or iOS.

  2. REST API
    Use the /users/track endpoint to update the push_subscribe attribute for a given user.

  3. Automatically during opt-in
    When a user accepts the native OS push permission prompt, Braze will automatically change that user’s subscription state to Opted-In.

Checking push subscription state

User profile for John Doe with their push subscription state set to Subscribed.

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.

Push permission

All push-enabled platforms - iOS, Web, and Android - require explicit opt-in via an OS-level system prompt, with some slight differences described below.

Because a user’s decision is final and you can’t ask again after they decline, using push primer in-app messages is an important strategy for increasing your opt-in rates.

Native OS push permission prompts

Platform Screenshot Description
iOS An iOS native push prompt asking "My App would like to send you notifications" with two buttons, "Don't Allow" and "Allow" at the bottom of the message. This does not apply when requesting provisional push permission.
Android An Android push message asking "Allow Kitchenerie to send you notifications?" with two buttons, "Allow" and "Don't allow" at the bottom of the message. This push permission was introduced in Android 13. Before Android 13, permission was not required to send push.
Web A web browser's native push prompt asking "Braze.com wants to show notification" with two buttons, "Block" and "Allow" at the bottom of the message.  

Android

Before Android 13, permission was not needed to send push notifications. On Android 12 and below, 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.

Starting with Android 13, push permission must be asked of and granted by the user. Your app can manually request permission from the user at opportune times, but if not, users will be prompted automatically when your app creates a notification channel.

iOS

A notification in the system Notification Center with a message at the bottom asking, "Keep receiving notifications from the Yachtr app?" with two buttons below to "Keep" or "Turn Off"

Your app can request provisional push or authorized push.

Authorized push requires explicit permission from a user before sending any notifications, whereas provisional push lets you send notifications quietly, directly to the notification center without any sound or alert.

Provisional authorization and quiet push

Before iOS 12 (released in 2018), all users must explicitly opt-in to receive push notifications.

In iOS 12, Apple introduced provisional authorization, allowing brands to send quiet push notifications to their users’ notification center before they explicitly opt-in, giving you a chance to demonstrate the value of your messages early. Refer to provisional authorization to learn more.

Web

For Web, you must request explicit user opt-in via the native browser permission dialog.

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.

As a result, you should ask for permission only when a user clicks somewhere on your website and not randomly when a page loads.

Push tokens

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.

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 provides the ability to send regular visible push notifications to the foreground of a user’s device.
  2. Background push is 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:

Push token changelog on the **Engagement** tab of a user's profile, which lists when the push token was moved to another user, and what the token was.

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.

Multiple devices and one user

The push subscription state is user-based and is not specific to any individual app. The state of the push subscription is the value that was last set. So if a user has opted-in to push notifications, their push subscription state is Opted-in across all eligible devices. If a user later explicitly unsubscribes from push notifications through your application or other methods your brand provides, their push subscription state is updated to Unsubscribed and no push-registered devices can receive push notifications.

Push Enabled filter

Push Enabled is a segmentation filter in Braze that allows marketers to easily identify users that allow Braze to send push notifications and users that haven’t expressed preferences to not receive push notifications.

The Push Enabled filter takes into account the following:

  • The ability for Braze to send a push notification (foreground push token)
  • The user’s overall preference to receive push on any of their devices (push subscription state)

A screenshot of the dashboard showing a user is "Push Registered for Marketing (iOS)"

A user is considered “push enabled” or “push registered” if they have an active foreground push token for an app within your workspace, meaning push enablement status is app-specific.

Other platform-specific scenarios

If a foreground push enabled user disables push in their OS settings, then at the start of the next session:

  • Braze marks them as foreground push disabled and no longer attempts to send them push messages.
  • The Push Enabled for App (Android) filter and the Push Enabled segmentation filter (assuming no other apps on the user profile have a valid foreground push token) will return false.

In this scenario, since a background push token will still exist, you can continue to send background (silent) push notifications with the segmenting filter Background Push Enabled = true.

For Android, Braze will consider a user push disabled if:

  • A user uninstalls the app from their device.
  • A push message fails to deliver due to a bounce. This is often caused by an uninstall, but can also be due to app updates, new push token version, or format.
  • Push registration fails to Firebase Cloud Messaging (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.

Regardless of if a user accepts the foreground push opt-in prompt, you will still be able to send a background push if you have remote notifications enabled in Xcode and your app calls registerForRemoteNotifications().

If your app is provisionally authorized or the user has opted into push, they receive a foreground push token, allowing you to send them 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).

If a user declines to receive push notifications on an OS-level, their push subscription state will be Subscribed, and their profile will not show that a foreground push token has been registered.

In the scenario that a user, who initially opted-in on the OS level disables push notifications in their OS settings, at the next session start, the following will occur:

  • Braze marks them as foreground push disabled and no longer attempts to send push messages.
  • The Push Enabled for App (iOS) filter and the Push Enabled segmentation filter (assuming no other apps on the user profile have a valid foreground push token) will return false.

In this scenario, since a background push token will still exist, you can continue to send background (silent) push notifications with the segmenting filter Background Push Enabled = true.

When a user accepts the native push permission prompt, their subscription status will be changed to opted in.

To manage subscriptions, you can use the user method setPushNotificationSubscriptionType to create a preference settings page on your site, after which you can filter users by opt-out status on the dashboard.

If a user disables notifications within their browser, the next push notification sent to that user will bounce, and Braze will update the user’s push token accordingly. This is used to manage eligibility for the push-enabled filters (Background Push Enabled, Push Enabled and Push Enabled for App). The subscription status set on the user’s profile is a user-level setting and doesn’t change when a push bounces.

Best practices

Refer to our dedicated article on Push best practices for detailed guidance on how to optimize your usage of push at Braze.

HOW HELPFUL WAS THIS PAGE?
New Stuff!