Inicio rápido

Inicia, muestra, actualiza y finaliza una actividad en directo.

Necesitas tres cosas:

Una forma de hacer solicitudes HTTP (curl, un backend, una función serverless).
Una clave de API. Crea una cuenta, elige un plan en el panel (el plan gratuito sirve) y copia la clave desde Developer > API Key.
Un móvil: un iPhone con iOS 18 o posterior, o un móvil Android con la app WebActivity.

Cada llamada necesita la clave de API en el encabezado x-api-key. La clave es secreta: envía las solicitudes desde un backend, nunca desde código del navegador.

Inicia la actividad

Envía el primer state. Su layout define el diseño (progress, picture, versus o countdown). El widgetContainerId es obligatorio: cualquier texto que identifique este widget. Envía el mismo valor en cada llamada posterior. brand.title da nombre a la actividad en la app.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "pizza-tracker",
  "group": "order-tracker",
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Preparing your order",
    "progress": 0.25
  }
}'

La respuesta (201) da el activityId, que usan todas las llamadas posteriores, y links.iframe, el botón de lanzamiento:

{
  "ok": true,
  "activityId": "act-8f2cqa4mx7rd",
  "userId": "act-8f2cqa4mx7rd",
  "group": "order-tracker",
  "widgetContainerId": "pizza-tracker",
  "links": {
    "iframe": "<iframe src=\"https://api.webliveactivity.com/embed/button?type=track&userId=act-8f2cqa4mx7rd\" width=\"340\" height=\"95\" style=\"border:0;color-scheme:light\"></iframe>"
  }
}

Ábrela en un móvil

Pega links.iframe en una página web. Muestra un botón Track With Live Activity.

iPhone: al tocarlo se abre la app, o su App Clip sin instalar nada.
Android: al tocarlo se abre la app WebActivity, o Google Play para instalarla.
Ordenador: al hacer clic se muestra un código QR para escanear con el móvil.

Luego la tarjeta aparece en la pantalla de bloqueo y en la Dynamic Island. ¿Aún no tienes una página web? Abre la URL src del iframe en el navegador de un ordenador y haz clic en el botón. Para cambiar su color o usarlo en una página oscura, consulta el botón de lanzamiento.

Una actividad pertenece al primer teléfono que la abre. Para dar un botón a muchas personas, inicia con reuse: true. Consulta un botón, muchos móviles.

Envía actualizaciones

Envía el activityId, su widgetContainerId y solo los campos que cambian. Se combinan con el estado guardado.

curl -X POST https://api.webliveactivity.com/api/update \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "activityId": "act-8f2cqa4mx7rd",
  "widgetContainerId": "pizza-tracker",
  "state": {
    "primaryText": "Out for delivery",
    "stage": "On the way",
    "progress": 0.7,
    "estimatedMinutes": 8
  }
}'

La tarjeta se actualiza en su lugar. Cada actualización genera una alerta en el teléfono, salvo que se envíe con priority: 5. Las actualizaciones pueden tardar hasta 45 segundos en llegar. Consulta entrega y facturación.

Finalízala

Finaliza la actividad cuando termine el trabajo. La tarjeta se quita del teléfono de inmediato, sin sonido. Para dejar un diseño final en pantalla, envíalo como actualización y finaliza la actividad después.

curl -X POST https://api.webliveactivity.com/api/end \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "activityId": "act-8f2cqa4mx7rd",
  "widgetContainerId": "pizza-tracker"
}'

Finalizar no elimina la actividad. Una actualización con restart: true trae la tarjeta de vuelta al mismo teléfono.

Apunta a un grupo

Un group definido al iniciar etiqueta actividades. Envía el group y su widgetContainerId, sin activityId, para actualizarlas o finalizarlas todas con una sola llamada:

curl -X POST https://api.webliveactivity.com/api/update \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "group": "order-tracker",
  "widgetContainerId": "pizza-tracker",
  "state": {
    "secondaryText": "Kitchen is busier than usual"
  }
}'

Actividades de larga duración

iOS deja de aceptar actualizaciones normales 8 horas después de que empieza una tarjeta. Si inicias la actividad con keepAlive: true, el servicio reinicia la tarjeta cada 7 horas para que siga en el teléfono. Cada uno de esos reinicios genera una alerta. Una cuenta atrás de más de 8 horas lo necesita para llegar a su alerta. Sin él, la siguiente actualización pasadas las 8 horas se envía como reinicio, que vuelve a crear la tarjeta y siempre genera una alerta. Para recuperar una tarjeta que el usuario ha descartado, envía una actualización con restart: true.

Recibe callbacks del ciclo de vida

Añade un endpoint de webhook en el panel. El servicio lo llama cuando una actividad aparece por primera vez en un teléfono, y cuando el usuario la desactiva o la elimina en la app. Consulta webhooks.

Cambia el diseño

Envía un nuevo layout, con los campos de ese diseño, en cualquier actualización. La tarjeta cambia al diseño nuevo. Consulta diseños.