Iniciar actividad en vivo

Utiliza este endpoint para iniciar de forma remota actividades en vivo que se muestran en tu aplicación iOS. Este endpoint requiere una configuración adicional.

Después de crear una actividad en vivo, realiza una solicitud POST dirigida a un segmento, a una audiencia conectada o a usuarios específicos. Identifica a usuarios específicos por ID de usuario externo, alias de usuario o ambos. Para obtener más información sobre las actividades en vivo de Apple, consulta Starting and updating Live Activities with ActivityKit push notifications.

Si content-available no está configurado, la prioridad predeterminada del servicio de notificaciones push de Apple (APN) es 10. Si content-available está configurado, esta prioridad es 5. Para obtener más información, consulta el objeto push de Apple.

Importante

Después de una solicitud /messages/live_activity/start correcta, espera al menos 5 minutos antes de enviar la primera solicitud /messages/live_activity/update para el mismo activity_id. Este intervalo da tiempo a Braze y a los APN para registrar la nueva actividad en vivo y el mapeado de su token. Si envías la primera actualización demasiado pronto, es posible que esa actualización no se aplique a la actividad.

Consejo

Para finalizar una actividad en vivo, utiliza el endpoint /messages/live_activity/update con end_activity establecido en true.

Programar el descarte automático

Para programar el descarte automático después de que se inicie una actividad en vivo, programa una solicitud de seguimiento al endpoint de actualización desde tu backend.

1. Envía una solicitud /messages/live_activity/start con un activity_id que puedas reutilizar más adelante.
2. Almacena ese activity_id y la hora de finalización objetivo en el programador de tu backend.
3. A la hora de finalización objetivo, envía una solicitud /messages/live_activity/update con end_activity establecido en true.
4. Configura el comportamiento de descarte en la misma solicitud de actualización. Para más detalles, consulta el endpoint /messages/live_activity/update.
5. Verifica los eventos de envío y resultado en el Registro de actividad de mensajes.

Requisitos previos

Para utilizar este endpoint, completa los siguientes requisitos previos:

• Genera una clave de API con el permiso messages.live_activity.start.
• Crea una actividad en vivo con el SDK de Braze para Swift.

Importante

Si la carga útil final es mayor que el tamaño máximo permitido del servicio correspondiente, el envío no se realizará correctamente.

Importante

Cuando te diriges a usuarios específicos, Braze inicia una actividad en vivo solo para los external_user_ids y user_aliases que correspondan a usuarios existentes.

Límite de velocidad

Aplicamos el límite de velocidad predeterminado de Braze de 250 000 solicitudes por hora a este endpoint, como se documenta en Límites de velocidad de la API.

Cuerpo de la solicitud

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

Parámetros de la solicitud

Puedes incluir external_user_ids y user_aliases en la misma solicitud. La longitud combinada de sus matrices no puede superar 50. Braze se dirige a los usuarios que coincidan con cualquiera de los dos parámetros y solo envía una vez cuando varios identificadores corresponden al mismo usuario.

No combines external_user_ids ni user_aliases con segment_id o custom_audience. En este endpoint, utiliza custom_audience para pasar filtros de audiencia conectada.

Ejemplo de solicitud

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

Respuesta

Hay dos respuestas de código de estado para este endpoint: 201 y 4XX.

Ejemplo de respuesta correcta

Se devuelve un código de estado 201 si la solicitud tiene el formato correcto y Braze la recibe. El código de estado 201 puede devolver el siguiente cuerpo de respuesta.

1
2
3

{
  "message": "success"
}

Ejemplo de respuesta de error

La clase de código de estado 4XX indica un error del cliente. Consulta el artículo de errores y respuestas de la API para obtener más información sobre los errores que puedes encontrar.

El código de estado 400 podría devolver el siguiente cuerpo de respuesta.

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