Actividades en vivo para Swift

Aprende a implementar las actividades en vivo para el SDK Swift de Braze. Las actividades en vivo son notificaciones persistentes e interactivas que se muestran directamente en la pantalla de bloqueo, lo que permite a los usuarios obtener actualizaciones dinámicas en tiempo real—sin necesidad de desbloquear el dispositivo.

Cómo funciona

Las actividades en vivo presentan una combinación de información estática e información dinámica que tú actualizas. Por ejemplo, puedes crear una actividad en vivo que proporcione un rastreador de estado para una entrega. Esta actividad en vivo incluye el nombre de tu empresa como información estática, así como un “Tiempo de entrega” dinámico que se actualiza a medida que el repartidor se acerca a su destino.

Como desarrollador, puedes usar Braze para gestionar los ciclos de vida de tus actividades en vivo, realizar llamadas a la REST API de Braze para actualizar las actividades en vivo y hacer que todos los dispositivos suscritos reciban la actualización lo antes posible. Y, como gestionas las actividades en vivo a través de Braze, puedes usarlas junto con tus otros canales de mensajería—notificaciones push, mensajes dentro de la aplicación, Content Cards—para impulsar la adopción.

Diagrama de secuencia

• 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

Implementar una Live Activity

Requisitos previos

Antes de poder utilizar esta característica, tendrás que integrar el SDK de Swift Braze. También necesitarás completar lo siguiente:

• Asegúrate de que tu proyecto esté orientado a iOS 16.1 o posterior.
• Añade el permiso Push Notification en Signing & Capabilities en tu proyecto de Xcode.
• Asegúrate de que se utilicen claves .p8 para enviar notificaciones. Los archivos más antiguos, como .p12 o .pem, no son compatibles.
• A partir de la versión 8.2.0 de Braze Swift SDK, puedes registrar remotamente una Live Activity. Para utilizar esta característica, se requiere iOS 17.2 o posterior.

Nota

Aunque las Live Activities y las notificaciones push son similares, sus permisos del sistema son independientes. De forma predeterminada, todas las características de Live Activity están habilitadas, pero los usuarios pueden desactivar esta característica por aplicación.

Paso 1: Crear una actividad

Primero, asegúrate de haber seguido Displaying live data with Live Activities en la documentación de Apple para configurar las Live Activities en tu aplicación iOS. Como parte de esta tarea, asegúrate de incluir NSSupportsLiveActivities establecido en YES en tu Info.plist.

Dado que la naturaleza exacta de tu Live Activity es específica de tu caso de negocio, configura e inicializa los objetos Activity. Es importante que definas:

• ActivityAttributes: Este protocolo define el contenido estático (que no cambia) y dinámico (que cambia) que aparece en tu Live Activity.
• ActivityAttributes.ContentState: Este tipo define los datos dinámicos que se actualizan a lo largo del curso de la actividad.

También utilizas SwiftUI para crear la presentación de la interfaz de usuario en la pantalla de bloqueo y Dynamic Island en dispositivos compatibles.

Asegúrate de estar familiarizado con los prerrequisitos y limitaciones de Apple para las Live Activities, ya que estas restricciones son independientes de Braze.

Nota

Si esperas enviar pushes frecuentes a la misma Live Activity, puedes evitar ser limitado por el presupuesto de Apple estableciendo NSSupportsLiveActivitiesFrequentUpdates en YES en tu archivo Info.plist. Para más detalles, consulta la sección Determine the update frequency en la documentación de ActivityKit.

Ejemplo

Imaginemos que queremos crear una Live Activity para dar a nuestros usuarios actualizaciones sobre el espectáculo Superb Owl, donde dos centros de rescate de vida silvestre en competencia reciben puntos por los búhos que tienen en residencia. Para este ejemplo, hemos creado una estructura llamada SportsActivityAttributes, pero puedes usar tu propia implementación 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
}

Paso 2: Iniciar la actividad

Primero, elige cómo quieres registrar tu actividad:

• Remoto: Usa el método registerPushToStart temprano en el ciclo de vida de tu usuario y antes de que se necesite el token push-to-start, luego inicia una actividad usando el endpoint /messages/live_activity/start.
• Local: Crea una instancia de tu Live Activity, luego usa el método launchActivity para crear tokens push que Braze pueda gestionar.

