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, faça uma solicitação POST para direcionar um segmento, um público conectado ou usuários específicos. Identifique usuários específicos por ID de usuário externo, alias de usuário ou ambos. 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 (APN) é 10. Se content-available estiver definido, essa prioridade é 5. Para saber mais, consulte objeto de push da Apple.

Dica

Para encerrar uma Live Activity, use o endpoint /messages/live_activity/update com end_activity definido como true.

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 atividades de envio de mensagem.

Pré-requisitos

Para usar este endpoint, complete os seguintes pré-requisitos:

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

Importante

Se a carga útil final renderizada for maior do que o tamanho máximo permitido pelo serviço correspondente, o envio não será bem-sucedido.

Importante

Quando você direciona usuários específicos, a Braze inicia uma Live Activity apenas para external_user_ids e user_aliases que correspondam a usuários existentes.

Limite de frequência

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

Corpo da solicitação

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 solicitação

Você pode incluir external_user_ids e user_aliases na mesma solicitação. O comprimento combinado das matrizes não pode exceder 50. A Braze direciona os usuários que correspondam a qualquer um dos parâmetros e envia apenas uma vez quando múltiplos identificadores se resolvem para o mesmo usuário.

Não combine external_user_ids ou user_aliases com segment_id ou custom_audience. Neste endpoint, use custom_audience para passar filtros de 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
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"
    }
  ]
}'

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