Live-Aktivität starten

Verwenden Sie diesen Endpunkt, um Live-Aktivitäten, die in Ihrer iOS-App angezeigt werden, aus der Ferne zu starten. Dieser Endpunkt erfordert eine zusätzliche Einrichtung.

Nachdem Sie eine Live-Aktivität erstellt haben, senden Sie eine POST-Anfrage, um ein Segment, eine verbundene Zielgruppe oder bestimmte Nutzer:innen anzusprechen. Identifizieren Sie bestimmte Nutzer:innen anhand der externen Nutzer-ID, des Nutzer-Alias oder beidem. Weitere Informationen über die Live-Aktivitäten von Apple finden Sie unter Starten und Aktualisieren von Live-Aktivitäten mit Push-Benachrichtigungen von ActivityKit.

Wenn content-available nicht festgelegt ist, beträgt die Standardpriorität des Apple-Push-Benachrichtigungs-Dienstes (APNs) 10. Wenn content-available gesetzt ist, beträgt diese Priorität 5. Weitere Informationen finden Sie unter Apple-Push-Objekt.

Tipp

Um eine Live-Aktivität zu beenden, verwenden Sie den Endpunkt /messages/live_activity/update mit end_activity auf true gesetzt.

Automatisches Entfernen einrichten

Um das automatische Entfernen nach dem Start einer Live-Aktivität einzurichten, planen Sie eine Folgeanfrage an den Update-Endpunkt über Ihr Backend.

1. Senden Sie eine /messages/live_activity/start-Anfrage mit einer activity_id, die Sie später wiederverwenden können.
2. Speichern Sie diese activity_id und Ihren gewünschten Endzeitpunkt 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 Entfernungsverhalten in derselben Update-Anfrage. Weitere Details finden Sie beim Endpunkt /messages/live_activity/update.
5. Überprüfen Sie Sende- und Ergebnis-Ereignisse im Nachrichten-Aktivitätsprotokoll.

Voraussetzungen

Um diesen Endpunkt zu verwenden, müssen Sie Folgendes tun:

• Generieren Sie einen API-Schlüssel mit der Berechtigung messages.live_activity.start.
• Erstellen Sie eine Live-Aktivität mit dem Braze Swift SDK.

Wichtig

Wenn die endgültige gerenderte Nutzlast größer ist als die maximal zulässige Größe des entsprechenden Dienstes, wird die Übertragung nicht erfolgreich sein.

Wichtig

Wenn Sie bestimmte Nutzer:innen ansprechen, startet Braze eine Live-Aktivität nur für external_user_ids und user_aliases, die zu bestehenden Nutzer:innen aufgelöst werden.

Rate-Limit

Wir wenden auf diesen Endpunkt das standardmäßige Braze-Rate-Limit von 250.000 Anfragen pro Stunde an, wie in API-Rate-Limits dokumentiert.

Anfragetext

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "app_id": "(required, string) App API identifier retrieved from the Developer Console.",
  "activity_id": "(required, string) Define a custom string as your `activity_id`. Use this ID to send update or end events to your Live Activity.",
  "activity_attributes_type": "(required, string) The activity attributes type you define within `liveActivities.registerPushToStart` in your app.",
  "activity_attributes": "(required, object) The static attribute values for the activity type (such as the sports team names, which don't change)",
  "content_state": "(required, object) You define the ContentState parameters when you create your Live Activity. Pass the updated values for your ContentState using this object. The format of this request must match the shape you initially defined.",
  "stale_date": "(optional, datetime in ISO-8601 format) The time the Live Activity content is marked as outdated in the user’s UI.",
  "notification": "(required, object) Include an `apple_push` object to define a push notification that creates an alert for the user, displayed on paired watchOS devices. Include `notification.alert.title` and `notification.alert.body`.",
  // Include one targeting method:
  // 1. "external_user_ids", "user_aliases", or both (combined maximum 50)
  // 2. "custom_audience"
  // 3. "segment_id"
  "external_user_ids": "(optional, array of strings) see external user identifier",
  "user_aliases": "(optional, array of user alias objects) see user alias object",
  "custom_audience": "(optional, connected audience object) see connected audience",
  "segment_id": "(optional, string) see segment identifier"
}

Anfrageparameter

Sie können external_user_ids und user_aliases in derselben Anfrage verwenden. Die kombinierte Array-Länge darf 50 nicht überschreiten. Braze spricht Nutzer:innen an, die einem der beiden Parameter entsprechen, und sendet nur einmal, wenn mehrere Bezeichner zur selben Person aufgelöst werden.

Kombinieren Sie external_user_ids oder user_aliases nicht mit segment_id oder custom_audience. Verwenden Sie bei diesem Endpunkt custom_audience, um verbundene Zielgruppenfilter zu übergeben.

Beispielanfrage

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
curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_activity/start' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_REST_API_KEY}' \
--data-raw '{
  "app_id": "{YOUR_APP_API_IDENTIFIER}",
  "activity_id": "football-chiefs-bills-2024-01-21",
  "content_state": {
    "teamOneScore": 0,
    "teamTwoScore": 0
  },
  "activity_attributes_type": "FootballActivity",
  "activity_attributes": {
    "team1Name": "Chiefs",
    "team2Name": "Bills"
  },
  "stale_date": "2024-01-22T16:55:49+0000",
  "notification": {
    "alert": {
      "body": "The game is starting! Tune in soon!",
      "title": "Chiefs v. Bills"
    }
  },
  "external_user_ids": ["user-id1", "user-id2"],
  "user_aliases": [
    {
      "alias_name": "user-name",
      "alias_label": "user-label"
    }
  ]
}'

Antwort

Für diesen Endpunkt gibt es zwei Statuscode-Antworten: 201 und 4XX.

Beispiel für eine erfolgreiche Antwort

Ein Statuscode 201 wird zurückgegeben, wenn die Anfrage korrekt formatiert ist und Braze sie erhalten hat. Der Statuscode 201 kann den folgenden Antworttext zurückgeben.

1
2
3
{
  "message": "success"
}

Beispiel für eine Fehlerantwort

Die Statuscode-Klasse 4XX weist auf einen Client-Fehler hin. Weitere Informationen zu möglichen Fehlern finden Sie im Artikel API-Fehler und -Antworten.

Der Statuscode 400 könnte den folgenden Antworttext zurückgeben.

1
2
3
{
    "error": "\nProblem:\n  message body does not match declared format\nResolution:\n  when specifying application/json as content-type, you must pass valid application/json in the request's 'body' "
}