• remoto
• local

Importante

Para registrar remotamente una Live Activity, se requiere iOS 17.2 o posterior.

Paso 2.1: Añadir BrazeKit a tu extensión de widget

En tu proyecto de Xcode, selecciona el nombre de tu aplicación, luego General. En Frameworks and Libraries, confirma que BrazeKit esté listado.

Paso 2.2: Añadir el protocolo BrazeLiveActivityAttributes

En tu implementación de ActivityAttributes, añade la conformidad con el protocolo BrazeLiveActivityAttributes, luego añade la propiedad brazeActivityId a tu modelo de atributos.

Importante

iOS mapea la propiedad brazeActivityId al campo correspondiente en tu carga útil push-to-start de Live Activity, por lo que no debe ser renombrada ni asignada a ningún otro 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?
}

Paso 2.3: Registrarse para push-to-start

A continuación, registra el tipo de Live Activity, para que Braze pueda rastrear todos los tokens push-to-start y las instancias de Live Activity asociadas con este tipo.

Advertencia

El sistema operativo iOS solo genera tokens push-to-start durante la primera instalación de la aplicación después de reiniciar el dispositivo. Para asegurarte de que tus tokens se registren de forma fiable, llama a registerPushToStart en tu método didFinishLaunchingWithOptions.

Ejemplo

En el siguiente ejemplo, la clase LiveActivityManager gestiona los objetos de Live Activity. Luego, el 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.name
    )
  }

}

Paso 2.4: Enviar una notificación push-to-start

Envía una notificación push-to-start remota usando el endpoint /messages/live_activity/start.

Puedes usar el framework ActivityKit de Apple para obtener un token push, que Braze SDK puede gestionar por ti. Esto te permite actualizar las Live Activities a través de la API de Braze, ya que Braze envía el token push al servicio de notificaciones push de Apple (APN) en el backend.

1. Crea una instancia de tu implementación de Live Activity usando las API de ActivityKit de Apple.
2. Establece el parámetro pushType como .token.
3. Pasa los ActivitiesAttributes y ContentState de Live Activities que definiste.
4. Registra tu actividad con tu instancia de Braze pasándola a launchActivity(pushTokenTag:activity:). El parámetro pushTokenTag es una cadena personalizada que tú defines. Debe ser único para cada Live Activity que crees.

Después de registrar la Live Activity, Braze SDK extrae y observa los cambios en los tokens push.

Ejemplo

Para nuestro ejemplo, crea una clase llamada LiveActivityManager como interfaz para nuestros objetos de Live Activity. Luego, establece el 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)
    }
  }

}

Tu widget de Live Activity muestra este contenido inicial a tus usuarios.

Paso 3: Reanudar el seguimiento de la actividad

Para asegurarte de que Braze rastree tu Live Activity al iniciar la aplicación:

1. Abre tu archivo AppDelegate.
2. Importa el módulo ActivityKit si está disponible.
3. Llama a resumeActivities(ofType:) en application(_:didFinishLaunchingWithOptions:) para todos los tipos de ActivityAttributes que hayas registrado en tu aplicación.

Esto permite a Braze reanudar las tareas para rastrear las actualizaciones de tokens push para todas las Live Activities activas. Ten en cuenta que si un usuario ha descartado explícitamente la Live Activity en su dispositivo, se considera eliminada y Braze ya no la rastrea.

Ejemplo

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

Paso 4: Actualizar la actividad

El endpoint /messages/live_activity/update te permite actualizar una Live Activity a través de notificaciones push enviadas mediante la REST API de Braze. Usa este endpoint para actualizar el ContentState de tu Live Activity.

A medida que actualizas tu ContentState, tu widget de Live Activity muestra la nueva información. Así es como se ve el espectáculo Superb Owl al final de la primera mitad.

Consulta nuestro artículo del endpoint /messages/live_activity/update para obtener todos los detalles.

Paso 5: Finalizar la actividad

Cuando una Live Activity está activa, se muestra tanto en la pantalla de bloqueo del usuario como en Dynamic Island. Para finalizarla a través de Braze, usa el endpoint /messages/live_activity/update con end_activity establecido en true.

