Atividades ao vivo para Swift

Saiba como implementar as Atividades ao Vivo para o SDK Swift da Braze. As Atividades ao Vivo são notificações persistentes e interativas exibidas diretamente na tela de bloqueio. Com elas, os usuários recebem atualizações dinâmicas em tempo real—sem desbloquear o dispositivo.

Como funciona

As atividades ao vivo apresentam uma combinação de informações estáticas e informações dinâmicas que você atualiza. Por exemplo, você pode criar uma atividade ao vivo que mostra o status de uma entrega. Essa atividade ao vivo inclui o nome da sua empresa como informação estática. Ela também inclui um “Tempo até a entrega” dinâmico, que é atualizado à medida que o entregador se aproxima do destino.

Como desenvolvedor, você pode usar a Braze para gerenciar o ciclo de vida das suas atividades ao vivo e fazer chamadas para a REST API da Braze para atualizá-las. Assim, todos os dispositivos inscritos recebem a atualização o mais rápido possível. E, como você gerencia as atividades ao vivo pela Braze, pode usá-las em conjunto com seus outros canais de envio de mensagens—notificações por push, mensagens no app, Content Cards—para impulsionar a adoção.

Diagrama de sequência

• live activities sequence diagram

---
config:
  theme: mc
---
sequenceDiagram
  participant Server as Client Server
  participant Device as User Device
  participant App as iOS App / Braze SDK
  participant BrazeAPI as Braze API
  participant APNS as Apple Push Notification Service
  Note over Server, APNS: Launch Option 1<br/>Locally Start Activities
  App ->> App: Register a Live Activity using <br>`launchActivity(pushTokenTag:activity:)`
  App ->> App: Get push token from iOS
  App ->> BrazeAPI: Activity ID & Push token<br>automatically sent to Braze
  Note over Server, APNS: Launch Option 2<br/>Remotely Start Activities
  Device ->> App: Call `registerPushToStart`<br>to collect push tokens early
  App ->> BrazeAPI: Push-to-start tokens sent to Braze
  Server ->> BrazeAPI: POST /messages/live_activity/start
  Note right of BrazeAPI: Payload includes:<br>- push_token<br>- activity_id<br>- external_id<br>- event_name<br>- content_state (optional)
  BrazeAPI ->> APNS: Live activity start request
  APNS ->> Device: APNS sends activity to device
  App ->> App: Get push token from iOS
  App ->> BrazeAPI: Activity ID & Push token<br>automatically sent to Braze
  Note over Server, APNS: Resuming activities upon app launch
  App ->> App: Call `resumeActivities(ofType:)` on each app launch
  Note over Server, APNS: Updating a Live Activity
  loop update a live activity
  Server ->> BrazeAPI: POST /messages/live_activity/update
  Note right of BrazeAPI: Payload includes changes<br>to ContentState (dynamic variables)
  BrazeAPI ->> APNS: Update sent to APNS
  APNS ->> Device: APNS sends update to device
  end
  Note over Server, APNS: Ending a Live Activity
  Server ->> BrazeAPI: POST /messages/live_activity/update
  Note right of BrazeAPI: Activity can be ended via:<br> - User manually dismisses<br>- Times out after 12 hours<br>- Setting `end_activity: true` on `/messages/live_activity/update`
  APNS ->> Device: Live activity is dismissed

Implementação de uma Live Activity

Pré-requisitos

Antes de poder usar esse recurso, você precisará integrar o Braze Swift SDK. Você também precisará concluir o seguinte:

• Confira se o seu projeto tem como alvo o iOS 16.1 ou superior.
• Adicione a capacidade Push Notification em Signing & Capabilities no seu projeto do Xcode.
• Confira se as chaves .p8 são usadas para enviar notificações. Arquivos mais antigos, como .p12 ou .pem, não são suportados.
• A partir da versão 8.2.0 do SDK Swift da Braze, você pode registrar remotamente uma Live Activity. Para usar esse recurso, é necessário o iOS 17.2 ou superior.

Nota

Embora as Live Activities e as notificações por push sejam parecidas, as permissões de sistema delas são separadas. Por padrão, todos os recursos de Live Activity estão ativados, mas os usuários podem desativar esse recurso por app.

Etapa 1: Criar uma atividade

