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, können Sie eine POST-Anfrage senden, um Ihre Aktivität für ein Segment, eine verbundene Zielgruppe oder bestimmte externe Nutzer-IDs aus der Ferne zu starten. 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 Details 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.

Rate-Limits

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
{
  "app_id": "(required, string) App API identifier retrieved from the Developer Console.",
  "activity_id": "(required, string) Define a custom string as your `activity_id`. You will use this ID when you wish 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. Should include `notification.alert.title` and `notification.alert.body`",
  // One of the following:
  "external_user_ids": "(optional, array of strings) see external user identifier, maximum 50",
  "custom_audience": "(optional, connected audience object) see connected audience",
  "segment_id": "(optional, string) see segment identifier"
}

Anfrageparameter

Bei diesem Endpunkt übergeben Sie verbundene Zielgruppen-Filter in custom_audience.

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
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"
        }
    },
    // One of the following required:
    "segment_id": "{YOUR-SEGMENT-API-IDENTIFIER}", // Optional
    "custom_audience": {...}, // Optional
    "external_user_ids": ["user-id1", "user-id2"], // Optional
}'

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 war und wir sie erhalten haben. Der Statuscode 201 könnte 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' "
}