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. So erhalten Nutzer:innen dynamische Realtime-Updates—ohne ihr Gerät zu entsperren.

Funktionsweise

Live Activities kombinieren statische Informationen mit dynamischen Informationen, die Sie aktualisieren. Sie können zum Beispiel eine Live Activity erstellen, die den Status einer Lieferung anzeigt. Diese Live Activity enthält den Namen Ihres Unternehmens als statische Information sowie eine dynamische „Zeit bis zur Lieferung“, die sich aktualisiert, während sich die Lieferant:in dem Ziel nähert.

Als Entwickler:in können Sie mit Braze die Lebenszyklen Ihrer Live Activities verwalten, die Braze REST API aufrufen, um Live Activities zu aktualisieren, und dafür sorgen, dass alle abonnierten Geräte das Update so schnell wie möglich erhalten. Und da Sie Live Activities über Braze verwalten, können Sie sie zusammen mit Ihren anderen Messaging-Kanälen—Push-Benachrichtigungen, In-App-Nachrichten, Content Cards—einsetzen, 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

Implementieren einer Live Activity

Voraussetzungen

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

• Stellen Sie sicher, dass Ihr Projekt auf iOS 16.1 oder höher ausgerichtet ist.
• Fügen Sie in Ihrem Xcode-Projekt unter Signing & Capabilities die Berechtigung Push Notification hinzu.
• Stellen Sie sicher, dass zum Senden von Benachrichtigungen .p8-Schlüssel 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. Für dieses Feature ist iOS 17.2 oder höher erforderlich.

Hinweis

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

Schritt 1: Eine Activity erstellen

Stellen Sie zunächst sicher, dass Sie die Anleitung Displaying live data with Live Activities in der Apple-Dokumentation befolgt haben, um Live Activities in Ihrer iOS-Anwendung einzurichten. Achten Sie dabei darauf, NSSupportsLiveActivities in Ihrer Info.plist auf YES zu setzen.

Da die genaue Ausgestaltung Ihrer Live Activity von Ihrem Business Case abhängt, richten Sie die Activity-Objekte ein und initialisieren Sie sie. Definieren Sie insbesondere:

• ActivityAttributes: Dieses Protokoll definiert die statischen (unveränderlichen) und dynamischen (veränderlichen) Inhalte, die in Ihrer Live Activity erscheinen.
• ActivityAttributes.ContentState: Dieser Typ definiert die dynamischen Daten, die im Verlauf der Activity aktualisiert werden.

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

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

Hinweis

Wenn Sie häufig Pushes an dieselbe Live Activity senden möchten, können Sie eine Drosselung durch das Budgetlimit von Apple vermeiden, indem Sie NSSupportsLiveActivitiesFrequentUpdates in Ihrer Datei Info.plist auf YES setzen. Weitere Informationen finden Sie im Abschnitt Determine the update frequency der ActivityKit-Dokumentation.

Beispiel

Angenommen, wir möchten eine Live Activity erstellen, um unseren Nutzer:innen Updates zur Superb Owl Show zu liefern, bei der zwei konkurrierende Wildtierrettungsstationen Punkte für die bei ihnen lebenden Eulen erhalten. Für dieses Beispiel haben wir ein Struct namens SportsActivityAttributes erstellt, Sie können jedoch auch 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 Activity starten

Wählen Sie zunächst aus, wie Sie Ihre Activity 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. Starten Sie anschließend eine Activity ü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 verwaltet.

• 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 aus. Vergewissern Sie sich unter Frameworks and Libraries, dass BrazeKit aufgeführt ist.

Schritt 2.2: Das Protokoll BrazeLiveActivityAttributes hinzufügen

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

Wichtig

iOS ordnet die Eigenschaft brazeActivityId dem entsprechenden Feld in Ihrem Push-to-Start-Payload für die Live Activity zu. Sie sollte daher weder umbenannt noch 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, die diesem Typ zugeordnet sind, tracken kann.

Warnung

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

Beispiel

Im folgenden Beispiel verwaltet die Klasse LiveActivityManager die Live-Activity-Objekte. Anschließend registriert die Methode registerPushToStart den Typ 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"
    )
  }

}

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

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

Sie können das ActivityKit-Framework von Apple verwenden, um ein Push-Token abzurufen, das das Braze SDK für Sie verwalten kann. So können Sie Live Activities über die Braze API aktualisieren, da Braze das Push-Token im Backend an den Apple Push Notification Service (APNs) sendet.

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

Nachdem Sie die Live Activity registriert haben, extrahiert das Braze SDK die Push-Token und überwacht deren Änderungen.

Beispiel

Erstellen Sie für unser Beispiel eine Klasse namens LiveActivityManager als Schnittstelle für unsere Live-Activity-Objekte. Setzen Sie dann 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: Activity-Tracking fortsetzen

So stellen Sie sicher, dass Braze Ihre Live Activity beim App-Start trackt:

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

Dadurch kann Braze die Aufgaben zum Tracking von Push-Token-Updates für alle aktiven Live Activities fortsetzen. Beachten Sie: Wenn Nutzer:innen die Live Activity auf ihrem Gerät explizit geschlossen haben, gilt sie als entfernt und wird von Braze nicht mehr getrackt.

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 Activity aktualisieren

Mit dem Endpunkt /messages/live_activity/update können Sie eine Live Activity über Push-Benachrichtigungen aktualisieren, die über die Braze REST API gesendet werden. Verwenden Sie diesen Endpunkt, um den ContentState Ihrer Live Activity zu aktualisieren.

Wichtig

