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.

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

Implementing a Live Activity

To manage the lifecycle of a Live Activity, follow these four steps.

1. Create the Live Activity. Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for your static and dynamic states.
   
   

2. Register the Live Activity Register a Live Activity with the Braze SDK using the launchActivity method with the Live Activity object and unique activity tag.
   
   

3. Update the Live Activity Publish updates to the Live Activity using the Braze’s API /messages/live_activity/update endpoint.
   
   

4. End the Live Activity End a Live Activity for all recipients by publishing an update to /messages/live_activity/update with the parameter "end_activity": true.

Step 1: Developing your Live 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 BrazeActivityAttributes, 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 BrazeActivityAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String
}

Step 2: Registering a Live Activity

Next, you will use Braze methods to track and manage your Live Activities.

Updates to a Live Activity can be sent using ActivityKit (Apple’s framework for managing a Live Activity) or remote push notifications. In this instance, you will use ActivityKit to get a push token, which the Braze SDK can manage for you. This allows you to update Live Activities through the Braze API, as Braze will send the push token to the Apple Push Notification service (APNs) on the backend.

1. Create an instance of your Live Activity implementation using Apple’s ActivityKit APIs.
2. Set the pushType parameter as .token.
3. Pass in the Live Activities ActivitiesAttributes and ContentState you defined.
4. Register your activity with your Braze instance by passing it into launchActivity(pushTokenTag:activity:). The pushTokenTag parameter is a custom string you define. It should be unique for each Live Activity you create.

Once you have registered the Live Activity, the Braze SDK will extract and observe changes in the push tokens.

Example

For our example, we’ll create class called LiveActivityManager as an interface for our Live Activity objects. Then, we’ll set the pushTokenTag to "live-activity-1".

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

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {
  
  @available(iOS 16.2, *)
  func createActivity() {
    let activityAttributes = BrazeActivityAttributes(gameName: "Superb Owl", gameNumber: "Game 1")
    let contentState = BrazeActivityAttributes.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
      AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "live-activity-1",
                                                       activity: activity)
    }
  }
  
}

Your Live Activity widget would display this initial content to your users.

Resuming Live Activity tracking

You will need to ensure that Braze tracks your Live Activity upon app launch.

To do this:

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<BrazeActivityAttributes>.self
      )
    }

    return true
  }
}

Step 3: Updating a Live 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 4: Ending a Live 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.