API de Live Activities de iOS

Documentación de Apple:

• Acerca de las Live Activities
• Actualizar y finalizar Live Activities con notificaciones push de ActivityKit

Para permitir que un punto de Live Activity de Customer Journey construya su formulario de estado de contenido a partir de nombres de campo en lugar de un editor JSON sin formato, publica un esquema para tu attributes-type — consulta la API de Esquemas de Live Activity.

startLiveActivity

POST https://api.pushwoosh.com/json/1.3/startLiveActivity

Permite crear Live Activities de iOS.

Cuerpo de la solicitud

Parámetro	Tipo	Requerido/Opcional	Descripción
application	String	Requerido	Código de aplicación de Pushwoosh
auth	String	Requerido	Token de acceso a la API desde el Panel de Control de Pushwoosh.
notifications	Array	Requerido	Array JSON de parámetros de mensaje. Consulta los detalles en la tabla de Notificaciones a continuación.

Notificaciones

Parámetros utilizados en el array notifications:

Parámetro	Tipo	Requerido/Opcional	Descripción
content	String	Requerido*	Cuerpo de la alerta para el push que inicia la Live Activity, y el texto de respaldo que se muestra en dispositivos con versiones de iOS inferiores a la 16.1.
title	String	Requerido*	Título de la alerta para el push que inicia la Live Activity.
live_activity	Object	Requerido	Datos de la Live Activity para crear la Live Activity en iOS.
live_activity.content-state	Object	Requerido	Contenido para la notificación de la Live Activity.
live_activity.attributes-type	String	Requerido	El tipo de atributos utilizados en la Live Activity.
live_activity.attributes	Object	Requerido	Atributos para la Live Activity.
live_activity_id	String	Requerido	Un identificador único para la Live Activity. Se utiliza para apuntar a esta actividad al llamar a updateLiveActivity. Debe ser único por sesión de actividad.
filter	String	Opcional	El nombre de un filtro (segmento) de Pushwoosh. Consulta Nombre de Segmento / Filtro. La Live Activity se iniciará en todos los dispositivos que coincidan con este filtro.
devices	Array de Strings	Opcional	Una lista de tokens de dispositivo. La Live Activity se iniciará solo en los dispositivos especificados.
send_date	String	Opcional	Programa el push que inicia la Live Activity para una fecha y hora específicas — funciona con la segmentación por filter o devices. Usa el formato YYYY-MM-DD HH:mm, o now para iniciar inmediatamente (este también es el valor predeterminado cuando se omite el parámetro). No debe ser más de 1 día en el pasado o 30 días en el futuro, de lo contrario, la solicitud se rechaza con un error de validación.
timezone	String	Opcional	La zona horaria utilizada para interpretar send_date. Si se omite, send_date se interpreta en UTC.
apns_priority	Integer	Opcional	Controla la prioridad de entrega de APNs para este push de Live Activity. Acepta 10 (alta prioridad, entregado con la cabecera apns-priority: 10 para una representación instantánea en una pantalla bloqueada) o 5 (baja prioridad, entregado con apns-priority: 5 para conservar la batería del dispositivo). Cualquier otro valor se trata como 5, sin error de validación. Cada push de Live Activity tiene por defecto la prioridad 5, independientemente de si lleva contenido de alerta (content/title) — establece apns_priority: 10 explícitamente para solicitar una entrega de alta prioridad. Consulta Push Sensible al Tiempo y prioridad de entrega a continuación.

Nota: * Al menos uno de content o title no debe estar vacío. Pushwoosh rechaza una solicitud de inicio si ambos están vacíos.

Precaución

El inicio remoto de una Live Activity a través de startLiveActivity requiere iOS 17.2+ en el dispositivo — las versiones anteriores no son compatibles con la API pushToStartTokenUpdates en la que se basa este endpoint. Consulta Iniciar Live Activity con una notificación push remota.

Cuando se apunta a un filter (segmento), la hora de envío programada es cuando Pushwoosh comienza a despachar el push, no un instante de entrega garantizado — para audiencias grandes, la entrega a dispositivos individuales puede retrasarse unos minutos con respecto a send_date, ya que la tasa de envío para los pushes de Live Activity no se puede personalizar con send_rate.

