Iniciar atividade ao vivo
/messages/live_activity/start
Use esse endpoint para iniciar remotamente as Live Activities exibidas em seu app para iOS. Esse endpoint requer configuração adicional.
Depois de criar uma atividade ao vivo, você pode fazer uma solicitação POST para iniciar remotamente sua atividade para qualquer segmento específico. Para saber mais sobre o Live Activities da Apple, consulte Como iniciar e atualizar o Live Activities com notificações por push do ActivityKit.
Pré-requisitos
Para usar este endpoint, você precisará concluir o seguinte:
- Gerar uma chave de API com a permissão
messages.live_activity.start
. - Crie uma atividade ao vivo usando o Braze Swift SDK.
Limite de taxa
We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.
Corpo da solicitação
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"
}
Parâmetros de solicitação
Parâmetro | Obrigatória | Tipo de dados | Descrição |
---|---|---|---|
app_id |
Obrigatória | String | Identificador da API do app recuperado da página Chaves da API. |
activity_id |
Obrigatória | String | Defina uma string personalizada como seu activity_id . Você usará esse ID quando desejar enviar eventos de atualização ou encerramento para sua atividade ao vivo. |
activity_attributes_type |
Obrigatória | String | O tipo de atribuição de atividade que você define em liveActivities.registerPushToStart no seu app. |
activity_attributes |
Obrigatória | Objeto | Os valores de atribuição estáticos para o tipo de atividade (como os nomes das equipes esportivas, que não mudam). |
content_state |
Obrigatória | Objeto | Você define os ContentState parâmetros quando cria sua Atividade ao Vivo. Passe os valores atualizados para o seu ContentState usando este objeto.O formato desta solicitação deve corresponder à forma que você definiu inicialmente. |
dismissal_date |
Opcional | Datetime (string ISO-8601) |
Esse parâmetro define o tempo para remover a atividade ao vivo da interface do usuário. |
stale_date |
Opcional | Datetime (string ISO-8601) |
Este parâmetro informa ao sistema quando o conteúdo da Atividade ao Vivo é marcado como desatualizado na interface do usuário. |
notification |
Obrigatória | Objeto | Inclua um apple_push objeto para definir uma notificação por push. Esse comportamento dessa notificação por push depende se o usuário está ativo ou se o usuário está usando um dispositivo proxy.
|
external_user_ids |
Opcional se segment_id ou audience for fornecido |
Matriz de strings | Consulte ID de usuário externo. |
segment_id |
Opcional se external_user_ids ou audience for fornecido |
String | Consulte identificador de segmento. |
custom_audience |
Opcional se external_user_ids ou segment_id for fornecido |
Objeto do público conectado | Veja público conectado. |
Exemplo de solicitação
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
}'
Resposta
Existem dois códigos de status para este endpoint: 201
e 4XX
.
Exemplo de resposta bem-sucedida
Um código de status 201
é retornado se a solicitação foi formatada corretamente e recebemos a solicitação. O código de status 201
pode retornar o seguinte corpo de resposta.
1
2
3
{
"message": "success"
}
Exemplo de resposta de erro
A classe de código de status 4XX
indica um erro do cliente. Consulte o artigo erros e respostas da API para saber mais sobre os erros que você pode encontrar.
O código de status 400
pode retornar o seguinte corpo de resposta.
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' "
}