Primeiro, confira se você seguiu as instruções de Displaying live data with Live Activities na documentação da Apple para configurar as Live Activities no seu aplicativo iOS. Como parte dessa tarefa, inclua NSSupportsLiveActivities definido como YES no seu Info.plist.

Como a natureza exata da sua Live Activity depende do seu caso de negócio, configure e inicialize os objetos Activity. É importante definir:

• ActivityAttributes: Esse protocolo define o conteúdo estático (que não muda) e dinâmico (que muda) exibido na sua Live Activity.
• ActivityAttributes.ContentState: Esse tipo define os dados dinâmicos que são atualizados ao longo da atividade.

Você também usa o SwiftUI para criar a apresentação da interface na tela de bloqueio e na Dynamic Island nos dispositivos compatíveis.

Familiarize-se com os pré-requisitos e limitações da Apple para Live Activities, pois essas restrições são independentes da Braze.

Nota

Se você pretende enviar pushes frequentes para a mesma Live Activity, pode evitar ser limitado pelo orçamento da Apple definindo NSSupportsLiveActivitiesFrequentUpdates como YES no seu arquivo Info.plist. Para saber mais, consulte a seção Determine the update frequency na documentação do ActivityKit.

Exemplo

Vamos imaginar que queremos criar uma Live Activity para dar aos nossos usuários atualizações sobre o programa Superb Owl, em que dois centros de resgate de animais silvestres concorrentes ganham pontos pelas corujas que abrigam. Neste exemplo, criamos uma struct chamada SportsActivityAttributes, mas você pode usar sua própria implementação de ActivityAttributes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
struct SportsActivityAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String
}

Etapa 2: Iniciar a atividade

Primeiro, escolha como você quer registrar sua atividade:

• Remota: Use o método registerPushToStart logo no início do ciclo de vida do usuário e antes que o token push-to-start seja necessário. Depois, inicie uma atividade usando o endpoint /messages/live_activity/start.
• Local: Crie uma instância da sua Live Activity e, em seguida, use o método launchActivity para criar tokens por push para a Braze gerenciar.

• remote
• local

Importante

Para registrar remotamente uma Live Activity, é necessário o iOS 17.2 ou superior.

Etapa 2.1: Adicionar o BrazeKit à sua extensão de widget

No seu projeto do Xcode, selecione o nome do seu app e depois General. Em Frameworks and Libraries, confirme que BrazeKit está listado.

Etapa 2.2: Adicionar o protocolo BrazeLiveActivityAttributes

Na sua implementação de ActivityAttributes, adicione a conformidade com o protocolo BrazeLiveActivityAttributes e, em seguida, adicione a propriedade brazeActivityId ao seu modelo de atributos.

Importante

O iOS mapeia a propriedade brazeActivityId para o campo correspondente na carga útil push-to-start da sua Live Activity. Por isso, ela não deve ser renomeada nem receber nenhum outro valor.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
// 1. Add the `BrazeLiveActivityAttributes` conformance to your `ActivityAttributes` struct.
struct SportsActivityAttributes: ActivityAttributes, BrazeLiveActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String

  // 2. Add the `String?` property to represent the activity ID.
  var brazeActivityId: String?
}

Etapa 2.3: Registrar para push-to-start

Em seguida, registre o tipo de Live Activity para que a Braze possa rastrear todos os tokens push-to-start e as instâncias de Live Activity associadas a esse tipo.

Aviso

O sistema operacional iOS só gera tokens push-to-start durante a primeira instalação do app depois que um dispositivo é reiniciado. Para garantir que seus tokens sejam registrados de forma confiável, chame registerPushToStart no seu método didFinishLaunchingWithOptions.

Exemplo

No exemplo a seguir, a classe LiveActivityManager lida com os objetos de Live Activity. Depois, o método registerPushToStart registra SportsActivityAttributes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {

  @available(iOS 17.2, *)
  func registerActivityType() {
    // This method returns a Swift background task.
    // You may keep a reference to this task if you need to cancel it wherever appropriate, or ignore the return value if you wish.
    let pushToStartObserver: Task = Self.braze?.liveActivities.registerPushToStart(
      forType: Activity<SportsActivityAttributes>.self,
      name: "SportsActivityAttributes"
    )
  }

}

Etapa 2.4: Enviar uma notificação push-to-start

Envie uma notificação push-to-start remota usando o endpoint /messages/live_activity/start.