Wenn Sie /messages/live_activity/start aufrufen und anschließend die erste Anfrage an /messages/live_activity/update für dieselbe activity_id senden, warten Sie zwischen den Anfragen mindestens 5 Minuten. Diese Verzögerung gibt Braze und APNs Zeit, die neue Live Activity und ihre Token-Zuordnung zu registrieren. Wenn Sie das erste Update zu früh senden, wird es möglicherweise nicht auf die Activity angewendet.

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.

Ausführliche Informationen finden Sie in unserem Artikel zum Endpunkt /messages/live_activity/update.

Schritt 5: Die Activity beenden

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

Um das Beenden einer Live Activity zuverlässiger zu machen, können Sie die folgenden optionalen Schritte ausführen:

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

Automatisches Schließen einrichten

Um das automatische Schließen einzurichten, planen Sie nach dem Start der Live Activity eine Folgeanfrage an den Update-Endpunkt.

1. Senden Sie eine Anfrage an /messages/live_activity/start mit einer activity_id, die Sie nachverfolgen können.
2. Speichern Sie diese activity_id und Ihre gewünschte Endzeit in Ihrem Backend-Scheduler.
3. Senden Sie zur gewünschten Endzeit eine Anfrage an /messages/live_activity/update, wobei end_activity auf true gesetzt ist.
4. Konfigurieren Sie das Schließdatum in derselben Update-Anfrage. Weitere Informationen finden Sie unter dem Endpunkt /messages/live_activity/update.

Beachten Sie, dass der Zeitpunkt des Schließens von iOS gesteuert wird. Auch nachdem Sie eine gültige Beenden-Anfrage gesendet haben, kann sich das Entfernen vom Sperrbildschirm oder aus der Dynamic Island je nach Bedingungen auf Betriebssystemebene verzögern oder anders verhalten.

Eine Live Activity kann auch außerhalb von Braze beendet werden:

• Schließen 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 aus der Dynamic Island der Nutzer:innen. Nach einer Standardzeit von 12 Stunden entfernt iOS die Live Activity vom Sperrbildschirm der Nutzer:innen.

Ausführliche Informationen finden Sie in unserem Artikel zum Endpunkt /messages/live_activity/update.

Live Activities tracken

Live-Activity-Events sind in Currents, Snowflake Data Sharing und dem Query Builder verfügbar. Mit den folgenden Events können Sie den Lebenszyklus Ihrer Live Activities verstehen und überwachen, die Verfügbarkeit von Token tracken sowie Probleme unabhängig diagnostizieren oder Zustellungsstatus überprüfen.

• Live Activity Push To Start Token Change: Erfasst, wenn ein Push-to-Start-Token (PTS) in Braze hinzugefügt oder aktualisiert wird. So können Sie Token-Registrierungen und die Verfügbarkeit pro Nutzer:in tracken.
• Live Activity Update Token Change: Trackt das Hinzufügen, Aktualisieren oder Entfernen von Live-Activity-Update-Token (LAU).
• 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-Sendungen überprüfen

Wenn Sie überprüfen möchten, ob ein Workspace iOS Live Activities sendet, stehen Ihnen die folgenden Methoden zur Verfügung:

Nachrichten-Aktivitätsprotokoll

Gehen Sie zu Einstellungen > Nachrichten-Aktivitätsprotokoll und filtern Sie nach Live-Activity-Fehlern, um alle Zustellungsergebnisse im Zusammenhang mit Live Activities innerhalb des erwarteten Zeitraums zu sehen. Weitere Informationen finden Sie unter Nachrichten-Aktivitätsprotokoll.

Query Builder, Currents oder Snowflake Data Sharing

Suchen Sie nach den folgenden Live-Activity-Events, um den Lebenszyklus und die Zustellung von Live Activities zu überprüfen:

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

Optional können Sie auch nach Signalen zur Token-Verfügbarkeit suchen:

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

Dashboard zur API-Nutzung

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 in diesem Workspace Benachrichtigungen für iOS Live Activities verwendet werden. Weitere Informationen finden Sie unter Dashboard zur API-Nutzung.

Ereignisse von Live-Aktivitäten beobachten (optional)

Wichtig

Abonnieren Sie diese ActivityKit-Streams nicht direkt über Apple. Andernfalls geraten sie mit den Abos von Braze in Konflikt und Live-Aktivitäten funktionieren nicht korrekt:

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, mit denen Sie den gesamten Lebenszyklus von Live-Aktivitäten beobachten können. Eine vollständige Schritt-für-Schritt-Anleitung finden Sie im Tutorial zu Live-Aktivitäten.

• 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 über eine starke Referenz gehalten wird (speichern Sie ihn zum Beispiel in einer Eigenschaft mit demselben Lebenszyklus wie Ihre Braze-Instanz).

Abos einrichten

Richten Sie die Abos einmalig in application(_:didFinishLaunchingWithOptions:) ein und behalten Sie sie während der gesamten 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 Ereignisse von Live-Aktivitäten ausgelöst – sie geben nicht den aktuellen Zustand zum Zeitpunkt des Abos wieder. Um einen Schnappschuss des aktuellen Zustands abzufragen, verwenden Sie Activity<T>.activities.

subscribeToStateUpdates

subscribeToStateUpdates(_:) liefert UpdateEvent-Werte, die den gesamten Lebenszyklus von Live-Aktivitäten abdecken. Die 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 angepasste Logik, um die laufende Activity<T> anhand ihrer ID in Activity.activities nachzuschlagen. Greifen Sie dann über activity.content.state auf den typisierten ContentState zu.

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 String type, 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",
        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",
        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.