Para mejorar la fiabilidad al finalizar una Live Activity, sigue estos pasos opcionales:

1. Opcionalmente incluye dismissal_date en esa misma solicitud de update para sugerir cuándo iOS debe eliminar la interfaz de usuario de la Live Activity.
2. Verifica los resultados de entrega en el registro de actividad de mensajes.

Organizar el descarte automático

Para organizar el descarte automático, programa una solicitud de seguimiento al endpoint de actualización después de iniciar la Live Activity.

1. Envía una solicitud /messages/live_activity/start con un activity_id que puedas rastrear.
2. Almacena ese activity_id y tu hora de finalización objetivo en tu programador del backend.
3. En la hora de finalización objetivo, envía una solicitud /messages/live_activity/update con end_activity establecido en true.
4. Configura la fecha de descarte en la misma solicitud de actualización. Para más detalles, consulta el endpoint /messages/live_activity/update.

Ten en cuenta que el momento del descarte está controlado por iOS. Incluso después de enviar una solicitud de finalización válida, la eliminación de la pantalla de bloqueo o Dynamic Island puede retrasarse o comportarse de manera diferente según las condiciones a nivel del sistema operativo.

Una Live Activity también puede finalizar fuera de Braze:

• Descarte del usuario: Un usuario puede descartar manualmente una Live Activity.
• Tiempo de espera agotado: Después de un tiempo predeterminado de ocho horas, iOS elimina la Live Activity de Dynamic Island del usuario. Después de un tiempo predeterminado de 12 horas, iOS elimina la Live Activity de la pantalla de bloqueo del usuario.

Consulta nuestro artículo del endpoint /messages/live_activity/update para obtener todos los detalles.

Seguimiento de Live Activities

Los eventos de Live Activity están disponibles en Currents, Snowflake Data Sharing y el generador de consultas. Los siguientes eventos pueden ayudarte a comprender y monitorear el ciclo de vida de tus Live Activities, rastrear la disponibilidad de tokens y diagnosticar problemas de forma independiente o verificar los estados de entrega.

• Cambio de token push-to-start de Live Activity: Captura cuándo se añade o actualiza un token push-to-start (PTS) en Braze, lo que te permite rastrear los registros de tokens y la disponibilidad por usuario.
• Cambio de token de actualización de Live Activity: Rastrea la adición, actualización o eliminación de tokens de actualización de Live Activity (LAU).
• Envío de Live Activity: Registra cada vez que Braze inicia, actualiza o finaliza una Live Activity.
• Resultado de Live Activity: Indica el estado de entrega final al servicio de notificaciones push de Apple (APN) para cada Live Activity enviada desde Braze.

Verificar los envíos de Live Activity

Si necesitas confirmar si un espacio de trabajo está enviando iOS Live Activities, puedes utilizar los siguientes métodos:

Registro de actividad de mensajes

Ve a Configuración > Registro de actividad de mensajes y filtra por errores de Live Activity para ver cualquier resultado de entrega relacionado con Live Activity durante el periodo de tiempo esperado. Para más información, consulta Registro de actividad de mensajes.

Query Builder, Currents o Snowflake Data Sharing

Busca los siguientes eventos de Live Activity para verificar el ciclo de vida y la entrega de Live Activity:

• Live Activity Send: Se registra cada vez que Braze inicia, actualiza o finaliza una Live Activity.
• Live Activity Outcome: Estado final de entrega a APN para cada Live Activity enviada.

Opcionalmente, también puedes comprobar las señales de disponibilidad de tokens:

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

Panel de uso de API

Ve a Configuración > APIs and Identifiers > Dashboard, selecciona Filters y filtra por Endpoint para ver las respuestas de la API. Por ejemplo, selecciona /messages/live_activity/update (o /messages/live_activity/start) y consulta el volumen de solicitudes de los últimos 30 días. Las respuestas de la API indican que se está llamando a la API y que se están utilizando notificaciones de iOS Live Activity en este espacio de trabajo. Para más información, consulta Panel de uso de API.

Observar eventos de actividad en vivo (opcional)

Importante