Você pode usar o framework ActivityKit da Apple para obter um token por push, que o SDK da Braze pode gerenciar para você. Isso permite atualizar as Live Activities pela API da Braze, já que a Braze envia o token por push para o serviço de Notificações por Push da Apple (APN) no backend.

1. Crie uma instância da sua implementação de Live Activity usando as APIs do ActivityKit da Apple.
2. Defina o parâmetro pushType como .token.
3. Passe os ActivitiesAttributes e o ContentState da Live Activity que você definiu.
4. Registre sua atividade na sua instância da Braze passando-a para launchActivity(pushTokenTag:activity:). O parâmetro pushTokenTag é uma string personalizada que você define. Ela deve ser exclusiva para cada Live Activity que você criar.

Depois que você registra a Live Activity, o SDK da Braze extrai e observa as mudanças nos tokens por push.

Exemplo

No nosso exemplo, crie uma classe chamada LiveActivityManager como interface para os nossos objetos de Live Activity. Em seguida, defina o pushTokenTag como "sports-game-2024-03-15".

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

import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {

  @available(iOS 16.2, *)
  func createActivity() {
    let activityAttributes = SportsActivityAttributes(gameName: "Superb Owl", gameNumber: "Game 1")
    let contentState = SportsActivityAttributes.ContentState(teamOneScore: "0", teamTwoScore: "0")
    let activityContent = ActivityContent(state: contentState, staleDate: nil)
    if let activity = try? Activity.request(attributes: activityAttributes,
                                            content: activityContent,
      // Setting your pushType as .token allows the Activity to generate push tokens for the server to watch.
                                            pushType: .token) {
      // Register your Live Activity with Braze using the pushTokenTag.
      // This method returns a Swift background task.
      // You may keep a reference to this task if you need to cancel it wherever appropriate, or ignore the return value if you wish.
      let liveActivityObserver: Task = AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "sports-game-2024-03-15",
                                                                                        activity: activity)
    }
  }

}

Seu widget de Live Activity exibe esse conteúdo inicial para os usuários.

Etapa 3: Retomar o rastreamento da atividade

Para garantir que a Braze rastreie sua Live Activity quando o app for iniciado:

1. Abra seu arquivo AppDelegate.
2. Importe o módulo ActivityKit, se estiver disponível.
3. Chame resumeActivities(ofType:) em application(_:didFinishLaunchingWithOptions:) para todos os tipos de ActivityAttributes que você registrou no seu aplicativo.

Isso permite que a Braze retome as tarefas de rastreamento das atualizações de token por push de todas as Live Activities ativas. Se um usuário tiver dispensado explicitamente a Live Activity no dispositivo, ela é considerada removida e a Braze deixa de rastreá-la.

Exemplo

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

import UIKit
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

  static var braze: Braze? = nil

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {

    if #available(iOS 16.1, *) {
      Self.braze?.liveActivities.resumeActivities(
        ofType: Activity<SportsActivityAttributes>.self
      )
    }

    return true
  }
}

Etapa 4: Atualizar a atividade

O endpoint /messages/live_activity/update permite atualizar uma Live Activity por meio de notificações por push enviadas pela REST API da Braze. Use esse endpoint para atualizar o ContentState da sua Live Activity.

Importante

Quando você chamar /messages/live_activity/start e depois enviar a primeira solicitação /messages/live_activity/update para o mesmo activity_id, aguarde pelo menos 5 minutos entre as solicitações. Essa postergação dá tempo para a Braze e o APN registrarem a nova Live Activity e o mapeamento do token. Se você enviar a primeira atualização cedo demais, ela pode não ser aplicada à atividade.

À medida que você atualiza o ContentState, seu widget de Live Activity exibe as novas informações. Veja como fica o programa Superb Owl no final do primeiro tempo.

Consulte nosso artigo sobre o endpoint /messages/live_activity/update para ver todos os detalhes.

Etapa 5: Encerrar a atividade

Quando uma Live Activity está ativa, ela aparece tanto na tela de bloqueio quanto na Dynamic Island do usuário. Para encerrá-la pela Braze, use o endpoint /messages/live_activity/update com end_activity definido como true.

Para aumentar a confiabilidade ao encerrar uma Live Activity, siga estas etapas opcionais:

1. Se quiser, inclua dismissal_date nessa mesma solicitação update para sugerir quando o iOS deve remover a interface da Live Activity.
2. Verifique os resultados da entrega no Registro de atividades de mensagens.

Programar a dispensa automática

