Actualizaciones en vivo en Android

Pushwoosh es compatible con las Actualizaciones en vivo de Android a través del módulo pushwoosh-liveupdates (SDK 6.9.0 y versiones posteriores). Una Actualización en vivo es una notificación continua, de estilo de progreso, que el sistema promueve en la pantalla de bloqueo, en el cajón de notificaciones y como un chip de estado en la barra de estado, para que los usuarios puedan seguir una actividad sin abrir tu aplicación.

Todo el ciclo de vida se gestiona desde el servidor: tu backend envía un push cuando la actividad comienza, más pushes a medida que progresa y un push final cuando termina. El SDK renderiza cada uno automáticamente.

¿Qué son las Actualizaciones en vivo?

Las Actualizaciones en vivo se introdujeron en Android 16 (API 36) como una forma de mostrar una actividad iniciada por el usuario y sensible al tiempo de principio a fin. Se basan en las notificaciones centradas en el progreso de la plataforma y en la API Notification.ProgressStyle. Conceptualmente, son la contraparte en Android de las Actividades en vivo de iOS.

Esta página cubre únicamente la integración con Pushwoosh. Para conocer el comportamiento de la plataforma, las reglas de promoción y las guías de diseño, consulta la documentación oficial de Android:

• Notificaciones centradas en el progreso
• Crear notificaciones de actualización en vivo (Vistas)
• Crear notificaciones de actualización en vivo (Compose)

Cuándo usar las Actualizaciones en vivo

Las Actualizaciones en vivo están pensadas para una actividad que está en curso, iniciada por el usuario y es sensible al tiempo, algo con un inicio y un final claros que al usuario le importa activamente en ese momento. Escenarios típicos para los clientes de Pushwoosh:

• Entrega de comida — pedido aceptado, en preparación, en camino, llegando.
• Servicios de transporte y taxi — conductor asignado, en ruta, llegando, viaje en curso.
• Seguimiento de pedidos y envíos — estado en vivo de un pedido que está activamente en tránsito.
• Deportes y medios en vivo — marcador y tiempo del partido a medida que se desarrolla.
• Fitness — un entrenamiento o carrera activa con tiempo transcurrido y progreso.
• Fintech — un flujo de transacción o verificación que avanza por sus etapas.

Debido a que el ciclo de vida es impulsado por eventos reales que tu backend ya conoce (un pedido cambia de estado, un mensajero se mueve), una Actualización en vivo suele ser una llamada a la API integrada en tu flujo de eventos existente, no algo que una persona envía manualmente.

Precaución

No utilices las Actualizaciones en vivo para promociones, mensajes de chat o información ambiental, y nunca vuelvas a publicar una Actualización en vivo que el usuario haya descartado. Android puede revocar la capacidad de la aplicación para publicar notificaciones promocionadas. Sigue la guía de Android sobre el uso apropiado.

Requisitos

• Android 16 (API 36) o superior. En dispositivos más antiguos, el módulo permanece inactivo y cada llamada a la API de Actualización en vivo es una operación segura que no hace nada (no-op).
• Pushwoosh Android SDK 6.9.0 o posterior.

Añadir el módulo pushwoosh-liveupdates

Añade la dependencia a tu archivo app/build.gradle:

dependencies {
    implementation 'com.pushwoosh:pushwoosh-liveupdates:<latest-version>'
}

Reemplaza <latest-version> con la versión actual de Maven Central.

El módulo se descubre automáticamente al iniciar. Declara el permiso requerido POST_PROMOTED_NOTIFICATIONS, registra su propio canal de notificaciones e intercepta los pushes de Actualización en vivo antes de la ruta de notificación predeterminada. No hay código de inicialización adicional: el SDK establece los indicadores de “en curso” y “promocionado”, descarga el icono grande, mapea los botones de acción y publica la notificación por ti.

Enviar una Actualización en vivo

Envías Actualizaciones en vivo a través de la API de mensajería v2 añadiendo campos de Actualización en vivo al objeto root_params del bloque de contenido android. Utiliza una solicitud transactional: una Actualización en vivo se dirige al usuario específico cuya actividad está rastreando. El campo schedule es obligatorio; { "after": "0s" } envía inmediatamente. El ciclo de vida tiene tres operaciones, establecidas en pw_live_op:

