Live-Aktivitäten für Swift

Erfahren Sie, wie Sie Live-Aktivitäten für das Swift Braze SDK implementieren. Live-Aktivitäten sind persistente, interaktive Benachrichtigungen, die direkt auf dem Sperrbildschirm angezeigt werden und es Nutzer:innen ermöglichen, dynamische Realtime-Updates zu erhalten—ohne ihr Gerät zu entsperren.

So funktioniert es

Live Activities zeigen eine Kombination aus statischen und dynamischen Informationen an, die Sie aktualisieren können. Sie können beispielsweise eine Live Activity erstellen, die einen Status-Tracker für eine Lieferung bereitstellt. Diese Live Activity enthält den Namen Ihres Unternehmens als statische Information sowie eine dynamische „Lieferzeit“, die aktualisiert wird, wenn sich der Zusteller dem Ziel nähert.

Als Entwickler:in können Sie Braze verwenden, um die Lebenszyklen Ihrer Live Activities zu verwalten, Aufrufe an die Braze REST API zu senden, um Live-Activity-Updates durchzuführen, und alle abonnierten Geräte so schnell wie möglich das Update erhalten zu lassen. Und da Sie Live Activities über Braze verwalten, können Sie sie zusammen mit Ihren anderen Messaging-Kanälen nutzen – Push-Benachrichtigungen, In-App Messages, Content Cards –, um die Akzeptanz zu steigern.

Sequenzdiagramm

• live activities sequence diagram

---
config:
  theme: mc
---
sequenceDiagram
  participant Server as Client Server
  participant Device as User Device
  participant App as iOS App / Braze SDK
  participant BrazeAPI as Braze API
  participant APNS as Apple Push Notification Service
  Note over Server, APNS: Launch Option 1<br/>Locally Start Activities
  App ->> App: Register a Live Activity using <br>`launchActivity(pushTokenTag:activity:)`
  App ->> App: Get push token from iOS
  App ->> BrazeAPI: Activity ID & Push token<br>automatically sent to Braze
  Note over Server, APNS: Launch Option 2<br/>Remotely Start Activities
  Device ->> App: Call `registerPushToStart`<br>to collect push tokens early
  App ->> BrazeAPI: Push-to-start tokens sent to Braze
  Server ->> BrazeAPI: POST /messages/live_activity/start
  Note right of BrazeAPI: Payload includes:<br>- push_token<br>- activity_id<br>- external_id<br>- event_name<br>- content_state (optional)
  BrazeAPI ->> APNS: Live activity start request
  APNS ->> Device: APNS sends activity to device
  App ->> App: Get push token from iOS
  App ->> BrazeAPI: Activity ID & Push token<br>automatically sent to Braze
  Note over Server, APNS: Resuming activities upon app launch
  App ->> App: Call `resumeActivities(ofType:)` on each app launch
  Note over Server, APNS: Updating a Live Activity
  loop update a live activity
  Server ->> BrazeAPI: POST /messages/live_activity/update
  Note right of BrazeAPI: Payload includes changes<br>to ContentState (dynamic variables)
  BrazeAPI ->> APNS: Update sent to APNS
  APNS ->> Device: APNS sends update to device
  end
  Note over Server, APNS: Ending a Live Activity
  Server ->> BrazeAPI: POST /messages/live_activity/update
  Note right of BrazeAPI: Activity can be ended via:<br> - User manually dismisses<br>- Times out after 12 hours<br>- Setting `end_activity: true` on `/messages/live_activity/update`
  APNS ->> Device: Live activity is dismissed

Implementierung einer Live Activity

Voraussetzungen

Bevor Sie dieses Feature nutzen können, müssen Sie das Swift Braze SDK integrieren. Außerdem müssen Sie Folgendes abschließen:

• Stellen Sie sicher, dass Ihr Projekt auf iOS 16.1 oder höher abzielt.
• Fügen Sie die Push Notification-Berechtigung unter Signing & Capabilities in Ihrem Xcode-Projekt hinzu.
• Stellen Sie sicher, dass .p8-Schlüssel zum Senden von Benachrichtigungen verwendet werden. Ältere Dateien wie .p12 oder .pem werden nicht unterstützt.
• Ab Version 8.2.0 des Braze Swift SDK können Sie eine Live Activity remote registrieren. Um dieses Feature zu nutzen, ist iOS 17.2 oder höher erforderlich.