Para programar a dispensa automática, agende uma solicitação de acompanhamento para o endpoint de atualização depois de iniciar a Live Activity.

1. Envie uma solicitação /messages/live_activity/start com um activity_id que você consiga rastrear.
2. Armazene esse activity_id e o horário de término desejado no agendador do seu backend.
3. No horário de término desejado, envie uma solicitação /messages/live_activity/update com end_activity definido como true.
4. Configure a data de dispensa na mesma solicitação de atualização. Para saber mais, consulte o endpoint /messages/live_activity/update.

O momento da dispensa é controlado pelo iOS. Mesmo depois de você enviar uma solicitação de encerramento válida, a remoção da tela de bloqueio ou da Dynamic Island pode atrasar ou se comportar de forma diferente, dependendo das condições do sistema operacional.

Uma Live Activity também pode ser encerrada fora da Braze:

• Dispensa pelo usuário: O usuário pode dispensar manualmente uma Live Activity.
• Tempo esgotado: Após um tempo padrão de oito horas, o iOS remove a Live Activity da Dynamic Island do usuário. Após um tempo padrão de 12 horas, o iOS remove a Live Activity da tela de bloqueio do usuário.

Consulte nosso artigo sobre o endpoint /messages/live_activity/update para ver todos os detalhes.

Rastreamento de Live Activities

Os eventos de Live Activity estão disponíveis no Currents, no Snowflake Data Sharing e no Query Builder. Os eventos a seguir ajudam você a entender e monitorar o ciclo de vida das suas Live Activities e a rastrear a disponibilidade de tokens. Eles também permitem diagnosticar problemas ou verificar status de entrega por conta própria.

• Live Activity Push To Start Token Change: Registra quando um token push-to-start (PTS) é adicionado ou atualizado na Braze. Assim, você pode rastrear os registros e a disponibilidade de tokens por usuário.
• Live Activity Update Token Change: Rastreia a adição, a atualização ou a remoção de tokens de atualização de Live Activity (LAU).
• Live Activity Send: Registra cada vez que a Braze inicia, atualiza ou encerra uma Live Activity.
• Live Activity Outcome: Indica o status final de entrega para o serviço de Notificações por Push da Apple (APN) de cada Live Activity enviada pela Braze.

Verificar envios de Live Activities

Se precisar confirmar se um espaço de trabalho está enviando Live Activities do iOS, você pode usar os seguintes métodos:

Registro de atividades de mensagens

Acesse Configurações > Registro de atividades de mensagens e filtre por erros de Live Activity para ver os resultados de entrega relacionados a Live Activities no período esperado. Para saber mais, consulte Registro de atividades de mensagens.

Construtor de consultas, Currents ou Snowflake Data Sharing

Verifique os seguintes eventos de Live Activity para confirmar o ciclo de vida e a entrega das Live Activities:

• Live Activity Send: Registrado sempre que a Braze inicia, atualiza ou encerra uma Live Activity
• Live Activity Outcome: Status final de entrega para o APNs de cada Live Activity enviada

Opcionalmente, você também pode verificar os sinais de disponibilidade de token:

• Live Activity Push To Start Token Change
• Live Activity Update Token Change

Dashboard de uso da API

Acesse Configurações > APIs e identificadores > Dashboard, selecione Filtros e filtre por Endpoint para ver as respostas da API. Por exemplo, selecione /messages/live_activity/update (ou /messages/live_activity/start) e confira o volume de solicitações nos últimos 30 dias. As respostas da API indicam que a API está sendo chamada e que as notificações de Live Activities do iOS estão sendo usadas nesse espaço de trabalho. Para saber mais, consulte Dashboard de uso da API.

Observar eventos de Atividades ao Vivo (opcional)

Importante

Não se inscreva diretamente nestes streams do ActivityKit com a Apple. Isso entra em conflito com as inscrições da Braze e impede que as Atividades ao Vivo funcionem corretamente:

1. pushTokenUpdates
2. activityStateUpdates
3. contentUpdates
4. pushToStartTokenUpdates
5. activityUpdates

Em vez disso, use as inscrições mencionadas nesta seção.

O SDK da Braze fornece dois métodos de inscrição em braze.liveActivities para observar o ciclo de vida completo das Atividades ao Vivo. Para um passo a passo completo, consulte o tutorial de Atividades ao Vivo.

