Démarrer une ligne/en production/instantanée
/messages/live_activity/start
Utilisez cet endpoint pour démarrer à distance les activités en direct affichées dans votre app iOS. Cet endpoint nécessite une configuration supplémentaire.
Après avoir créé une activité en direct, vous pouvez effectuer une requête POST pour démarrer à distance votre activité pour n’importe quel segment/instantané. Pour en savoir plus sur les activités en direct d’Apple, consultez Démarrage et mise à jour des activités en direct avec les notifications push d’ActivityKit.
Conditions préalables
Pour utiliser cet endpoint, vous devrez effectuer les opérations suivantes :
- Générez une clé API avec l’autorisation
messages.live_activity.start
. - Créez une activité en direct à l’aide du SDK Braze Swift.
Limite de débit
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
Corps de la demande
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"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.",
"dismissal_date": "(optional, datetime in ISO-8601 format) The time to remove the Live Activity from the user’s UI. If this time is in the past, the Live Activity will be removed immediately.",
"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",
"custom_audience": "(optional, connected audience object) see connected audience",
"segment_id": "(optional, string) see segment identifier"
}
Paramètres de demande
Paramètre | Requis | Type de données | Description |
---|---|---|---|
app_id |
Requis | Chaîne de caractères | Identifiant API récupéré depuis la page Clés API. |
activity_id |
Requis | Chaîne de caractères | Définissez une chaîne de caractères personnalisée comme votre activity_id . Vous utiliserez cet ID lorsque vous souhaiterez envoyer des événements de mise à jour ou de fin à votre ligne/en production/instantanée. |
activity_attributes_type |
Requis | Chaîne de caractères | Le type d’attributs d’activité que vous définissez à l’adresse liveActivities.registerPushToStart dans votre application. |
activity_attributes |
Requis | Objet | Les valeurs d’attributs statiques pour le type d’activité (comme les noms des équipes sportives, qui ne changent pas). |
content_state |
Requis | Objet | Vous définissez les paramètres ContentState lorsque vous créez votre activité en direct. Transmettez les valeurs mises à jour pour votre ContentState en utilisant cet objet.Le format de cette requête doit correspondre à la forme que vous avez initialement définie. |
dismissal_date |
Facultatif | DateTime chaîne (ISO-8601) |
Ce paramètre définit le moment de suppression de l’activité en direct de l’interface utilisateur. |
stale_date |
Facultatif | DateTime chaîne (ISO-8601) |
Ce paramètre indique au système quand le contenu de l’activité en direct devient obsolète dans l’interface utilisateur. |
notification |
Requis | Objet | Inclure un apple_push objet pour définir une notification push. Le comportement de cette notification push dépend du fait que l’utilisateur soit actif ou utilise un appareil proxy.
|
external_user_ids |
Facultatif si segment_id ou audience est fourni |
Tableau de chaînes de caractères | Voir ID externe. |
segment_id |
Facultatif si external_user_ids ou audience est fourni |
Chaîne de caractères | Voir identifiant de segmentation. |
custom_audience |
Facultatif si external_user_ids ou segment_id est fourni |
Objet Audience connectée | Voir audience connectée. |
Exemple de demande
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
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"
},
"dismissal_date": "2024-01-22T00:00:00+0000",
"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
}'
Réponse
Deux réponses de code de statut existent pour cet endpoint : 201
et 4XX
.
Exemple de réponse réussie
Un code de statut 201
est renvoyé si la requête a été formatée correctement et que nous l’avons reçue. Le code de statut 201
pourrait renvoyer le corps de réponse suivant.
1
2
3
{
"message": "success"
}
Exemple de réponse échouée
La classe du code de statut 4XX
indique une erreur client. Reportez-vous à l’article erreurs et réponses de l’API pour plus d’informations sur les erreurs que vous pouvez rencontrer.
Le code de statut 400
pourrait renvoyer le corps de réponse suivant.
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' "
}