Démarrer une activité en direct

Utilisez cet endpoint pour démarrer à distance les activités en direct affichées dans votre application iOS. Cet endpoint nécessite une configuration supplémentaire.

Après avoir créé une activité en direct, envoyez une requête POST pour cibler un Segment, une audience connectée ou des utilisateurs spécifiques. Identifiez les utilisateurs spécifiques par leur ID utilisateur externe, leur alias d’utilisateur, ou les deux. Pour en savoir plus sur les activités en direct d’Apple, consultez Starting and updating Live Activities with ActivityKit push notifications.

Si content-available n’est pas défini, la priorité par défaut du service Apple Push Notification (APNs) est de 10. Si content-available est défini, cette priorité est de 5. Pour plus d’informations, consultez l’objet push Apple.

Important

Après une requête /messages/live_activity/start réussie, attendez au moins 5 minutes avant d’envoyer la première requête /messages/live_activity/update pour le même activity_id. Ce délai laisse à Braze et aux APNs le temps d’enregistrer la nouvelle activité en direct et le mappage de son jeton. Si vous envoyez la première mise à jour trop tôt, elle risque de ne pas s’appliquer à l’activité.

Conseil

Pour mettre fin à une activité en direct, utilisez l’endpoint /messages/live_activity/update avec end_activity défini sur true.

Planifier la fermeture automatique

Pour planifier la fermeture automatique d’une activité en direct après son démarrage, programmez depuis votre backend une requête de suivi vers l’endpoint de mise à jour.

1. Envoyez une requête /messages/live_activity/start avec un activity_id que vous pourrez réutiliser ultérieurement.
2. Stockez cet activity_id et l’heure de fin souhaitée dans le planificateur de votre backend.
3. À l’heure de fin prévue, envoyez une requête /messages/live_activity/update avec end_activity défini sur true.
4. Configurez le comportement de fermeture dans cette même requête de mise à jour. Pour plus de détails, consultez l’endpoint /messages/live_activity/update.
5. Vérifiez les événements d’envoi et de résultat dans le journal d’activité des messages.

Conditions préalables

Pour utiliser cet endpoint, remplissez les conditions préalables 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.

Important

Si la charge utile finale est plus grande que la taille maximale autorisée par le service correspondant, l’envoi n’aboutira pas.

Important

Lorsque vous ciblez des utilisateurs spécifiques, Braze ne démarre une activité en direct que pour les external_user_ids et user_aliases qui correspondent à des utilisateurs existants.

Limite de débit

La limite de débit par défaut de Braze, soit 250 000 requêtes par heure, s’applique à cet endpoint, comme indiqué dans Limites de débit de l’API.

Corps de la requête

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

Paramètres de la requête

Vous pouvez inclure external_user_ids et user_aliases dans la même requête. La longueur combinée de leurs tableaux ne peut pas dépasser 50. Braze cible les utilisateurs qui correspondent à l’un ou l’autre des paramètres et n’envoie le message qu’une seule fois lorsque plusieurs identifiants renvoient au même utilisateur.

Ne combinez pas external_user_ids ou user_aliases avec segment_id ou custom_audience. Sur cet endpoint, utilisez custom_audience pour transmettre des filtres d’audience connectée.

Exemple de requête

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"
    }
  ]
}'

Réponse

Cet endpoint peut renvoyer deux codes de statut : 201 et 4XX.

Exemple de réponse réussie

Un code de statut 201 est renvoyé si la requête est correctement formatée et que Braze la reçoit. Le code de statut 201 peut renvoyer le corps de réponse suivant.

1
2
3

{
  "message": "success"
}

Exemple de réponse d’erreur

La classe de codes de statut 4XX indique une erreur côté client. Consultez l’article Erreurs et réponses de l’API pour en savoir plus sur les erreurs que vous pourriez rencontrer.

Le code de statut 400 peut 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' "
}