Live Activity

Una Live Activity es una tarjeta que se actualiza en tiempo real para que el usuario vea el progreso sin abrir la app (estado de vuelo, entrega, viaje y similares). En iOS es una pequeña tarjeta en la pantalla de bloqueo y en Dynamic Island. En Android 16 y versiones posteriores, es el mismo tipo de tarjeta, mostrada como una notificación persistente con una barra de progreso.

Use el elemento Live Activity en un journey para iniciar, actualizar o finalizar esa tarjeta en iOS, Android o ambos.

Cada elemento realiza una acción:

• Start: crear la tarjeta.
• Update: cambiar una tarjeta existente.
• End: cerrar la tarjeta.

Para cambiar o cerrar la misma tarjeta más tarde, agregue otro elemento Live Activity y apúntelo de vuelta al que creó la tarjeta con Card created by.

Ejemplos de casos de uso

Use este elemento siempre que el usuario deba ver un estado que sigue cambiando, sin abrir la app.

• Estado de vuelo: muestre la tarjeta después del check-in. Mantenga actualizados la puerta, el estado y el horario durante el vuelo. Elimine la tarjeta después del aterrizaje.
• Entrega de comida: muestre la tarjeta cuando se realiza el pedido. Mantenga actualizados el nombre del repartidor, el tiempo estimado y la distancia en el camino. Elimine la tarjeta al entregar.
• Solicitud de viaje: muestre la tarjeta cuando se solicita el viaje. Mantenga actualizados el conductor, el tiempo estimado y la matrícula mientras el conductor se acerca. Elimine la tarjeta cuando el viaje finaliza.
• Pedido o cita: muestre la tarjeta cuando se confirma el pedido o la reserva. Mantenga el estado actualizado a medida que avanza. Elimine la tarjeta cuando se completa o la visita termina.
• Evento en vivo: muestre la tarjeta cuando comienza el evento. Mantenga actualizados el marcador, el período o el horario mientras transcurre. Elimine la tarjeta cuando finaliza el evento.

Consejo

Para journeys completos, vea Cómo mostrar el estado de un vuelo en la pantalla de bloqueo y Cómo mostrar el progreso de una entrega en la pantalla de bloqueo.

Requisitos previos

Antes de configurar este elemento, compruebe lo que necesita cada plataforma.

Para la tarjeta de iOS:

• Soporte de iOS Live Activity: su app debe admitir Live Activities. Vea la guía de Live Activities del iOS SDK.
• Un esquema de widget publicado: pida a su equipo de desarrollo que publique el esquema que coincide con el tipo de Live Activity en la app en Applications → Configure → Live Activity schemas. También pueden publicarlo a través de la API. Para saber qué pertenece a un esquema, vea Cómo escribir un esquema.
• Widget en la lista: después de publicar el esquema, selecciónelo en Widget en este elemento. Si la lista Widget está vacía, el esquema aún no está publicado.

Para la notificación de Android:

• Soporte de Android Live Updates: su app necesita el SDK 6.11+ y el módulo pushwoosh-liveupdates. Android no necesita ningún esquema. Pida a su desarrollador de Android que confirme que el módulo está incluido en la compilación.

Configurar el elemento

1. Arrastre el elemento Live Activity al lienzo.

   

2. Haga doble clic en el elemento para abrir sus ajustes.

3. Ingrese un nombre en Step name.

4. En Action, elija una de las siguientes opciones:

   • Start: crear la tarjeta de Live Activity.
   • Update: cambiar el contenido de una tarjeta existente.
   • End: cerrar la tarjeta.

5. En Platforms, active iOS Live Activity, Android Live Updates o ambas. Al menos una plataforma debe permanecer activada, por lo que no puede desactivar la última. En Update y End, Platforms muestra las plataformas del elemento Start vinculado y es de solo lectura.

   

6. Solo en Start, establezca la clave de la tarjeta para que los pasos posteriores de Update y End puedan encontrar esta tarjeta:

   • En Card key: event, seleccione el evento que identifica la tarjeta (por ejemplo, el evento de entrada al journey).
   • En Card key: attribute, seleccione el atributo que hace que la clave sea única por viajero. Esto es obligatorio una vez que establece Card key: event. Dejarlo sin establecer hace que la selección del evento no tenga efecto, igual que dejar ambos campos vacíos: una tarjeta por viajero, direccionada por el ID de usuario predeterminado.

   