Hinweis

Obwohl Live Activities und Push-Benachrichtigungen ähnlich sind, sind ihre Systemberechtigungen getrennt. Standardmäßig sind alle Live-Activity-Features aktiviert, aber Nutzer:innen können dieses Feature pro App deaktivieren.

Schritt 1: Eine Aktivität erstellen

Stellen Sie zunächst sicher, dass Sie Displaying live data with Live Activities in der Apple-Dokumentation befolgt haben, um Live Activities in Ihrer iOS-Anwendung einzurichten. Stellen Sie im Rahmen dieser Aufgabe sicher, dass Sie NSSupportsLiveActivities auf YES in Ihrer Info.plist setzen.

Da die genaue Art Ihrer Live Activity spezifisch für Ihren Geschäftsfall ist, richten Sie die Activity-Objekte ein und initialisieren Sie sie. Definieren Sie dabei insbesondere:

• ActivityAttributes: Dieses Protokoll definiert den statischen (unveränderlichen) und dynamischen (veränderlichen) Inhalt, der in Ihrer Live Activity angezeigt wird.
• ActivityAttributes.ContentState: Dieser Typ definiert die dynamischen Daten, die sich im Verlauf der Aktivität aktualisieren.

Sie verwenden außerdem SwiftUI, um die UI-Darstellung des Sperrbildschirms und der Dynamic Island auf unterstützten Geräten zu erstellen.

Machen Sie sich mit Apples Voraussetzungen und Einschränkungen für Live Activities vertraut, da diese Einschränkungen unabhängig von Braze sind.

Hinweis

Wenn Sie erwarten, häufige Pushes an dieselbe Live Activity zu senden, können Sie eine Drosselung durch Apples Budgetlimit vermeiden, indem Sie NSSupportsLiveActivitiesFrequentUpdates auf YES in Ihrer Info.plist-Datei setzen. Weitere Details finden Sie im Abschnitt Determine the update frequency in der ActivityKit-Dokumentation.

Beispiel

Stellen wir uns vor, wir möchten eine Live Activity erstellen, die unseren Nutzer:innen Updates zur Superb-Owl-Show liefert, bei der zwei konkurrierende Wildtierrettungsstationen Punkte für die Eulen erhalten, die sie beherbergen. Für dieses Beispiel haben wir ein Struct namens SportsActivityAttributes erstellt, aber Sie können Ihre eigene Implementierung von ActivityAttributes verwenden.

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
}

Schritt 2: Die Aktivität starten

Wählen Sie zunächst, wie Sie Ihre Aktivität registrieren möchten:

• Remote: Verwenden Sie die Methode registerPushToStart früh im Lebenszyklus Ihrer Nutzer:innen und bevor das Push-to-Start-Token benötigt wird, und starten Sie dann eine Aktivität über den Endpunkt /messages/live_activity/start.
• Lokal: Erstellen Sie eine Instanz Ihrer Live Activity und verwenden Sie dann die Methode launchActivity, um Push-Token zu erstellen, die Braze verwalten kann.

• remote
• local

Wichtig

Um eine Live Activity remote zu registrieren, ist iOS 17.2 oder höher erforderlich.

Schritt 2.1: BrazeKit zu Ihrer Widget-Erweiterung hinzufügen

Wählen Sie in Ihrem Xcode-Projekt Ihren App-Namen und dann General. Bestätigen Sie unter Frameworks and Libraries, dass BrazeKit aufgeführt ist.

Schritt 2.2: Das BrazeLiveActivityAttributes-Protokoll hinzufügen

Fügen Sie in Ihrer ActivityAttributes-Implementierung die Konformität zum BrazeLiveActivityAttributes-Protokoll hinzu und ergänzen Sie die Eigenschaft brazeActivityId in Ihrem Attributmodell.

Wichtig

iOS ordnet die Eigenschaft brazeActivityId dem entsprechenden Feld in Ihrem Live-Activity-Push-to-Start-Payload zu, daher sollte sie nicht umbenannt oder mit einem anderen Wert belegt werden.

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