No te suscribas directamente a estos flujos de ActivityKit con Apple, ya que entrará en conflicto con las suscripciones de Braze e impedirá que las actividades en vivo funcionen correctamente:

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

En su lugar, utiliza las suscripciones que se mencionan en esta sección.

El SDK de Braze proporciona dos métodos de suscripción en braze.liveActivities para observar el ciclo de vida completo de las actividades en vivo. Para un tutorial paso a paso completo, consulta el tutorial de actividades en vivo.

• subscribeToStateUpdates(_:): Entrega eventos del ciclo de vida tanto para el registro de tokens push-to-start como para las instancias de actividad en ejecución.
• subscribeToErrors(_:): Entrega errores del SDK y del lado del servidor encontrados durante el seguimiento de actividades en vivo.

Nota

Ambos métodos devuelven un Braze.Cancellable. La suscripción permanece activa mientras el valor devuelto se mantenga a través de una referencia fuerte (por ejemplo, almacénalo en una propiedad con el mismo ciclo de vida que tu instancia de Braze).

Configurar suscripciones

Configura las suscripciones una vez en application(_:didFinishLaunchingWithOptions:) y mantenlas durante toda la vida de tu aplicación:

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

Las devoluciones de llamada solo se activan para eventos futuros de actividad en vivo; no reproducen el estado actual en el momento de la suscripción. Para consultar la instantánea del estado actual, utiliza Activity<T>.activities.

subscribeToStateUpdates

subscribeToStateUpdates(_:) entrega valores UpdateEvent que cubren el ciclo de vida completo de las actividades en vivo. Los eventos se dividen en dos ámbitos:

• .activityType(ActivityType): Eventos a nivel de tipo para el registro de tokens push-to-start (iOS 17.2+). Aún no existe ninguna instancia de actividad.
• .activityInstance(ActivityInstance): Eventos a nivel de instancia para una actividad en ejecución específica.

Se admiten múltiples suscriptores: cada suscripción activa recibe cada emisión de forma independiente.

Eventos a nivel de tipo

Eventos a nivel de instancia

Ejemplo

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 utilizando los mismos dos ámbitos que UpdateEvent:

• .activityType(ActivityType): Errores a nivel de tipo para fallos en el registro push-to-start.
• .activityInstance(ActivityInstance): Errores a nivel de instancia para una actividad en ejecución.

Utiliza la bandera isTransient para determinar si es apropiado reintentar. El SDK reintenta automáticamente los fallos transitorios.

Errores a nivel de tipo

Errores a nivel de instancia

Ejemplo

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

Manejar actualizaciones del estado del contenido (opcional)

Si deseas utilizar el estado del contenido de la instancia real de la actividad en vivo, sigue esta sección.

Cuando se activa un evento .contentUpdated, utiliza lógica personalizada para buscar la Activity<T> en ejecución por su ID desde Activity.activities y luego accede al ContentState tipado a través 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últiples tipos de atributos

Si tu aplicación utiliza múltiples tipos de ActivityAttributes, comprueba la cadena type para buscar la Activity<T> apropiada:

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.name,
        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.name,
        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 })
}

Preguntas más frecuentes (FAQ)

Funcionalidad y soporte

¿Qué plataformas admiten actividades en vivo?

Actualmente, las actividades en vivo son una característica específica de iOS y iPadOS. De forma predeterminada, las actividades iniciadas en un iPhone o iPad se muestran adicionalmente en cualquier dispositivo watchOS 11+ o macOS 26+ emparejado.

Braze no ofrece actualmente soporte nativo de actividades en vivo en Android. Para Android, puedes crear experiencias de actualización en vivo a través de notificaciones push de Braze y renderizado de notificaciones personalizadas.

El artículo de actividades en vivo cubre los requisitos previos para gestionar actividades en vivo a través del SDK Swift de Braze.

¿Son compatibles las aplicaciones React Native con las actividades en vivo?

Sí, a partir de la versión 3.0.0+ del SDK de React Native se admiten actividades en vivo a través del SDK Swift de Braze. Es decir, tienes que escribir código iOS de React Native directamente sobre el SDK Swift de Braze.