Vincular Update y End a la tarjeta correcta

Cuando Action es Update o End, use Card created by para apuntar al elemento Start exacto que creó esta tarjeta. De lo contrario, Update o End no la alcanzarán.

1. En Card created by, seleccione el Step name de ese elemento Start (por ejemplo, Order card start).

Después de elegir Card created by, Card key (from the start element) muestra los valores de Card key: event y Card key: attribute de ese Start. Es de solo lectura y confirma a qué tarjeta apunta esto.

Nota

Ejemplo: Start se llama Order card start. En Update y End, elija Order card start en Card created by. Ambos pasos entonces cambian o cierran esa misma tarjeta de pedido.

Elegir el idioma de la tarjeta

Card language se aplica tanto a la tarjeta de iOS como a la notificación de Android.

Establezca Card language en default o un código de idioma específico. El contenido bajo default es el respaldo para cualquier idioma que no complete por separado.

Configurar la tarjeta de iOS

Omita esta sección si solo está activado Android Live Updates.

Elegir el widget y la versión del esquema

1. En Widget, seleccione el tipo de Live Activity publicado para esta tarjeta. Los campos de contenido de abajo provienen de esa elección. En Update o End, Widget es de solo lectura, heredado del elemento Card created by.

2. En Schema version, seleccione qué versión publicada del esquema de ese widget usar. Los campos de Card content provienen de esta versión. En Update y End, Schema version sigue siendo un selector: puede elegir una versión publicada diferente del mismo widget heredado a la que usó el Start vinculado.

   

Establecer los atributos fijos de la tarjeta (solo Start)

En Start, bajo Card attributes, agregue los campos que permanecen fijos durante toda la vida de la tarjeta, establecidos una vez y nunca cambiados de nuevo, como un número de vuelo o un ID de pedido. Estos son independientes de los campos de Card content de abajo. Esos valores pueden cambiar en Update.

Pida a su desarrollador de iOS la lista exacta de Field name. Esos nombres permanecen fijos durante toda la vida de la tarjeta (el tipo ActivityAttributes de la app). No use los nombres cambiantes de Card content (el ContentState de la app).

1. Haga clic en Add attribute.
2. Establezca Field name y Value para cada atributo que necesite.

Update y End no establecen atributos. Lo que Start haya establecido para esta tarjeta permanece fijo.

Precaución

Los atributos de la tarjeta se envían exactamente como espera el tipo ActivityAttributes de su app, campo por campo. Si se equivoca en un nombre, o los deja vacíos, el decodificador del dispositivo rechaza todo el payload. En una prueba real, un Start con flightNumber abrió la tarjeta, y un Start sin atributos entregó solo el sobre, sin nada que mostrar en la pantalla de bloqueo.

Completar el contenido de la tarjeta

En Card content, escriba un valor literal o un marcador de posición de personalización en cada campo. Aparece un campo por cada propiedad en la versión de esquema seleccionada.

Precompletado en Update y End

En Update o End, si Card content para el Card language actual está vacío (incluido un idioma que acaba de agregar), Pushwoosh precompleta los campos desde el elemento Start vinculado cuando abre los ajustes:

• El mismo idioma que Start, si ese idioma tiene contenido.
• De lo contrario, el contenido default de Start.
• Si Start no tiene ninguno de los dos, deje los campos vacíos y complételos usted mismo.

Los valores precompletados siguen siendo editables. Haga clic en Apply solo cuando quiera conservar las ediciones. Abrir el elemento por sí solo no cambia un journey en ejecución.

Los campos que deje vacíos en Update o End no se envían. Lo que la tarjeta muestre entonces en esos campos depende de su app: puede conservar el valor anterior, borrarlo o hacer otra cosa. Pregunte a sus desarrolladores cómo lo maneja su app.

