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 ofrezca 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 hasta la entrega” dinámico que se actualiza a medida que el repartidor se acerca a su destino.

Como desarrollador, puedes usar Braze para administrar los ciclos de vida de tus actividades en vivo, hacer llamadas a la REST API de Braze para actualizar las actividades en vivo y conseguir que todos los dispositivos suscritos reciban la actualización lo antes posible. Además, como administras 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 Actividad en vivo

Requisitos previos

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

• Asegúrate de que tu proyecto está dirigido a iOS 16.1 o posterior.
• Añade el derecho Push Notification en Signing & Capabilities en tu proyecto de Xcode.
• Asegúrate de que se utilizan claves .p8 para enviar notificaciones. No se admiten archivos más antiguos como .p12 o .pem.
• A partir de la versión 8.2.0 del SDK de Swift de Braze, puedes registrar una Actividad en vivo de forma remota. Para utilizar esta característica, se necesita iOS 17.2 o posterior.

Nota

Aunque las Actividades en vivo y las notificaciones push son similares, sus permisos del sistema son independientes. De forma predeterminada, todas las características de las Actividades en vivo están habilitadas, pero los usuarios pueden desactivar esta característica para cada aplicación.

Paso 1: Crear una actividad

En primer lugar, asegúrate de haber seguido la guía Displaying live data with Live Activities de la documentación de Apple para configurar las Actividades en vivo en tu aplicación de iOS. Como parte de esta tarea, asegúrate de incluir NSSupportsLiveActivities con el valor YES en tu Info.plist.

Como la naturaleza exacta de tu Actividad en vivo depende 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 Actividad en vivo.
• ActivityAttributes.ContentState: Este tipo define los datos dinámicos que se actualizan a lo largo de la actividad.

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

Familiarízate con los requisitos previos y limitaciones de Apple para las Actividades en vivo, ya que estas restricciones son independientes de Braze.

Nota

Si esperas enviar notificaciones push frecuentes a la misma Actividad en vivo, puedes evitar que Apple te limite por su presupuesto de envíos configurando NSSupportsLiveActivitiesFrequentUpdates con el valor YES en tu archivo Info.plist. Para más información, consulta la sección Determine the update frequency en la documentación de ActivityKit.

Ejemplo

Imaginemos que queremos crear una Actividad en vivo para ofrecer a nuestros usuarios actualizaciones del espectáculo Superb Owl, en el que dos centros de rescate de fauna salvaje compiten y reciben puntos por los búhos que tienen acogidos. Para este ejemplo, hemos creado una estructura llamada SportsActivityAttributes, pero puedes utilizar 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

En primer lugar, elige cómo quieres registrar tu actividad:

• Remoto: Utiliza el método registerPushToStart al principio del ciclo de vida del usuario y antes de que se necesite el token push-to-start; después, inicia una actividad con el endpoint /messages/live_activity/start.
• Local: Crea una instancia de tu Actividad en vivo y, a continuación, utiliza el método launchActivity para crear tokens de notificaciones push que Braze gestionará.

• remote
• local

Importante

Para registrar una Actividad en vivo de forma remota, se necesita 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 y, a continuación, General. En Frameworks and Libraries, confirma que aparece BrazeKit.

Paso 2.2: Añadir el protocolo BrazeLiveActivityAttributes

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

Importante

iOS mapea la propiedad brazeActivityId al campo correspondiente de la carga útil push-to-start de tu Actividad en vivo, por lo que no debes cambiarle el nombre ni asignarle 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 Actividad en vivo para que Braze pueda hacer un seguimiento de todos los tokens push-to-start y de las instancias de Actividades en vivo asociadas a 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 un dispositivo. Para asegurarte de que tus tokens se registran de forma fiable, llama a registerPushToStart en tu método didFinishLaunchingWithOptions.

Ejemplo

En el siguiente ejemplo, la clase LiveActivityManager gestiona los objetos de Actividad en vivo. Después, 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 con el endpoint /messages/live_activity/start.

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

1. Crea una instancia de tu implementación de Actividad en vivo utilizando las API de ActivityKit de Apple.
2. Establece el parámetro pushType como .token.
3. Pasa los ActivitiesAttributes y el ContentState de las Actividades en vivo que hayas definido.
4. Registra tu actividad en tu instancia de Braze pasándola a launchActivity(pushTokenTag:activity:). El parámetro pushTokenTag es una cadena personalizada que defines tú. Debe ser única para cada Actividad en vivo que crees.

