Live Activities

Live Activities are persistent, interactive notifications displayed on your lock screen, allowing you to keep an eye on things in real-time. Because they appear on the lock screen, Live Activities ensure that your notifications won’t be missed. Because they’re persistent, you can display up-to-date content to your users without even having them unlock their phone.

About Live Activities

Live Activities present a combination of static information and dynamic information that you update. For example, you can create a Live Activity that provides a status tracker for a delivery. This Live Activity would have your company’s name as static information, as well as a dynamic “Time to delivery” that would be updated as the delivery driver approaches its destination.

As a developer, you can use Braze to manage your Live Activity lifecycles, make calls to the Braze REST API to make Live Activity updates, and have all subscribed devices receive the update as soon as possible. And, because you’re managing Live Activities through Braze, you can use them in tandem with your other messaging channels—push notifications, in-app messages, Content Cards—to drive adoption.

Prerequisites

Additional prerequisites include:

• Live Activities are only available for iPhones and iPads on iOS 16.1 and later. To use this feature, ensure that your project is targeting this iOS version.
• The Push Notification entitlement must be added under Signing & Capabilities in your Xcode project.
• Live Activities require using a .p8 key to send the notification. Older files such as a .p12 or .pem are not supported.
• Starting with version 8.2.0 of the Braze Swift SDK, you can remotely register a Live Activity. To use this feature, iOS 17.2 or later is required.

Implementing a Live Activity

Step 1: Create an activity

First, ensure that you have followed Displaying live data with Live Activities in Apple’s documentation to set up Live Activities in your iOS application. As part of this task, make sure you include NSSupportsLiveActivities set to YES in your Info.plist.

Because the exact nature of your Live Activity will be specific to your business case, you will need to set up and initialize the Activity objects. Importantly, you will define:

• ActivityAttributes: This protocol defines the static (unchanging) and dynamic (changing) content that will appear in your Live Activity.
• ActivityAttributes.ContentState: This type defines the dynamic data that will be updated over the course of the activity.

You will also use SwiftUI to create the UI presentation of the lock screen and Dynamic Island on supported devices.

Make sure you’re familiar with Apple’s prerequisites and limitations for Live Activities, as these constraints are independent from Braze.

Example

Let’s imagine that we want to create a Live Activity to give our users updates for the Superb Owl show, where two competing wildlife rescues are given points for the owls they have in residence. For this example, we have created a struct called SportsActivityAttributes, but you may use your own implementation of ActivityAttributes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
struct SportsActivityAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String
}

Step 2: Start the activity

First, choose how you want to register your activity:

• Remote: Use the registerPushToStart method early in your user lifecycle and before the push-to-start token is needed, then start an activity using the /messages/live_activity/start endpoint.
• Local: Create an instance of your Live Activity, then use the launchActivity method to create push tokens for Braze to manage.

• remote
• local

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
struct SportsActivityAttributes: ActivityAttributes, BrazeLiveActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String
  var brazeActivityId: String?
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {

  @available(iOS 17.2, *)
  func registerActivityType() {
    // This method returns a Swift background task.
    // You may keep a reference to this task if you need to cancel it wherever appropriate, or ignore the return value if you wish.
    let pushToStartObserver: Task = Self.braze?.liveActivities.registerPushToStart(
      forType: Activity<SportsActivityAttributes>.self,
      name: "SportsActivityAttributes"
    )
  }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {
  
  @available(iOS 16.2, *)
  func createActivity() {
    let activityAttributes = SportsActivityAttributes(gameName: "Superb Owl", gameNumber: "Game 1")
    let contentState = SportsActivityAttributes.ContentState(teamOneScore: "0", teamTwoScore: "0")
    let activityContent = ActivityContent(state: contentState, staleDate: nil)
    if let activity = try? Activity.request(attributes: activityAttributes,
                                            content: activityContent,
      // Setting your pushType as .token allows the Activity to generate push tokens for the server to watch.
                                            pushType: .token) {
      // Register your Live Activity with Braze using the pushTokenTag.
      // This method returns a Swift background task.
      // You may keep a reference to this task if you need to cancel it wherever appropriate, or ignore the return value if you wish.
      let liveActivityObserver: Task = AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "sports-game-2024-03-15",
                                                                                        activity: activity)
    }
  }
  
}

Step 3: Resume activity tracking

To ensure Braze tracks your Live Activity upon app launch:

1. Open your AppDelegate file.
2. Import the ActivityKit module if it’s available.
3. Call resumeActivities(ofType:) in application(_:didFinishLaunchingWithOptions:) for all ActivityAttributes types you have registered in your application.