#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
// 1. Add the `BrazeLiveActivityAttributes` conformance to your `ActivityAttributes` struct.
struct SportsActivityAttributes: ActivityAttributes, BrazeLiveActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String

  // 2. Add the `String?` property to represent the activity ID.
  var brazeActivityId: String?
}

Schritt 2.3: Für Push-to-Start registrieren

Registrieren Sie als Nächstes den Live-Activity-Typ, damit Braze alle Push-to-Start-Token und Live-Activity-Instanzen verfolgen kann, die mit diesem Typ verknüpft sind.

Warnung

Das iOS-Betriebssystem generiert Push-to-Start-Token nur bei der ersten App-Installation nach einem Geräteneustart. Um sicherzustellen, dass Ihre Token zuverlässig registriert werden, rufen Sie registerPushToStart in Ihrer didFinishLaunchingWithOptions-Methode auf.

Beispiel

Im folgenden Beispiel verwaltet die Klasse LiveActivityManager Live-Activity-Objekte. Dann registriert die Methode registerPushToStart SportsActivityAttributes:

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.name
    )
  }

}

Schritt 2.4: Eine Push-to-Start-Benachrichtigung senden

Senden Sie eine remote Push-to-Start-Benachrichtigung über den Endpunkt /messages/live_activity/start.

Sie können Apples ActivityKit-Framework verwenden, um ein Push-Token zu erhalten, das das Braze SDK für Sie verwalten kann. Dies ermöglicht es Ihnen, Live Activities über die Braze-API zu aktualisieren, da Braze das Push-Token an den Apple Push Notification Service (APNs) im Backend sendet.

1. Erstellen Sie eine Instanz Ihrer Live-Activity-Implementierung mithilfe der ActivityKit-APIs von Apple.
2. Setzen Sie den Parameter pushType auf .token.
3. Übergeben Sie die von Ihnen definierten ActivitiesAttributes und ContentState der Live Activities.
4. Registrieren Sie Ihre Aktivität bei Ihrer Braze-Instanz, indem Sie sie an launchActivity(pushTokenTag:activity:) übergeben. Der Parameter pushTokenTag ist ein benutzerdefinierter String, den Sie festlegen. Er sollte für jede von Ihnen erstellte Live Activity eindeutig sein.

Nachdem Sie die Live Activity registriert haben, extrahiert das Braze SDK die Push-Token und beobachtet Änderungen daran.

Beispiel

Erstellen Sie für unser Beispiel eine Klasse namens LiveActivityManager als Schnittstelle für unsere Live-Activity-Objekte. Setzen Sie dann den pushTokenTag auf "sports-game-2024-03-15".

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

}

Ihr Live-Activity-Widget zeigt Ihren Nutzer:innen diesen anfänglichen Inhalt an.

Schritt 3: Aktivitäts-Tracking fortsetzen

Um sicherzustellen, dass Braze Ihre Live Activity beim App-Start verfolgt:

1. Öffnen Sie Ihre AppDelegate-Datei.
2. Importieren Sie das ActivityKit-Modul, falls es verfügbar ist.
3. Rufen Sie resumeActivities(ofType:) in application(_:didFinishLaunchingWithOptions:) für alle ActivityAttributes-Typen auf, die Sie in Ihrer Anwendung registriert haben.

Dies ermöglicht es Braze, Aufgaben zur Verfolgung von Push-Token-Aktualisierungen für alle aktiven Live Activities fortzusetzen. Beachten Sie, dass Braze eine Live Activity nicht mehr verfolgt, wenn Nutzer:innen sie auf ihrem Gerät explizit geschlossen haben, da sie als entfernt gilt.

Beispiel

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

Schritt 4: Die Aktivität aktualisieren

Der Endpunkt /messages/live_activity/update ermöglicht es Ihnen, eine Live Activity über Push-Benachrichtigungen zu aktualisieren, die über die Braze REST API gesendet werden. Verwenden Sie diesen Endpunkt, um den ContentState Ihrer Live Activity zu aktualisieren.

Wenn Sie Ihren ContentState aktualisieren, zeigt Ihr Live-Activity-Widget die neuen Informationen an. So sieht die Superb-Owl-Show am Ende der ersten Halbzeit aus.

Alle Details finden Sie in unserem Artikel zum Endpunkt /messages/live_activity/update.

Schritt 5: Die Aktivität beenden

