Iniciar atividade ao vivo

Use esse endpoint para iniciar remotamente as Live Activities exibidas no seu app para iOS. Esse endpoint requer configuração adicional.

Depois de criar uma Live Activity, você pode fazer uma solicitação POST para iniciar remotamente sua atividade para qualquer segmento específico. Para saber mais sobre as Live Activities da Apple, consulte Como iniciar e atualizar Live Activities com notificações por push do ActivityKit.

Se content-available não estiver definido, a prioridade padrão do serviço de Notificações por Push da Apple (APNs) é 10. Se content-available estiver definido, essa prioridade é 5. Consulte objeto de push da Apple para mais detalhes.

Configurando o encerramento automático

Para configurar o encerramento automático após o início de uma Live Activity, agende uma solicitação de acompanhamento para o endpoint de atualização a partir do seu backend.

1. Envie uma solicitação /messages/live_activity/start com um activity_id que você possa reutilizar posteriormente.
2. Armazene esse activity_id e o horário de encerramento desejado no agendador do seu backend.
3. No horário de encerramento desejado, envie uma solicitação /messages/live_activity/update com end_activity definido como true.
4. Configure o comportamento de encerramento na mesma solicitação de atualização. Para mais detalhes, consulte o endpoint /messages/live_activity/update.
5. Verifique os eventos de envio e resultado no Registro de atividade de mensagens.

Pré-requisitos

Para usar este endpoint, você precisará concluir o seguinte:

• Gerar uma chave de API com a permissão messages.live_activity.start.
• Criar uma Live Activity usando o SDK Swift da Braze.

Limite de taxa

Aplicamos o limite de taxa padrão da Braze de 250.000 solicitações por hora a esse endpoint, conforme documentado em Limites de taxa da API.

Corpo da solicitação

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

Parâmetros de solicitação

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

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 a recebemos. 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' "
}