• start — primer push para una actividad. Publica la notificación en curso.
• update — un push posterior para la misma actividad. La actualiza en el mismo lugar, de forma silenciosa.
• end — push terminal. Descarta la notificación.

Todos los pushes que pertenecen a la misma actividad deben compartir el mismo pw_live_id. Ese ID une las actualizaciones y también es lo que usas para descartar la actualización desde la aplicación.

Cada push describe completamente la notificación; nada se hereda del push anterior. Vuelve a enviar cada campo que quieras conservar, como los segmentos y el icono grande, con cada update; un campo omitido se renderiza como ausente.

Parámetros de Actualización en vivo

Estas claves van dentro del objeto root_params del bloque de contenido android. El título, el cuerpo y el icono grande utilizan los campos de push estándar de Android (title, body, custom_icon).

Parámetro	Tipo	Descripción
pw_live_op	string	Operación del ciclo de vida: start, update o end. Requerido.
pw_live_id	string	ID de actividad estable compartido por todos los pushes de una Actualización en vivo. Requerido.
pw_live_progress	int	Valor de progreso, medido contra la suma de las longitudes de los segmentos.
pw_live_progress_indeterminate	bool	Muestra una animación indeterminada en lugar de un valor concreto.
pw_live_segments	JSON string	Segmentos de progreso ordenados, cada uno {"color": "#RRGGBB", "length": N}.
pw_live_extras	JSON string	Datos arbitrarios pasados a un proveedor de estilo personalizado.
pw_live_when	long	Ancla de tiempo del encabezado, en milisegundos de la época (epoch).
pw_live_chronometer	bool	Muestra el tiempo del encabezado como un cronómetro en funcionamiento.
pw_live_chronometer_count_down	bool	Un cronómetro en funcionamiento cuenta hacia atrás en lugar de hacia adelante.
pw_live_show_when	bool	Muestra la columna de tiempo del encabezado. El valor predeterminado es true.

Nota

Los valores en root_params se entregan al dispositivo como cadenas de texto, por lo que pw_live_segments y pw_live_extras deben pasarse como cadenas codificadas en JSON, como se muestra en los ejemplos a continuación.

Los cuatro campos de tiempo se combinan de la siguiente manera: con pw_live_show_when establecido en false, el tiempo se oculta; de lo contrario, pw_live_when es el ancla, pw_live_chronometer lo convierte en un contador en vivo, y pw_live_chronometer_count_down hace que ese contador vaya hacia atrás.