No existe una API de conveniencia JavaScript específica de React Native para las actividades en vivo porque las características de las actividades en vivo proporcionadas por Apple utilizan lenguajes intraducibles en JavaScript (por ejemplo, concurrencia Swift, genéricos, SwiftUI).

¿Admite Braze actividades en vivo como Campaign o paso en Canvas?

No, actualmente no es posible.

Notificaciones push y actividades en vivo

¿Qué ocurre si se envía una notificación push mientras está activa una actividad en vivo?

Las actividades en vivo y las notificaciones push ocupan un espacio de pantalla diferente y no entrarán en conflicto en la pantalla del usuario.

Si las actividades en vivo aprovechan la funcionalidad de los mensajes push, ¿es necesario habilitar las notificaciones push para recibir actividades en vivo?

Aunque las actividades en vivo se basan en notificaciones push para las actualizaciones, están controladas por diferentes configuraciones de usuario. Un usuario puede optar por las actividades en vivo pero no por las notificaciones push, y viceversa.

Los tokens de actualización de actividad en vivo caducan a las ocho horas.

¿Las actividades en vivo requieren push primers?

Los push primers son una buena práctica para pedir a tus usuarios que acepten las notificaciones push de tu aplicación. Sin embargo, no hay ninguna indicación del sistema para participar en las actividades en vivo. Por defecto, los usuarios están incluidos en las actividades en vivo para una aplicación individual cuando instalan esa aplicación en iOS 16.1 o posterior. Este permiso puede habilitarse o deshabilitarse en la configuración del dispositivo para cada aplicación.

Temas técnicos y solución de problemas

¿Cómo sé si las actividades en vivo tienen errores?

Cualquier error de actividad en vivo se registra en el panel de Braze, en el Registro de actividad de mensajes, donde puedes filtrar por “LiveActivity Errors”.

Después de enviar una notificación push-to-start, ¿por qué no he recibido mi actividad en vivo?

En primer lugar, comprueba que tu carga útil incluye todos los campos obligatorios descritos en el endpoint messages/live_activity/start. Los campos activity_attributes y content_state deben coincidir con las propiedades definidas en el código de tu proyecto. Si estás seguro de que la carga útil es correcta, es posible que APN te esté aplicando un límite de velocidad. Este límite lo impone Apple y no Braze.

Para verificar que tu notificación push-to-start ha llegado correctamente al dispositivo pero no se ha mostrado debido a los límites de velocidad, puedes depurar tu proyecto utilizando la aplicación Consola de tu Mac. Adjunta el proceso de grabación del dispositivo que desees y, a continuación, filtra los registros por process:liveactivitiesd en la barra de búsqueda.

Después de iniciar mi actividad en vivo con push-to-start, ¿por qué no recibe nuevas actualizaciones?

Comprueba que has seguido correctamente las instrucciones del Paso 2.2: Añadir el protocolo BrazeLiveActivityAttributes. Tu ActivityAttributes debe contener tanto la conformidad con el protocolo BrazeLiveActivityAttributes como la propiedad brazeActivityId.

Después de recibir una notificación push-to-start de actividad en vivo, comprueba que puedes ver una solicitud de red saliente al endpoint /push_token_tag de tu URL de Braze y que contiene el ID de actividad correcto en el campo "tag".

Por último, asegúrate de que el tipo de atributo de actividad en vivo en tu carga útil de actualización coincida exactamente con la cadena y la clase utilizadas en tu llamada al método del SDK registerPushToStart. Utiliza constantes para evitar errores tipográficos.

Recibo una respuesta de acceso denegado cuando intento utilizar el endpoint live_activity/update. ¿Por qué?

Las claves de API que utilices deben tener los permisos correctos para acceder a los distintos endpoints de la API de Braze. Si estás utilizando una clave de API que creaste anteriormente, es posible que hayas olvidado actualizar sus permisos. Lee nuestro resumen de seguridad de la clave de API para refrescarte la memoria.

¿Comparte el endpoint messages/send límites de velocidad con el endpoint messages/live_activity/update?

De manera predeterminada, el límite de velocidad para el endpoint messages/live_activity/update es de 250 000 solicitudes por hora, por espacio de trabajo y a través de múltiples endpoints. Para más información, consulta los límites de velocidad de la API.