Wenn eine Live Activity aktiv ist, wird sie sowohl auf dem Sperrbildschirm als auch auf der Dynamic Island der Nutzer:innen angezeigt. Um sie über Braze zu beenden, verwenden Sie den Endpunkt /messages/live_activity/update mit end_activity auf true gesetzt.

Um die Zuverlässigkeit beim Beenden einer Live Activity zu verbessern, führen Sie die folgenden optionalen Schritte aus:

1. Fügen Sie optional dismissal_date in derselben update-Anfrage hinzu, um vorzuschlagen, wann iOS die Live-Activity-UI entfernen soll.
2. Überprüfen Sie die Zustellungsergebnisse im Nachrichtenaktivitätsprotokoll.

Automatische Entfernung einrichten

Um eine automatische Entfernung einzurichten, planen Sie eine Folgeanfrage an den Update-Endpunkt, nachdem Sie die Live Activity gestartet haben.

1. Senden Sie eine /messages/live_activity/start-Anfrage mit einer activity_id, die Sie verfolgen können.
2. Speichern Sie diese activity_id und Ihre gewünschte Endzeit in Ihrem Backend-Scheduler.
3. Senden Sie zum gewünschten Endzeitpunkt eine /messages/live_activity/update-Anfrage mit end_activity auf true gesetzt.
4. Konfigurieren Sie das Entfernungsdatum in derselben Update-Anfrage. Details finden Sie beim Endpunkt /messages/live_activity/update.

Beachten Sie, dass der Zeitpunkt der Entfernung von iOS gesteuert wird. Auch nachdem Sie eine gültige Beendigungsanfrage gesendet haben, kann die Entfernung vom Sperrbildschirm oder der Dynamic Island verzögert werden oder sich je nach Bedingungen auf Betriebssystemebene unterschiedlich verhalten.

Eine Live Activity kann auch außerhalb von Braze enden:

• Entfernung durch Nutzer:innen: Nutzer:innen können eine Live Activity manuell schließen.
• Zeitüberschreitung: Nach einer Standardzeit von acht Stunden entfernt iOS die Live Activity von der Dynamic Island der Nutzer:innen. Nach einer Standardzeit von 12 Stunden entfernt iOS die Live Activity vom Sperrbildschirm der Nutzer:innen.

Alle Details finden Sie in unserem Artikel zum Endpunkt /messages/live_activity/update.

Tracking von Live Activities

Live-Activity-Ereignisse sind in Currents, Snowflake Data Sharing und im Query Builder verfügbar. Die folgenden Ereignisse können Ihnen helfen, den Lebenszyklus Ihrer Live Activities zu verstehen und zu überwachen, die Token-Verfügbarkeit zu verfolgen und unabhängig Probleme zu diagnostizieren oder Zustellungsstatus zu überprüfen.

• Live Activity Push To Start Token Change: Erfasst, wann ein Push-to-Start-Token (PTS) in Braze hinzugefügt oder aktualisiert wird, sodass Sie Token-Registrierungen und -Verfügbarkeit pro Nutzer:in verfolgen können.
• Live Activity Update Token Change: Verfolgt das Hinzufügen, Aktualisieren oder Entfernen von Live Activity Update (LAU) Tokens.
• Live Activity Send: Protokolliert jedes Mal, wenn eine Live Activity von Braze gestartet, aktualisiert oder beendet wird.
• Live Activity Outcome: Gibt den endgültigen Zustellungsstatus an den Apple Push Notification Service (APNs) für jede von Braze gesendete Live Activity an.

Live-Activity-Versand überprüfen

Wenn Sie bestätigen müssen, ob ein Workspace iOS Live Activities sendet, können Sie die folgenden Methoden verwenden:

Nachrichtenaktivitätsprotokoll

Gehen Sie zu Einstellungen > Nachrichtenaktivitätsprotokoll und filtern Sie nach Live-Activity-Fehlern, um alle zustellungsbezogenen Ergebnisse für Live Activities in Ihrem erwarteten Zeitraum zu sehen. Weitere Informationen finden Sie unter Nachrichtenaktivitätsprotokoll.

Query Builder, Currents oder Snowflake Data Sharing

Prüfen Sie die folgenden Live-Activity-Ereignisse, um den Lebenszyklus und die Zustellung von Live Activities zu überprüfen:

• Live Activity Send: Wird jedes Mal protokolliert, wenn eine Live Activity von Braze gestartet, aktualisiert oder beendet wird.
• Live Activity Outcome: Endgültiger Zustellungsstatus an APNs für jede gesendete Live Activity.

Optional können Sie auch die Verfügbarkeit von Token-Signalen prüfen:

• Live Activity Push To Start Token Change
• Live Activity Update Token Change

API-Nutzungs-Dashboard

Gehen Sie zu Einstellungen > APIs und Bezeichner > Dashboard, wählen Sie Filter aus und filtern Sie nach Endpunkt, um API-Antworten zu sehen. Wählen Sie beispielsweise /messages/live_activity/update (oder /messages/live_activity/start) aus und sehen Sie sich das Anfragevolumen der letzten 30 Tage an. API-Antworten zeigen an, dass die API aufgerufen wird und dass iOS-Live-Activity-Benachrichtigungen in diesem Workspace verwendet werden. Weitere Informationen finden Sie unter API-Nutzungs-Dashboard.

Ereignisse von Live-Aktivitäten beobachten (optional)

Wichtig

Abonnieren Sie diese ActivityKit-Streams nicht direkt über Apple, da dies mit den Abos von Braze in Konflikt gerät und die korrekte Funktion von Live-Aktivitäten verhindert:

1. pushTokenUpdates
2. activityStateUpdates
3. contentUpdates
4. pushToStartTokenUpdates
5. activityUpdates

Verwenden Sie stattdessen die in diesem Abschnitt beschriebenen Abos.

Das Braze SDK bietet zwei Abo-Methoden auf braze.liveActivities, um den gesamten Lebenszyklus von Live-Aktivitäten zu beobachten. Eine vollständige Schritt-für-Schritt-Anleitung finden Sie im Live Activities Tutorial.

• subscribeToStateUpdates(_:): Liefert Lebenszyklus-Ereignisse sowohl für die Push-to-Start-Token-Registrierung als auch für laufende Aktivitätsinstanzen.
• subscribeToErrors(_:): Liefert SDK- und serverseitige Fehler, die beim Tracking von Live-Aktivitäten auftreten.

Hinweis

Beide Methoden geben ein Braze.Cancellable zurück. Das Abo bleibt aktiv, solange der zurückgegebene Wert durch eine starke Referenz gehalten wird (speichern Sie ihn z. B. in einer Eigenschaft mit demselben Lebenszyklus wie Ihre Braze-Instanz).

Abos einrichten

Richten Sie Abos einmalig in application(_:didFinishLaunchingWithOptions:) ein und behalten Sie sie für die gesamte Lebensdauer Ihrer App bei:

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
class AppDelegate: UIResponder, UIApplicationDelegate {
  static var braze: Braze?

  var stateSubscription: Braze.Cancellable?
  var errorSubscription: Braze.Cancellable?

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    let braze = Braze(configuration: config)
    Self.braze = braze

    if #available(iOS 16.1, *) {
      stateSubscription = Self.braze?.liveActivities.subscribeToStateUpdates { event in
        self.handleStateUpdate(event)
      }
      errorSubscription = Self.braze?.liveActivities.subscribeToErrors { error in
        self.handleLiveActivityError(error)
      }
    }

    return true
  }
}

Hinweis

Callbacks werden nur für zukünftige Live-Aktivitäts-Ereignisse ausgelöst – sie geben nicht den aktuellen Zustand zum Zeitpunkt des Abos wieder. Um den aktuellen Zustandsschnappschuss abzufragen, verwenden Sie Activity<T>.activities.

subscribeToStateUpdates

subscribeToStateUpdates(_:) liefert UpdateEvent-Werte, die den gesamten Lebenszyklus von Live-Aktivitäten abdecken. Ereignisse sind in zwei Bereiche unterteilt:

• .activityType(ActivityType): Ereignisse auf Typebene für die Push-to-Start-Token-Registrierung (iOS 17.2+). Es existiert noch keine Aktivitätsinstanz.
• .activityInstance(ActivityInstance): Ereignisse auf Instanzebene für eine bestimmte laufende Aktivität.

Mehrere Abonnent:innen werden unterstützt – jedes aktive Abo erhält jede Emission unabhängig.

Ereignisse auf Typebene