Push de inicio

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "title": "Order #4521",
                "body": "We are preparing your order",
                "custom_icon": "https://example.com/restaurant.png",
                "root_params": {
                  "pw_live_op": "start",
                  "pw_live_id": "order_4521",
                  "pw_live_progress": "1",
                  "pw_live_segments": "[{\"color\":\"#34A853\",\"length\":3},{\"color\":\"#FBBC05\",\"length\":4},{\"color\":\"#4285F4\",\"length\":3}]",
                  "pw_live_extras": "{\"eta\":\"18:40\"}"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Push de actualización

Envía un update con el mismo pw_live_id cada vez que la actividad avance. Repite los segmentos y el icono; una actualización que los omita se renderizará sin ellos.

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "title": "Order #4521",
                "body": "Your courier is on the way",
                "custom_icon": "https://example.com/restaurant.png",
                "root_params": {
                  "pw_live_op": "update",
                  "pw_live_id": "order_4521",
                  "pw_live_progress": "7",
                  "pw_live_segments": "[{\"color\":\"#34A853\",\"length\":3},{\"color\":\"#FBBC05\",\"length\":4},{\"color\":\"#4285F4\",\"length\":3}]"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Push de finalización

El push terminal solo necesita la operación y el ID.

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "android": {
                "root_params": {
                  "pw_live_op": "end",
                  "pw_live_id": "order_4521"
                }
              }
            }
          }
        }
      },
      "schedule": { "after": "0s" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Personalizar la apariencia

El SDK incluye un estilo de progreso predeterminado construido a partir de pw_live_progress, pw_live_progress_indeterminate y pw_live_segments. Para tener control total sobre la barra de progreso, implementa LiveUpdateProgressStyleProvider y da forma a un Notification.ProgressStyle tú mismo.

El proveedor es el único punto de personalización. El SDK sigue siendo responsable de la configuración del canal, los indicadores de “en curso” y “promocionado”, el icono grande, los botones de acción y el tiempo del encabezado; un proveedor personalizado solo puede dar forma a la barra de progreso, por lo que no puede romper la elegibilidad para la promoción. Debe ser sin estado: deriva el estilo devuelto únicamente del LiveUpdateState proporcionado. Si lanza una excepción, el SDK recurre al estilo predeterminado y la notificación se publica de todos modos.

Java

import android.app.Notification;
import androidx.annotation.NonNull;
import com.pushwoosh.liveupdates.LiveUpdateProgressStyleProvider;
import com.pushwoosh.liveupdates.LiveUpdateSegment;
import com.pushwoosh.liveupdates.LiveUpdateState;
import java.util.List;

public class OrderStyleProvider implements LiveUpdateProgressStyleProvider {
    @NonNull
    @Override
    public Notification.ProgressStyle createStyle(@NonNull LiveUpdateState state) {
        Notification.ProgressStyle style = new Notification.ProgressStyle();
        if (state.getProgress() != null) {
            style.setProgress(state.getProgress());
        }
        style.setProgressIndeterminate(state.isProgressIndeterminate());

        List<LiveUpdateSegment> segments = state.getSegments();
        int boundary = 0;
        for (int i = 0; i < segments.size(); i++) {
            LiveUpdateSegment seg = segments.get(i);
            style.addProgressSegment(
                new Notification.ProgressStyle.Segment(seg.getLength()).setColor(seg.getColor()));
            boundary += seg.getLength();
            if (i < segments.size() - 1) {
                style.addProgressPoint(new Notification.ProgressStyle.Point(boundary));
            }
        }
        return style;
    }
}

Kotlin

import android.app.Notification
import com.pushwoosh.liveupdates.LiveUpdateProgressStyleProvider
import com.pushwoosh.liveupdates.LiveUpdateState

class OrderStyleProvider : LiveUpdateProgressStyleProvider {
    override fun createStyle(state: LiveUpdateState): Notification.ProgressStyle {
        val style = Notification.ProgressStyle()
        state.progress?.let { style.setProgress(it) }
        style.setProgressIndeterminate(state.isProgressIndeterminate)

        val segments = state.segments
        var boundary = 0
        segments.forEachIndexed { i, seg ->
            style.addProgressSegment(
                Notification.ProgressStyle.Segment(seg.length).setColor(seg.color))
            boundary += seg.length
            if (i < segments.size - 1) {
                style.addProgressPoint(Notification.ProgressStyle.Point(boundary))
            }
        }
        return style
    }
}

Registra el proveedor con una etiqueta <meta-data> en AndroidManifest.xml. La clase debe tener un constructor público sin argumentos.

<meta-data
    android:name="com.pushwoosh.LIVE_UPDATE_STYLE_PROVIDER"
    android:value="com.example.OrderStyleProvider" />

Usa LiveUpdateState.getExtras() para leer el JSON que enviaste en pw_live_extras y adaptar el estilo a tus propios datos de negocio.

Gestionar Actualizaciones en vivo desde tu aplicación

El servidor impulsa cada start, update y end, por lo que no hay una API del lado de la aplicación para publicar o actualizar una Actualización en vivo. La fachada PushwooshLiveUpdates cubre solo lo que el servidor no puede hacer: descartar una actualización localmente y verificar cuáles están en pantalla.

import com.pushwoosh.liveupdates.PushwooshLiveUpdates;

// Descarta una Actualización en vivo específica cuando el usuario finaliza la actividad en la aplicación,
// sin esperar al push terminal "end" del servidor
PushwooshLiveUpdates.endLiveUpdate("order_4521");

// Lista los ID de actividad que esta aplicación muestra actualmente
List<String> active = PushwooshLiveUpdates.getActiveIds();

// Borra todo lo que esta aplicación está mostrando, por ejemplo, al cerrar sesión
PushwooshLiveUpdates.endAllLiveUpdates();

Todos los métodos son seguros para llamar desde cualquier hilo y son una operación que no hace nada (no-op) en dispositivos por debajo de Android 16.

Enlaces relacionados

• Resumen del SDK de Pushwoosh para Android
• Referencia de la API del SDK de Pushwoosh para Android
• API de mensajería
• Notificaciones centradas en el progreso de Android