Después de registrar la Actividad en vivo, el SDK de Braze extrae y observa los cambios en los tokens de notificaciones push.

Ejemplo

Para nuestro ejemplo, crea una clase llamada LiveActivityManager como interfaz para nuestros objetos de Actividad en vivo. Después, establece pushTokenTag en "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 Actividad en vivo muestra este contenido inicial a tus usuarios.

Paso 3: Reanudar el seguimiento de la actividad

Para asegurarte de que Braze hace un seguimiento de tu Actividad en vivo 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 de seguimiento de las actualizaciones de los tokens de notificaciones push de todas las Actividades en vivo activas. Ten en cuenta que, si un usuario ha descartado explícitamente la Actividad en vivo en su dispositivo, se considera eliminada y Braze deja de hacerle seguimiento.

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 Actividad en vivo mediante notificaciones push enviadas a través de la REST API de Braze. Utiliza este endpoint para actualizar el ContentState de tu Actividad en vivo.

Importante

Cuando llames a /messages/live_activity/start y después envíes la primera solicitud a /messages/live_activity/update para el mismo activity_id, espera al menos 5 minutos entre solicitudes. Este retraso da tiempo a Braze y a APN para registrar la nueva Actividad en vivo y el mapeado de su token. Si envías la primera actualización demasiado pronto, es posible que esa actualización no se aplique a la actividad.

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

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

Paso 5: Finalizar la actividad

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

Para mejorar la fiabilidad al finalizar una Actividad en vivo, sigue estos pasos opcionales:

1. Si quieres, incluye dismissal_date en esa misma solicitud update para sugerir cuándo debe iOS eliminar la interfaz de usuario de la Actividad en vivo.
2. Verifica los resultados de la entrega en el Registro de actividad de mensajes.

Programar el descarte automático

Para programar el descarte automático, programa una solicitud de seguimiento al endpoint de actualización después de iniciar la Actividad en vivo.

1. Envía una solicitud /messages/live_activity/start con un activity_id del que puedas hacer seguimiento.
2. Almacena ese activity_id y tu hora de finalización prevista en el programador de tu backend.
3. A la hora de finalización prevista, 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 iOS controla el momento del descarte. Incluso después de enviar una solicitud de finalización válida, la eliminación de la pantalla de bloqueo o de la Dynamic Island puede retrasarse o comportarse de forma diferente según las condiciones del sistema operativo.

Una Actividad en vivo también puede finalizar fuera de Braze:

• Descarte del usuario: Un usuario puede descartar manualmente una Actividad en vivo.
• Tiempo de espera: Tras un tiempo predeterminado de ocho horas, iOS elimina la Actividad en vivo de la Dynamic Island del usuario. Tras un tiempo predeterminado de 12 horas, iOS elimina la Actividad en vivo de la pantalla de bloqueo del usuario.

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

Seguimiento de Live Activities

Los eventos de Live Activity están disponibles en Currents, en el uso compartido de datos de Snowflake y en el generador de consultas. Los siguientes eventos pueden ayudarte a comprender y supervisar el ciclo de vida de tus Live Activities, hacer un seguimiento de la disponibilidad de tokens y diagnosticar problemas o verificar estados de entrega de forma independiente.

• Cambio de token de inicio por push de Live Activity: Registra cuándo se añade o actualiza un token de inicio por push (PTS) en Braze, lo que te permite hacer un seguimiento de los registros y la disponibilidad de tokens por usuario.
• Cambio de token de actualización de Live Activity: Hace un seguimiento de cuándo se añaden, actualizan o eliminan 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 final de entrega al servicio de notificaciones push de Apple (APN) para cada Live Activity enviada desde Braze.

Verificar envíos de Live Activities

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

Registro de actividad de mensajes

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

Generador de consultas, Currents o Snowflake Data Sharing

Comprueba los siguientes eventos de Live Activities para verificar su ciclo de vida y su entrega:

• 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 la API

Ve a Configuración > API e identificadores > Panel, selecciona Filtros 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 usando notificaciones de Live Activities de iOS en este espacio de trabajo. Para más información, consulta Panel de uso de la API.

Observar eventos de actividades 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. De forma predeterminada, 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 deshabilitarse o volver a habilitarse 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.