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.

Updating push subscription states

There are three ways you can update a user’s push subscription state:

Automatic opt-in (default)

By default, Braze sets a user’s push subscription state to Opted-In when they first authorize push notifications for your app. Braze also does this when a user re-enables push permissions in their system settings after previously disabling them.

• android
• swift

1
<bool name="com_braze_optin_when_push_authorized">false</bool>

1
2
3
4
configuration.optInWhenPushAuthorized = false // disables the default behavior

let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

SDK integration

You can update a user’s subscription state with the Braze SDK using the setPushNotificationSubscriptionType method on Web, Android, or iOS. For example, you can use this method to create a settings page in your app where users can manually enable or disable push notifications.

REST API

You can update a user’s subscription state with the Braze REST API using the /users/track endpoint to update their push_subscribe attribute.

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

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		This does not apply when requesting provisional push permission.
Android		This push permission was introduced in Android 13. Before Android 13, permission was not required to send push.
Web

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

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:

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

• android
• ios
• web

Best practices

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