En End, Card content es opcional. Un campo que complete se convierte en el último valor mostrado antes de que la tarjeta se cierre.

Establecer la prioridad y el momento de entrega

1. En Delivery priority, elija cuándo debe entregar iOS esta actualización:

   • Immediate: iOS la entrega de inmediato y puede despertar el teléfono (y reproducir el sonido, si estableció uno).
   • Quiet: iOS puede entregarla más tarde junto con otras actualizaciones y no despierta el teléfono de inmediato.
   • Default (batched): iOS usa su propia entrega por lotes predeterminada y no despierta el teléfono de inmediato.

2. En Sound, seleccione un sonido de la lista. Su equipo de desarrollo agrega archivos de sonido al paquete de la app de iOS. Vea Sonido push personalizado. El sonido solo se reproduce junto con Alert title o Alert text, igual que el banner.

3. Dependiendo de la Action que establezca para este elemento (Start, Update o End), complete una de las siguientes opciones:

   • Start o Update: establezca Stale after, min con cuántos minutos deben verse frescos los datos de la tarjeta. Cuando ese tiempo termina, iOS atenúa los números como desactualizados. La tarjeta permanece en la pantalla de bloqueo. Para que los números sigan viéndose actuales, envíe otro Update antes de que el tiempo termine.
   • End: establezca Dismiss after, min con cuánto tiempo permanece la tarjeta cerrada en la pantalla de bloqueo antes de que iOS la elimine. Déjelo en 0 y la tarjeta seguirá mostrando su Card content final hasta que iOS la retire por su cuenta, en hasta 4 horas.

4. Opcionalmente, establezca Relevance score con un número de 1 a 100. Cuando una persona tiene más de una Live Activity activa de su app a la vez, iOS muestra primero la que tiene la puntuación más alta. Déjelo en 0 para no establecer una preferencia. Pushwoosh no envía en absoluto una puntuación 0 a Apple. Vea Múltiples actividades por dispositivo para el panorama completo.

Completar la notificación de Android

Complete el título, el texto, la barra de progreso y la hora del encabezado de la notificación de Android. Esta sección solo aparece cuando Android Live Updates está activado. Usa el mismo Card language que la tarjeta de iOS.

1. Establezca Notification title para cada idioma que complete para Android. En Start y Update, el journey no puede ejecutarse hasta que cada uno de esos idiomas tenga un título. Un idioma sin título muestra un recordatorio en el formulario.

2. Establezca Notification text.

   