Ereignisse auf Instanzebene

Beispiel

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
27
28
29
30
31
32
33
func handleStateUpdate(_ event: Braze.LiveActivities.UpdateEvent) {
  switch event {

  // Type-scoped: push-to-start token lifecycle (iOS 17.2+)
  case .activityType(.pushToStartTokenRead(let activityType)):
    print("[\(activityType)] Push-to-start token read by SDK")

  // ...

  // Instance-scoped: SDK tracking
  case .activityInstance(.started(let id, let type, let tag, let source)):
    print("[\(type)] Activity \(id) started via \(source), tag: \(tag)")

  // ...

  // Instance-scoped: ActivityKit lifecycle
  case .activityInstance(.active(let id, let type)):
    print("[\(type)] Activity \(id) is active")

  // ...

  case .activityInstance(.ended(let id, let type)):
    print("[\(type)] Activity \(id) ended")

  // Instance-scoped: content updates (iOS 16.2+)
  case .activityInstance(.contentUpdated(let id, let type)):
    // For more advanced use cases of `contentUpdated`, see the section below
    print("[\(type)] Content updated for activity \(id)")

  case .activityInstance(.pushTokenUpdated(let id, let type)):
    print("[\(type)] Activity \(id) push token rotated")
  }
}

subscribeToErrors

subscribeToErrors(_:) liefert ErrorEvent-Werte mit denselben zwei Bereichen wie UpdateEvent:

• .activityType(ActivityType): Fehler auf Typebene bei fehlgeschlagener Push-to-Start-Registrierung.
• .activityInstance(ActivityInstance): Fehler auf Instanzebene für eine laufende Aktivität.

Verwenden Sie das Flag isTransient, um zu bestimmen, ob ein erneuter Versuch sinnvoll ist. Das SDK wiederholt vorübergehende Fehler automatisch.

Fehler auf Typebene

Fehler auf Instanzebene

Beispiel

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
func handleLiveActivityError(_ error: Braze.LiveActivities.ErrorEvent) {
  switch error {

  // Type-scoped errors
  case .activityType(.pushToStartRegistrationFailed(let type, let isTransient, let reason)):
    if isTransient {
      print("[\(type)] Push-to-start registration failed (transient, will retry): \(reason)")
    } else {
      print("[\(type)] Push-to-start registration failed (permanent): \(reason)")
    }

  // Instance-scoped errors
  case .activityInstance(.registrationFailed(let id, let type, _, let isTransient, let reason)):
    if isTransient {
      print("[\(type)] Activity \(id) registration failed (transient, retrying): \(reason)")
    } else {
      print("[\(type)] Activity \(id) registration failed (permanent): \(reason)")
    }

  case .activityInstance(.activityNotFound(let id, let type)):
    print("[\(type)] Stored activity \(id) not found on resume")

  case .activityInstance(.invalidPushTokenTag(let id, let type, let tag)):
    print("[\(type)] Activity \(id) has invalid push token tag '\(tag)'")
  }
}

Aktualisierungen des Inhaltsstatus verarbeiten (optional)

Wenn Sie den tatsächlichen Inhaltsstatus der Live-Aktivitätsinstanz verwenden möchten, folgen Sie diesem Abschnitt.

Wenn ein .contentUpdated-Ereignis ausgelöst wird, verwenden Sie benutzerdefinierte Logik, um die laufende Activity<T> anhand ihrer ID aus Activity.activities nachzuschlagen und dann über activity.content.state auf den typisierten ContentState zuzugreifen.

Einzelner Attributtyp

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
27
28
case .activityInstance(.contentUpdated(let id, let type)):
  #if canImport(ActivityKit)
    // Add custom logic look up the Activity<T> by ID and access your app's typed ContentState.
    // In this example, `SportsActivityAttributes` is the app's custom type.
    if #available(iOS 16.2, *),
      let activity = findActivityInstance(id: id, as: SportsActivityAttributes.self)
    {
      // `activityContent` is now strongly typed as a `SportsActivityAttributes`
      let activityContent = activity.content.state
      print("[\(type)] Game \(id) — score: \(activityContent.teamOneScore)–\(activityContent.teamTwoScore)")
      return
    }
  #endif
  print("[\(type)] Content updated for activity \(id)")

// ...

// - MARK: Helper methods