Las llamadas repetidas de push-to-start se agotan silenciosamente. Después de aproximadamente diez inicios en rápida sucesión, Apple deja de entregar la notificación push-to-start subyacente sin ningún error, y startLiveActivity sigue devolviendo 200. Durante las pruebas de campaña, esto parece como si “la API funciona pero no sucede nada en el dispositivo”. Espacia los inicios de prueba consecutivos.

Ejemplo de solicitud

Con filtro

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1"
      }
    ]
  }
}

Con dispositivos

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "SECOND_LIVE_ACTIVITY",
        "devices": ["first_third", "second_device"]
      }
    ]
  }
}

Inicio programado

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "THIRD_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1",
        "send_date": "2026-06-16 16:00"
      }
    ]
  }
}

Ejemplo de respuesta

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Nota:

Lee este artículo para aprender más sobre cómo trabajar con Live Activities usando el SDK de Pushwoosh para iOS.

updateLiveActivity

POST https://api.pushwoosh.com/json/1.3/updateLiveActivity

Permite actualizar y finalizar Live Activities de iOS

Cuerpo de la solicitud

Parámetro	Tipo	Requerido/Opcional	Descripción
auth	String	Requerido	Token de acceso a la API desde el Panel de Control de Pushwoosh.
application	String	Requerido	Código de aplicación de Pushwoosh
notifications	Array	Requerido	Array JSON de parámetros de mensaje. Consulta los detalles en la tabla de Notificaciones a continuación.

Notificaciones

Parámetros utilizados en el array notifications:

Parámetro	Tipo	Requerido/Opcional	Descripción
live_activity	Object	Requerido	Datos de la Live Activity para actualizar la Live Activity en iOS.
live_activity.event	String	Requerido	Especifica el tipo de evento. Usa "update" para actualizar la Live Activity o "end" para cerrarla.
live_activity.content-state	Object	Requerido	Objeto con pares clave-valor utilizado para pasar datos a la Live Activity para actualizar su contenido.
live_activity.dismissal-date	Integer	Opcional	El tiempo (en segundos) en el que la Live Activity debe finalizar. En un end, omite este campo para que la tarjeta siga mostrando su último content-state hasta que iOS la retire por su cuenta — consulta la nota más abajo. Indica una fecha en el pasado para que la tarjeta se elimine en cuanto llegue esta actualización.
live_activity_id	String	Requerido	El identificador único de la Live Activity a actualizar. Debe coincidir con el live_activity_id utilizado en startLiveActivity. La actualización se entregará a todos los dispositivos en los que se inició esta actividad.
live_activity.relevance-score	Integer	Opcional	Indica al sistema iOS qué Live Activity tiene mayor prioridad que otras. Acepta valores de 1 al infinito (se recomiendan valores hasta 100).
live_activity.stale-date	Integer	Opcional	El tiempo (en segundos) que representa la fecha en la que una Live Activity se vuelve obsoleta o caducada.
apns_priority	Integer	Opcional	Controla la prioridad de entrega de APNs para este push de Live Activity. Acepta 10 (alta prioridad, entregado con la cabecera apns-priority: 10 para una representación instantánea en una pantalla bloqueada) o 5 (baja prioridad, entregado con apns-priority: 5 para conservar la batería del dispositivo). Cualquier otro valor se trata como 5, sin error de validación. Cada push de Live Activity tiene por defecto la prioridad 5, independientemente de si lleva contenido de alerta (content/title) — establece apns_priority: 10 explícitamente para solicitar una entrega de alta prioridad. Consulta Push Sensible al Tiempo y prioridad de entrega a continuación.
content	String	Opcional	Cuerpo de la alerta para esta actualización. El caso común es una actualización solo de estado de contenido, que no establece ninguno de los campos content, title o subtitle y no lleva ninguna alerta.
title	String	Opcional	Título de la alerta para esta actualización. Establecer content, title o subtitle activa una alerta y permite que ios_sound se reproduzca. Si no se establece ninguno de los tres, la actualización permanece en silencio, que es el comportamiento predeterminado para las actualizaciones solo de estado de contenido.
subtitle	String	Opcional	Subtítulo de la alerta para esta actualización. Tiene el mismo rol de activación de alerta que content/title arriba.
ios_sound	String	Opcional	Nombre del archivo de sonido en el paquete principal de la aplicación. Se incluye dentro de aps.alert junto con content/title/subtitle, no en el aps.sound de nivel superior, que ActivityKit ignora para las Live Activities, por lo que solo se reproduce cuando esta actualización también establece al menos uno de esos tres. iOS también limita la frecuencia de las alertas de Live Activity por su cuenta. Se ha observado que la misma carga útil llega con sonido en una entrega y sin él en la siguiente, tanto en el dispositivo como en el Simulador.