3. Configure la barra de progreso:

   • Progress: escriba un número o un marcador de posición con la forma {name} (opcionalmente {name|format} o {name|format|default}) para indicar dónde debe situarse la barra, en las mismas unidades que las longitudes de los segmentos.
   • Segments: haga clic en Add segment por cada tramo de color de la barra y establezca un Color hexadecimal (#RRGGBB o #AARRGGBB) y una Length para cada uno. Las longitudes de los segmentos suman la barra completa.
   • Animate the bar without a known end: actívelo para mostrar una barra en movimiento en lugar del valor de Progress.
   • Hide the progress bar: actívelo para mostrar la tarjeta sin barra.

   

4. Configure la hora del encabezado:

   • Header time: escriba una marca de tiempo Unix en segundos (no en milisegundos), o un marcador de posición, para el momento que debe mostrar el reloj del encabezado de la tarjeta. Por ejemplo, 1735689600 significa 2025-01-01 00:00 UTC. Si se establecen tanto este campo como Header time after, min, se usa Header time.
   • Header time after, min: establezca cuántos minutos después del envío debe mostrarse la hora del encabezado.
   • Run the header time as a timer: actívelo para mostrar Header time como un reloj en marcha en lugar de un valor fijo. Esto muestra Count down to the header time.
   • Count down to the header time: actívelo para contar hacia atrás hasta Header time en lugar de contar hacia adelante desde el envío.
   • Hide the header time: actívelo para mostrar la tarjeta sin la hora del encabezado.

   

Cualquiera de los campos anteriores puede contener un marcador de posición, que se resuelve de la misma forma que los campos de Card content de iOS: desde el evento del journey o personalizado con un atributo de evento.

Algunos dispositivos Android no mostrarán la notificación

• Android 15 o anterior, o una app sin el módulo pushwoosh-liveupdates: Pushwoosh sigue enviando la actualización, pero no aparece nada en el dispositivo y tampoco se muestra un push normal en su lugar.
• Dispositivos Huawei y Baidu: no reciben Android Live Updates. Las actualizaciones solo llegan a los dispositivos registrados a través de Firebase Cloud Messaging (FCM).

Tocar la notificación abre la app, igual que un push normal.

Establecer el banner de alerta

Esta sección solo se aplica cuando iOS Live Activity está activado. Si solo está activado Android Live Updates, estos campos se ocultan y no se envía nada.

Para las tres acciones (Start, Update y End):

1. En Alert title, establezca el título del banner mostrado en la pantalla de bloqueo.
2. En Alert text, establezca el texto del banner.

Precaución

Si tanto Alert title como Alert text están vacíos, la tarjeta igual inicia, se actualiza o finaliza, pero la pantalla de bloqueo no muestra ningún banner ni reproduce ningún sonido. Complete al menos uno de los dos cuando esta acción deba aparecer en una pantalla bloqueada.

Elegir qué dispositivo recibe la tarjeta

El direccionamiento se establece una vez, en Start. Deje ambos interruptores apagados para enviar la tarjeta al dispositivo en el que el viajero entró al journey. Activar uno de los interruptores desactiva el otro:

• Send to all devices of this user: enviar a todos los dispositivos registrados bajo el User ID de ese viajero, no solo al que usó para entrar.
• Send to the last active device only: enviar al único dispositivo que ese User ID usó más recientemente, en lugar de a todos los dispositivos o al dispositivo de entrada.

Consejo

Active Send to the last active device only cuando la misma persona pueda estar viendo desde un iPhone diferente al que usó para entrar al journey.

En Update y End, revise Delivery (from the start element). Nombra el modo de direccionamiento del Start vinculado. La actualización solo puede llegar a la misma tarjeta, así que se envía de la misma manera.

Nota

Ambos interruptores se bloquean tan pronto como el journey comienza a ejecutarse, también en Start. Para cambiar el direccionamiento después de eso, pause primero el journey.

Personalizar el contenido

Use esto cuando los marcadores de posición en Alert title, Alert text, Card content o, en Android, Notification title, Notification text, Progress o Header time deban tomar valores del evento del journey o de la entrada basada en API en lugar de las etiquetas del dispositivo.

1. Bajo Overwrite personalization, active Personalise message with event attributes.
2. Marque la casilla Overwrite placeholder junto a cada marcador de posición que quiera reasignar.
3. Asigne ese marcador de posición a un atributo de evento.

Guardar el elemento

Haga clic en Apply para guardar los ajustes del elemento. Apply guarda este elemento en el journey. No confirma que la tarjeta haya aparecido en el dispositivo. Después de que el journey esté en ejecución, revise Total entries y las bajas en este paso, y verifique la tarjeta en un iPhone de prueba, en un dispositivo de prueba con Android 16 o posterior, o en ambos, según las plataformas que haya activado.

Limitaciones

• Estadísticas del elemento: en este paso, revise Total entries, la fila Delivery (modo de direccionamiento) y las bajas (No recipient for the card, Live Activity send failed). Use No recipient for the card para ver que la mensajería no encontró ningún dispositivo para las plataformas activadas en ese modo, no que el dispositivo carecía de un token de Live Activity. Este paso no informa si el dispositivo mostró la tarjeta o si el usuario la abrió.
• El sonido no está garantizado en cada actualización: iOS limita por sí mismo la frecuencia de las alertas de Live Activity. Una actualización idéntica puede reproducir un sonido una vez y llegar en silencio la siguiente.
• Muchas acciones Start seguidas durante las pruebas: si envía alrededor de diez acciones Start para la misma persona en poco tiempo (por ejemplo, mientras prueba el journey), Apple puede dejar de mostrar tarjetas nuevas y no devolver un error. En el journey, la persona aún puede parecer entregada. Deje un intervalo entre las ejecuciones de prueba.