@available(iOS 16.2, *)
func findActivityInstance<Attributes: ActivityAttributes>(
  id: String,
  as type: Attributes.Type
) -> Activity<Attributes>? {
  // Use Apple's API to find the matching Live Activity instance:
  // - https://developer.apple.com/documentation/activitykit/activity/activities
  Activity<Attributes>.activities.first(where: { $0.id == id })
}

Mehrere Attributtypen

Wenn Ihre App mehrere ActivityAttributes-Typen verwendet, prüfen Sie den type-String, um die passende Activity<T> nachzuschlagen:

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
27
28
29
30
31
32
33
34
case .activityInstance(.contentUpdated(let id, let type)):
  #if canImport(ActivityKit)
    if #available(iOS 16.2, *) {
      if type == SportsActivityAttributes.name,
        let activity = findActivityInstance(id: id, as: SportsActivityAttributes.self)
      {
        let activityContent = activity.content.state
        print("[\(type)] Game \(id) — score: \(activityContent.teamOneScore)–\(activityContent.teamTwoScore)")
        return

      } else if type == OrderActivityAttributes.name,
        let activity = findActivityInstance(id: id, as: OrderActivityAttributes.self)
      {
        let activityContent = activity.content.state
        print("[\(type)] Order \(id) — status: \(activityContent.status), ETA: \(activityContent.eta)")
        return
      }
    }
  #endif
  print("[\(type)] Content updated for activity \(id)")

// ...

// - MARK: Helper methods

@available(iOS 16.2, *)
func findActivityInstance<Attributes: ActivityAttributes>(
  id: String,
  as type: Attributes.Type
) -> Activity<Attributes>? {
  // Use Apple's API to find the matching Live Activity instance:
  // - https://developer.apple.com/documentation/activitykit/activity/activities
  Activity<Attributes>.activities.first(where: { $0.id == id })
}

Häufig gestellte Fragen (FAQ)

Funktionalität und Unterstützung

Welche Plattformen unterstützen Live-Aktivitäten?

Derzeit sind Live-Aktivitäten ein Feature, das speziell für iOS und iPadOS verfügbar ist. Standardmäßig werden Aktivitäten, die auf einem iPhone oder iPad gestartet werden, zusätzlich auf allen gekoppelten Geräten mit watchOS 11+ oder macOS 26+ angezeigt.

Braze bietet derzeit keine native Unterstützung für Live-Aktivitäten auf Android. Für Android können Sie Live-Update-Erlebnisse über Braze-Push-Benachrichtigungen und benutzerdefiniertes Benachrichtigungs-Rendering erstellen.

Der Artikel zu Live-Aktivitäten beschreibt die Voraussetzungen für die Verwaltung von Live-Aktivitäten über das Braze Swift SDK.

Unterstützen React Native-Apps Live-Aktivitäten?

Ja, React Native SDK 3.0.0+ unterstützt Live-Aktivitäten über das Braze Swift SDK. Das bedeutet, dass Sie React Native iOS-Code direkt auf Basis des Braze Swift SDK schreiben müssen.

Es gibt keine React Native-spezifische JavaScript-Convenience-API für Live-Aktivitäten, da die von Apple bereitgestellten Features für Live-Aktivitäten Sprachen verwenden, die nicht in JavaScript übersetzbar sind (z. B. Swift Concurrency, Generics, SwiftUI).

Unterstützt Braze Live-Aktivitäten als Campaign oder Canvas-Schritt?

Nein, dies wird derzeit nicht unterstützt.

Push-Benachrichtigungen und Live-Aktivitäten

Was passiert, wenn während einer aktiven Live-Aktivität eine Push-Benachrichtigung gesendet wird?

Live-Aktivitäten und Push-Benachrichtigungen belegen unterschiedliche Bereiche auf dem Bildschirm und stehen nicht miteinander in Konflikt.

Wenn Live-Aktivitäten die Push-Nachrichtenfunktion nutzen, müssen dann Push-Benachrichtigungen aktiviert sein, um Live-Aktivitäten zu empfangen?

Obwohl Live-Aktivitäten auf Push-Benachrichtigungen für Aktualisierungen angewiesen sind, werden sie durch unterschiedliche Nutzereinstellungen gesteuert. Nutzer:innen können sich für Live-Aktivitäten anmelden und für Push-Benachrichtigungen abmelden – und umgekehrt.

