About push subscription states

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.

note

A user’s push subscription state applies to their entire user profile, which includes all of the user’s devices.

The following subscription state options exist: 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 have foreground push enabled. You can override this setting if needed when composing a message.

important

Braze does not automatically change a user’s push subscription state to Unsubscribed. Remember that if a user’s push subscription state is Unsubscribed, then the user’s Foreground Push Enabled filter in segmentation is false.

Push registration and reachable users

Push subscription state reflects a user’s preference, but whether they count as reachable for push in the dashboard also depends on push registration—that is, a valid foreground push token on their profile. For how Braze calculates channel-level counts, see Measure segment size.

• Push campaigns and Canvases: Users who aren’t push registered aren’t included in Reachable users for Android Push or iOS Push in audience statistics, even when their push subscription state is Subscribed or Opted-In.
• Other channels: The same users can still count as reachable for other channels they qualify for (for example, email or in-app messages).
• Segments: Segment membership follows your filters. Users without push registration remain in the segment unless a filter excludes them (for example, Foreground Push Enabled). Total segment membership can be higher than the sum of users shown in push-specific Reachable users rows.

A user profile can show push subscription state Subscribed while no push token is assigned. Those users still don’t count toward Reachable users for Android Push or iOS Push until Braze records a valid token.

For filter definitions, see Segmentation filters.

Updating push subscription states

Review the following ways to 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.

Differences between push enablement and push subscription status

Push enablement refers to whether a user has granted OS- or browser-level permission to receive notifications on a specific device. Push subscription state is a Braze-level setting that represents a user’s global preference for receiving push across their profile.

When automatic opt-in is enabled (the default), Braze updates a user’s push subscription state to Opted-In when they authorize push notifications for your app or re-enable permissions in their system settings (for example, on iOS, Android 13+, and supported web browsers). Otherwise, the user’s push subscription state remains Subscribed until you explicitly change it using an SDK method or REST API call.

Braze does not automatically change a user’s push subscription state to Unsubscribed when they opt out of notifications at the OS, browser, or app level. To update a user’s push subscription state, you must update it in Braze. For example, if a user disables push from an in-app preference center, update the push subscription state to Unsubscribed in Braze. Braze does not update user profiles based on your preference center. To align subscription states with a user’s in-app preferences, call the appropriate methods using the SDK (iOS or Android) or REST API.

Checking push subscription state

You can check a user’s push subscription state with Braze in any of the following ways:

• 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.
• REST API export: You can export individual user profiles in JSON format using the export Users by segment or Users by identifier endpoints. Braze returns a push tokens object that contains push enablement information per device.