• subscribeToStateUpdates(_:): Entrega eventos de ciclo de vida tanto para o registro de tokens push-to-start quanto para instâncias de atividades em execução.
• subscribeToErrors(_:): Entrega erros do SDK e do lado do servidor encontrados durante o rastreamento de Atividades ao Vivo.

Nota

Ambos os métodos retornam um Braze.Cancellable. A inscrição permanece ativa enquanto o valor retornado for mantido por uma referência forte (por exemplo, armazene-o em uma propriedade com o mesmo ciclo de vida da sua instância Braze).

Configurar inscrições

Configure as inscrições uma única vez em application(_:didFinishLaunchingWithOptions:) e mantenha-as durante toda a vida útil do seu app:

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

class AppDelegate: UIResponder, UIApplicationDelegate {
  static var braze: Braze?

  var stateSubscription: Braze.Cancellable?
  var errorSubscription: Braze.Cancellable?

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    let braze = Braze(configuration: config)
    Self.braze = braze

    if #available(iOS 16.1, *) {
      stateSubscription = Self.braze?.liveActivities.subscribeToStateUpdates { event in
        self.handleStateUpdate(event)
      }
      errorSubscription = Self.braze?.liveActivities.subscribeToErrors { error in
        self.handleLiveActivityError(error)
      }
    }

    return true
  }
}

Nota

Os retornos de chamada são disparados apenas para eventos futuros de Atividades ao Vivo. Eles não reproduzem o estado atual no momento da inscrição. Para consultar o snapshot do estado atual, use Activity<T>.activities.

subscribeToStateUpdates

subscribeToStateUpdates(_:) entrega valores UpdateEvent que cobrem o ciclo de vida completo das Atividades ao Vivo. Os eventos são divididos em dois escopos:

• .activityType(ActivityType): Eventos em nível de tipo para o registro de tokens push-to-start (iOS 17.2+). Ainda não existe nenhuma instância de atividade.
• .activityInstance(ActivityInstance): Eventos em nível de instância para uma atividade específica em execução.

Há suporte para múltiplos assinantes — cada inscrição ativa recebe todas as emissões de forma independente.

Eventos com escopo de tipo

Eventos com escopo de instância

Exemplo

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
31
32
33

func handleStateUpdate(_ event: Braze.LiveActivities.UpdateEvent) {
  switch event {

  // Type-scoped: push-to-start token lifecycle (iOS 17.2+)
  case .activityType(.pushToStartTokenRead(let activityType)):
    print("[\(activityType)] Push-to-start token read by SDK")

  // ...

  // Instance-scoped: SDK tracking
  case .activityInstance(.started(let id, let type, let tag, let source)):
    print("[\(type)] Activity \(id) started via \(source), tag: \(tag)")

  // ...

  // Instance-scoped: ActivityKit lifecycle
  case .activityInstance(.active(let id, let type)):
    print("[\(type)] Activity \(id) is active")

  // ...

  case .activityInstance(.ended(let id, let type)):
    print("[\(type)] Activity \(id) ended")

  // Instance-scoped: content updates (iOS 16.2+)
  case .activityInstance(.contentUpdated(let id, let type)):
    // For more advanced use cases of `contentUpdated`, see the section below
    print("[\(type)] Content updated for activity \(id)")

  case .activityInstance(.pushTokenUpdated(let id, let type)):
    print("[\(type)] Activity \(id) push token rotated")
  }
}

subscribeToErrors

subscribeToErrors(_:) entrega valores ErrorEvent usando os mesmos dois escopos de UpdateEvent:

• .activityType(ActivityType): Erros em nível de tipo para falhas no registro push-to-start.
• .activityInstance(ActivityInstance): Erros em nível de instância para uma atividade em execução.

Use a flag isTransient para determinar se faz sentido tentar novamente. O SDK tenta novamente as falhas transitórias de forma automática.

Erros com escopo de tipo

Erros com escopo de instância

Exemplo

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