Live-Activity-Update-Token verfallen nach acht Stunden.

Sind für Live-Aktivitäten Push-Primer erforderlich?

Push-Primer sind eine bewährte Methode, um Ihre Nutzer:innen aufzufordern, Push-Benachrichtigungen von Ihrer App zu aktivieren. Es gibt jedoch keine Systemaufforderung, um sich für Live-Aktivitäten anzumelden. Standardmäßig sind Nutzer:innen für Live-Aktivitäten einer App angemeldet, wenn sie diese App unter iOS 16.1 oder höher installieren. Diese Berechtigung kann in den Geräteeinstellungen für jede App einzeln deaktiviert oder wieder aktiviert werden.

Technische Themen und Fehlerbehebung

Wie erkenne ich, ob Live-Aktivitäten Fehler aufweisen?

Fehler in Bezug auf Live-Aktivitäten werden im Braze-Dashboard im Nachrichten-Aktivitätsprotokoll protokolliert, wo Sie nach „LiveActivity Errors“ filtern können.

Warum habe ich nach dem Senden einer Push-to-Start-Benachrichtigung meine Live-Aktivität nicht erhalten?

Überprüfen Sie zunächst, ob Ihre Payload alle erforderlichen Felder enthält, die im Endpunkt messages/live_activity/start beschrieben sind. Die Felder activity_attributes und content_state sollten mit den im Code Ihres Projekts definierten Eigenschaften übereinstimmen. Wenn Sie sicher sind, dass die Payload korrekt ist, werden Sie möglicherweise durch APNs gedrosselt. Dieses Limit wird von Apple und nicht von Braze festgelegt.

Um zu überprüfen, ob Ihre Push-to-Start-Benachrichtigung erfolgreich auf dem Gerät angekommen ist, aber aufgrund von Rate-Limits nicht angezeigt wurde, können Sie Ihr Projekt mit der Konsolen-App auf Ihrem Mac debuggen. Hängen Sie den Aufzeichnungsprozess für Ihr gewünschtes Gerät an und filtern Sie dann die Protokolle nach process:liveactivitiesd in der Suchleiste.

Warum empfängt meine Live-Aktivität nach dem Start mit Push-to-Start keine neuen Updates?

Überprüfen Sie, ob Sie die Anweisungen in Schritt 2.2: BrazeLiveActivityAttributes-Protokoll hinzufügen korrekt umgesetzt haben. Ihre ActivityAttributes sollten sowohl die BrazeLiveActivityAttributes-Protokollkonformität als auch die Eigenschaft brazeActivityId enthalten.

Nachdem Sie eine Push-to-Start-Benachrichtigung für eine Live-Aktivität erhalten haben, überprüfen Sie, ob eine ausgehende Netzwerkanfrage an den Endpunkt /push_token_tag Ihrer Braze-URL zu sehen ist und ob diese die korrekte Aktivitäts-ID unter dem Feld "tag" enthält.

Stellen Sie abschließend sicher, dass der Attributtyp der Live-Aktivität in Ihrer Update-Payload genau mit dem String und der Klasse übereinstimmt, die in Ihrem SDK-Methodenaufruf von registerPushToStart verwendet werden. Verwenden Sie Konstanten, um Tippfehler zu vermeiden.

Ich erhalte die Antwort „Access Denied“, wenn ich versuche, den Endpunkt live_activity/update zu verwenden. Warum?

Die von Ihnen verwendeten API-Schlüssel müssen die richtigen Berechtigungen für den Zugriff auf die verschiedenen Braze-API-Endpunkte besitzen. Wenn Sie einen zuvor erstellten API-Schlüssel verwenden, haben Sie möglicherweise versäumt, dessen Berechtigungen zu aktualisieren. Weitere Informationen finden Sie in unserer Übersicht zur Sicherheit von API-Schlüsseln.

Teilt der Endpunkt messages/send die Rate-Limits mit dem Endpunkt messages/live_activity/update?

Standardmäßig liegt das Rate-Limit für den Endpunkt messages/live_activity/update bei 250.000 Anfragen pro Stunde und Workspace, verteilt über mehrere Endpunkte. Weitere Informationen finden Sie unter API-Rate-Limits.