Skip to content

Push Stories

Push Stories allow marketers to use photo carousel functionality to create a sequence of pages within a push notification. These pages consist of an image, click action, title, and description.

Setting up Push Stories for your iOS app requires additional steps beyond integrating standard push notifications, which are outlined in this article.


The following SDK versions is required to receive Push Stories:

Ensure that you have followed the push notification integration tutorial to enable push in your app. As part of this task, you should have implemented the UNNotification framework, which is required for this feature.

Step 1: Adding the Notification Content Extension target

In your app project, go to menu File > New > Target and add a new Notification Content Extension target and activate it.

Xcode should generate a new target for you and create files automatically for you including:

  • NotificationViewController.swift
  • MainInterface.storyboard

Step 2: Enable capabilities

In Xcode, add the Background Modes capability using the Signing & Capabilities pane to the main app target. Select both the Background fetch and Remote notifications checkboxes.

Additionally, from the Signing & Capabilities pane in Xcode, add the App Groups capability to your main app target as well as the Notification Content Extension targets. Then, click the + button. Use your app’s bundle ID to create the app group. For example, if your app’s bundle ID is, you can name your app group

Step 3: Adding the Push Story framework to your app

After following the Swift Package Manager integration guide, add BrazePushStory to your Notification Content Extension:

In Xcode, under frameworks and libraries, select the "+" icon to add a framework.

Add the following line to your Podfile:

target 'YourContentExtensionTarget' do
  pod 'BrazePushStory'

After updating the Podfile, navigate to the directory of your Xcode app project within your terminal and run pod install.

Download the latest from the GitHub release page, extract it, and add the BrazePushStory.xcframework to your project’s Notification Content Extension:

Step 4: Updating your notification view controller

In NotificationViewController.swift, add the following line to import the header files:

import BrazePushStory

Next, replace the default implementation by inheriting BrazePushStory.NotificationViewController:

class NotificationViewController: BrazePushStory.NotificationViewController {}

Step 5: Setting the Notification Content Extension plist

Open the Info.plist file of the Notification Content Extension, then add and change the following keys under NSExtension \ NSExtensionAttributes:

Key Type Value
UNNotificationExtensionCategory String ab_cat_push_story_v2
UNNotificationExtensionDefaultContentHidden Boolean YES
UNNotificationExtensionInitialContentSizeRatio Number 0.6
UNNotificationExtensionUserInteractionEnabled Boolean YES

Your Info.plist file should match the following image:

Step 6: Updating the Braze integration in your main app

Before initializing Braze, assign the name of your app group to your Braze configuration’s push.appGroup property.

let configuration = Braze.Configuration(apiKey: "<YOUR-BRAZE-API-KEY>",
                                        endpoint: "<YOUR-BRAZE-ENDPOINT>")
configuration.push.appGroup = "REPLACE_WITH_APPGROUP"
let braze = Braze(configuration: configuration)
New Stuff!