func handleLiveActivityError(_ error: Braze.LiveActivities.ErrorEvent) {
  switch error {

  // Type-scoped errors
  case .activityType(.pushToStartRegistrationFailed(let type, let isTransient, let reason)):
    if isTransient {
      print("[\(type)] Push-to-start registration failed (transient, will retry): \(reason)")
    } else {
      print("[\(type)] Push-to-start registration failed (permanent): \(reason)")
    }

  // Instance-scoped errors
  case .activityInstance(.registrationFailed(let id, let type, _, let isTransient, let reason)):
    if isTransient {
      print("[\(type)] Activity \(id) registration failed (transient, retrying): \(reason)")
    } else {
      print("[\(type)] Activity \(id) registration failed (permanent): \(reason)")
    }

  case .activityInstance(.activityNotFound(let id, let type)):
    print("[\(type)] Stored activity \(id) not found on resume")

  case .activityInstance(.invalidPushTokenTag(let id, let type, let tag)):
    print("[\(type)] Activity \(id) has invalid push token tag '\(tag)'")
  }
}

Lidar com atualizações do estado do conteúdo (opcional)

Se você quiser usar o estado do conteúdo da instância real da Atividade ao Vivo, siga esta seção.

Quando um evento .contentUpdated for disparado, use lógica personalizada para buscar a Activity<T> em execução pelo ID em Activity.activities. Em seguida, acesse o ContentState tipado por meio de activity.content.state.

Tipo de atributos único

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

case .activityInstance(.contentUpdated(let id, let type)):
  #if canImport(ActivityKit)
    // Add custom logic look up the Activity<T> by ID and access your app's typed ContentState.
    // In this example, `SportsActivityAttributes` is the app's custom type.
    if #available(iOS 16.2, *),
      let activity = findActivityInstance(id: id, as: SportsActivityAttributes.self)
    {
      // `activityContent` is now strongly typed as a `SportsActivityAttributes`
      let activityContent = activity.content.state
      print("[\(type)] Game \(id) — score: \(activityContent.teamOneScore)–\(activityContent.teamTwoScore)")
      return
    }
  #endif
  print("[\(type)] Content updated for activity \(id)")

// ...

// - MARK: Helper methods

@available(iOS 16.2, *)
func findActivityInstance<Attributes: ActivityAttributes>(
  id: String,
  as type: Attributes.Type
) -> Activity<Attributes>? {
  // Use Apple's API to find the matching Live Activity instance:
  // - https://developer.apple.com/documentation/activitykit/activity/activities
  Activity<Attributes>.activities.first(where: { $0.id == id })
}

Múltiplos tipos de atributos

Se o seu app usa vários tipos de ActivityAttributes, verifique a string type para buscar a Activity<T> adequada:

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
31
32
33
34

case .activityInstance(.contentUpdated(let id, let type)):
  #if canImport(ActivityKit)
    if #available(iOS 16.2, *) {
      if type == "SportsActivityAttributes",
        let activity = findActivityInstance(id: id, as: SportsActivityAttributes.self)
      {
        let activityContent = activity.content.state
        print("[\(type)] Game \(id) — score: \(activityContent.teamOneScore)–\(activityContent.teamTwoScore)")
        return

      } else if type == "OrderActivityAttributes",
        let activity = findActivityInstance(id: id, as: OrderActivityAttributes.self)
      {
        let activityContent = activity.content.state
        print("[\(type)] Order \(id) — status: \(activityContent.status), ETA: \(activityContent.eta)")
        return
      }
    }
  #endif
  print("[\(type)] Content updated for activity \(id)")

// ...

// - MARK: Helper methods

@available(iOS 16.2, *)
func findActivityInstance<Attributes: ActivityAttributes>(
  id: String,
  as type: Attributes.Type
) -> Activity<Attributes>? {
  // Use Apple's API to find the matching Live Activity instance:
  // - https://developer.apple.com/documentation/activitykit/activity/activities
  Activity<Attributes>.activities.first(where: { $0.id == id })
}

Perguntas frequentes (FAQ)

Funcionalidade e suporte

Quais plataformas suportam Atividades ao Vivo?

Atualmente, as Atividades ao Vivo são um recurso específico do iOS e iPadOS. Por padrão, atividades lançadas em um iPhone ou iPad também são exibidas em qualquer dispositivo watchOS 11+ ou macOS 26+ emparelhado.

A Braze não oferece suporte nativo a Atividades ao Vivo no Android no momento. Para Android, você pode criar experiências de atualização em tempo real por meio de notificações por push da Braze e renderização personalizada de notificações.

O artigo sobre Atividades ao Vivo aborda os pré-requisitos para o gerenciamento de Atividades ao Vivo por meio do SDK Swift da Braze.

Os apps React Native são compatíveis com Atividades ao Vivo?