This allows Braze to resume tasks to track push token updates for all active Live Activities. Note that if a user has explicitly dismissed the Live Activity on their device, it is considered removed, and Braze will no longer track it.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import UIKit
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

  static var braze: Braze? = nil

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    
    if #available(iOS 16.1, *) {
      Self.braze?.liveActivities.resumeActivities(
        ofType: Activity<SportsActivityAttributes>.self
      )
    }

    return true
  }
}

Step 4: Update the activity

The /messages/live_activity/update endpoint allows you to update a Live Activity through push notifications passed through the Braze REST API. Use this endpoint to update your Live Activity’s ContentState.

As you update your ContentState, your Live Activity widget will display the new information. Here’s what the Superb Owl show might look like at the end of the first half.

See our /messages/live_activity/update endpoint article for full details.

Step 5: End the activity

When a Live Activity is active, it is shown on both a user’s lock screen and Dynamic Island. There are a few different ways for a Live Activity to end and be removed from a user’s UI.

• User dismissal: A user can manually dismiss a Live Activity.
• Time out: After a default time of 8 hours, iOS will remove the Live Activity from the user’s Dynamic Island. After a default time of 12 hours, iOS will remove the Live Activity from the user’s lock screen.
• Dismissal date: You can provide a datetime for a Live Activity to be removed from a user’s UI prior to time out. This is defined either in the Activity’s ActivityUIDismissalPolicy or using the dismissal_date parameter in requests to the /messages/live_activity/update endpoint.
• End activity: You can set end_activity to true in a request to the /messages/live_activity/update endpoint to immediately end a Live Activity.

See our /messages/live_activity/update endpoint article for full details.

Frequently Asked Questions (FAQ)

Functionality and support

What platforms support Live Activities?

Live Activities are currently a feature specific to iOS. The Live Activities article covers the prerequisites for managing Live Activities through the Braze Swift SDK.

Do React Native apps support Live Activities?

Yes, React Native SDK 3.0.0+ supports Live Activities via the Braze Swift SDK. That is, you need to write React Native iOS code directly on top of the Braze Swift SDK.

There isn’t a React Native-specific JavaScript convenience API for Live Activities because the Live Activities features provided by Apple use languages untranslatable in JavaScript (for example, Swift concurrency, generics, SwiftUI).

Does Braze support Live Activities as a campaign or Canvas step?

No, this is not currently supported.

Push notifications and Live Activities

What happens if a push notification is sent while a Live Activity is active?

Live Activities and push notifications occupy different screen real estate and won’t conflict on a user’s screen.

If Live Activities leverage push message functionality, do push notifications need to be enabled to receive Live Activities?

While Live Activities rely on push notifications for updates, they are controlled by different user settings. A user can opt into Live Activities but out of push notifications, and the other way around.

Live Activity update tokens expire after eight hours.

Do Live Activities require push primers?

Push primers are a best practice to prompt your users to opt in to push notifications from your app. However, there is no system prompt to opt into Live Activities. By default, users are opted into Live Activities for an individual app when the user installs that app on iOS 16.1 or later. This permission can be disabled or re-enabled in the device settings on a per-app basis.

Technical topics and troubleshooting

How do I know if Live Activities has errors?

Any Live Activity errors will be logged in the Braze dashboard in the Message Activity Log, where you can filter by “LiveActivity Errors”.

After sending a push-to-start notification, why haven’t I received my Live Activity?

First, verify that your payload includes all the required fields described in the messages/live_activity/start endpoint. The activity_attributes and content_state fields should match the properties defined in your project’s code. If you’re certain that the payload is correct, its possible you may be rate-limited by APNs. This limit is imposed by Apple and not by Braze.

To verify that your push-to-start notification successfully arrived at the device but was not displayed due to rate limits, you can debug your project using the Console app on your Mac. Attach the recording process for your desired device, then filter the logs by process:liveactivitiesd in the search bar.

I am receiving an Access Denied response when I try to use the live_activity/update endpoint. Why?

The API keys you use need to be given the correct permissions to access the different Braze API endpoints. If you are using an API key that you previously created, it’s possible that you neglected to update its permissions. Read our API key security overview for a refresher.

Does the messages/send endpoint share rate limits with the messages/live_activity/update endpoint?

By default, the rate limit for the messages/live_activity/update endpoint is 250,000 requests per hour, per workspace, and across multiple endpoints. See the API rate limits for more information.