Nota: relevance-score solo afecta el orden de visualización entre múltiples Live Activities activas en el mismo dispositivo — no afecta la urgencia de la entrega. Usa apns_priority para controlar la urgencia con la que se entrega una actualización.

Nota

Un end sin dismissal-date no elimina la tarjeta. Permanece en la pantalla de bloqueo mostrando el content-state que envió esta actualización, y el propio sistema de Live Activity de Apple la retira por su cuenta en un plazo de hasta 4 horas.

Ejemplo de solicitud

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "title": "Live Activity Update",
        "live_activity": {
          "event": "update",
          "content-state": {
            "status": "second 66",
            "estimatedTime": "66 min",
            "emoji": "👨‍"
          },
          "relevance-score": 60
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY"
      }
    ]
  }
}

Ejemplo de respuesta

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Lee este artículo para aprender más sobre cómo trabajar con Live Activities usando el SDK de Pushwoosh para iOS.

Push Sensible al Tiempo y prioridad de entrega

Por defecto, Apple entrega las actualizaciones de Live Activity con baja prioridad (apns-priority: 5) para conservar la batería. Cuando un dispositivo está bloqueado, una actualización de baja prioridad se procesa en segundo plano y solo se vuelve visible en la Lock Screen una vez que el usuario desbloquea el dispositivo. En un dispositivo ya desbloqueado, se renderiza instantáneamente. Usa el parámetro apns_priority descrito anteriormente para solicitar una entrega de alta prioridad (apns-priority: 10) para que la actualización se renderice en la Lock Screen de inmediato, sin necesidad de desbloquear.

No relacionado con el interruptor de Push Sensible al Tiempo

El interruptor Push Sensible al Tiempo en el Panel de Control de Pushwoosh establece el interruption-level solo para las notificaciones push estándar. No tiene efecto en la prioridad de entrega de Live Activity enviada a través de esta API — las Live Activities utilizan una ruta de entrega separada, controlada exclusivamente por el parámetro de solicitud apns_priority.

Incluso con apns_priority: 10 disponible, Apple limita la frecuencia con la que se puede usar.

Presupuesto de alta prioridad de APNs

Apple limita la cantidad de pushes de alta prioridad (apns-priority: 10) que una aplicación puede enviar por hora. Para actividades que se actualizan con frecuencia (p. ej., resultados en vivo), reserva apns_priority: 10 para eventos críticos y usa apns_priority: 5 o menos actualizaciones para cambios de rutina. Habilitar NSSupportsLiveActivitiesFrequentUpdates en el Info.plist de tu aplicación (consulta la guía del SDK de iOS) aumenta este presupuesto para casos de uso de alta frecuencia.

Múltiples actividades por dispositivo

Puedes iniciar múltiples Live Activities en el mismo dispositivo llamando a startLiveActivity varias veces con diferentes valores de live_activity_id.

Por ejemplo, si inicias dos actividades: FIRST_LIVE_ACTIVITY con filter: FILTER_NAME_1 y SECOND_LIVE_ACTIVITY con filter: FILTER_NAME_2, un dispositivo que coincida con ambos filtros tendrá ambas actividades ejecutándose simultáneamente.

Para actualizar una de ellas, pasa su live_activity_id a updateLiveActivity. La actualización se entrega a todos los dispositivos donde se creó esa actividad. La otra actividad no se ve afectada.

El parámetro relevance-score controla la prioridad de visualización cuando hay múltiples Live Activities activas en el mismo dispositivo. Si el espacio en la pantalla es limitado o las actividades están agrupadas, la actividad con un valor más alto se muestra con mayor prioridad.