Sim, o React Native SDK 3.0.0+ oferece suporte a Atividades ao Vivo por meio do SDK Swift da Braze. Ou seja, você precisa escrever código React Native iOS diretamente sobre o SDK Swift da Braze.

Não há uma API de conveniência JavaScript específica do React Native para Atividades ao Vivo porque os recursos de Atividades ao Vivo fornecidos pela Apple usam linguagens intraduzíveis em JavaScript (por exemplo, concorrência Swift, genéricos, SwiftUI).

A Braze oferece suporte a Atividades ao Vivo como uma Campaign ou etapa do Canvas?

Não, isso não é suportado no momento.

Notificações por push e Atividades ao Vivo

O que acontece se uma notificação por push for enviada enquanto uma Atividade ao Vivo estiver ativa?

As Atividades ao Vivo e as notificações por push ocupam espaços diferentes na tela e não entram em conflito na tela do usuário.

Se as Atividades ao Vivo utilizam a funcionalidade de mensagens push, as notificações por push precisam estar ativadas para receber Atividades ao Vivo?

Embora as Atividades ao Vivo dependam de notificações por push para atualizações, elas são controladas por configurações de usuário diferentes. Um usuário pode aceitar Atividades ao Vivo, mas não as notificações por push, e vice-versa.

Os tokens de atualização de Atividade ao Vivo expiram após oito horas.

As Atividades ao Vivo requerem push primers?

Os push primers são uma prática recomendada para solicitar que os usuários aceitem notificações por push do seu app. No entanto, não há nenhum prompt do sistema para aceitar Atividades ao Vivo. Por padrão, os usuários aceitam Atividades ao Vivo para um app individual quando instalam esse app no iOS 16.1 ou posterior. Essa permissão pode ser desativada ou reativada nas configurações do dispositivo por app.

Tópicos técnicos e solução de problemas

Como posso saber se as Atividades ao Vivo têm erros?

Todos os erros de Atividades ao Vivo são registrados no dashboard da Braze no Registro de atividades de envio de mensagem, onde é possível filtrar por “LiveActivity Errors”.

Depois de enviar uma notificação push-to-start, por que não recebi minha Atividade ao Vivo?

Primeiro, verifique se sua carga útil inclui todos os campos obrigatórios descritos no endpoint messages/live_activity/start. Os campos activity_attributes e content_state devem corresponder às propriedades definidas no código do seu projeto. Se tiver certeza de que a carga útil está correta, é possível que você esteja sendo limitado pelos APNs. Esse limite é imposto pela Apple e não pela Braze.

Para verificar se a notificação push-to-start chegou com sucesso ao dispositivo, mas não foi exibida devido a limites de taxa, você pode depurar o projeto usando o app Console no Mac. Anexe o processo de gravação do dispositivo desejado e, em seguida, filtre os registros por process:liveactivitiesd na barra de pesquisa.

Depois de iniciar minha Atividade ao Vivo com push-to-start, por que ela não está recebendo novas atualizações?

Verifique se você implementou corretamente as instruções na Etapa 2.2: Adicionar o protocolo BrazeLiveActivityAttributes. Seu ActivityAttributes deve conter tanto a conformidade com o protocolo BrazeLiveActivityAttributes quanto a propriedade brazeActivityId.

Depois de receber uma notificação push-to-start de Atividade ao Vivo, verifique se você consegue ver uma solicitação de rede de saída para o endpoint /push_token_tag da sua URL da Braze e se ela contém o ID da atividade correto no campo "tag".

Por fim, certifique-se de que o tipo de atributo da Atividade ao Vivo na sua carga útil de atualização corresponda exatamente à string e à classe usadas na chamada do método do SDK para registerPushToStart. Use constantes para evitar erros de digitação.

Estou recebendo uma resposta de acesso negado quando tento usar o endpoint live_activity/update. Por quê?

As chaves de API que você usa precisam ter as permissões corretas para acessar os diferentes endpoints da API da Braze. Se estiver usando uma chave de API criada anteriormente, é possível que tenha se esquecido de atualizar as permissões. Leia nossa visão geral da segurança da chave de API para relembrar.

O endpoint messages/send compartilha os limites de taxa com o endpoint messages/live_activity/update?

Por padrão, o limite de taxa do endpoint messages/live_activity/update é de 250.000 solicitações por hora, por espaço de trabalho e em vários endpoints. Consulte os limites de taxa da API para saber mais.