Live Updates sur Android

Pushwoosh prend en charge les Live Updates Android via le module pushwoosh-liveupdates (SDK 6.9.0 et versions ultérieures). Une Live Update est une notification continue, de type progression, que le système met en avant sur l’écran de verrouillage, dans le tiroir de notifications et sous forme de puce d’état dans la barre d’état, afin que les utilisateurs puissent suivre une activité sans ouvrir votre application.

L’ensemble du cycle de vie est piloté depuis le serveur : votre backend envoie une notification push lorsque l’activité commence, d’autres notifications push au fur et à mesure de sa progression, et une dernière notification push lorsqu’elle se termine. Le SDK effectue le rendu de chacune d’entre elles automatiquement.

Que sont les Live Updates ?

Les Live Updates ont été introduites dans Android 16 (API 36) comme un moyen de présenter une activité initiée par l’utilisateur et sensible au temps, du début à la fin. Elles s’appuient sur les notifications centrées sur la progression de la plateforme et sur l’API Notification.ProgressStyle. Conceptuellement, elles sont l’équivalent Android des Live Activities d’iOS.

Cette page ne couvre que l’intégration de Pushwoosh. Pour le comportement de la plateforme, les règles de promotion et les conseils de conception, consultez la documentation officielle d’Android :

• Notifications centrées sur la progression
• Créer des notifications de mise à jour en direct (Vues)
• Créer des notifications de mise à jour en direct (Compose)

Quand utiliser les Live Updates ?

Les Live Updates sont destinées à une activité en cours, initiée par l’utilisateur et sensible au temps — quelque chose avec un début et une fin clairs qui intéresse activement l’utilisateur à l’instant T. Scénarios typiques pour les clients de Pushwoosh :

• Livraison de repas — commande acceptée, en préparation, en cours de livraison, en approche.
• VTC et taxi — chauffeur assigné, en route, en approche, trajet en cours.
• Suivi de commande et d’expédition — statut en direct d’une commande qui est activement en transit.
• Sports et médias en direct — score et temps du match au fur et à mesure de son déroulement.
• Fitness — un entraînement ou une course en cours avec le temps écoulé et la progression.
• Fintech — une transaction ou un flux de vérification passant par ses différentes étapes.

Étant donné que le cycle de vie est piloté par des événements réels que votre backend connaît déjà (une commande change de statut, un coursier se déplace), une Live Update correspond généralement à un seul appel d’API intégré à votre flux d’événements existant — et non à quelque chose qu’une personne envoie manuellement.

Attention

N’utilisez pas les Live Updates pour des promotions, des messages de chat ou des informations ambiantes, et ne republiez jamais une Live Update que l’utilisateur a rejetée. Android peut révoquer la capacité de l’application à publier des notifications promues. Suivez les recommandations d’Android sur l’utilisation appropriée.

Prérequis

• Android 16 (API 36) ou plus récent. Sur les appareils plus anciens, le module reste inactif et chaque appel d’API Live Update est une opération sûre sans effet (no-op).
• SDK Android Pushwoosh 6.9.0 ou version ultérieure.

Ajouter le module pushwoosh-liveupdates

Ajoutez la dépendance à votre fichier app/build.gradle :

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

Remplacez <latest-version> par la version actuelle de Maven Central.

Le module est découvert automatiquement au démarrage. Il déclare la permission requise POST_PROMOTED_NOTIFICATIONS, enregistre son propre canal de notification et intercepte les notifications push de Live Update avant le chemin de notification par défaut. Il n’y a pas de code d’initialisation supplémentaire — le SDK définit les indicateurs ongoing et promoted, télécharge la grande icône, mappe les boutons d’action et publie la notification pour vous.

Envoyer une Live Update

Vous envoyez des Live Updates via l’API de messagerie v2 en ajoutant des champs de Live Update à l’objet root_params du bloc de contenu android. Utilisez une requête transactional — une Live Update cible l’utilisateur spécifique dont elle suit l’activité. Le champ schedule est requis ; { "after": "0s" } envoie immédiatement. Le cycle de vie comporte trois opérations, définies dans pw_live_op :

• start — première notification push pour une activité. Publie la notification en cours.
• update — une notification push ultérieure pour la même activité. La rafraîchit sur place, silencieusement.
• end — notification push terminale. Rejette la notification.

Toutes les notifications push qui appartiennent à la même activité doivent partager le même pw_live_id. Cet identifiant relie les mises à jour entre elles et c’est aussi ce que vous utilisez pour rejeter la mise à jour depuis l’application.

Chaque notification push décrit entièrement la notification — rien n’est reporté de la notification push précédente. Renvoyez chaque champ que vous souhaitez conserver, comme les segments et la grande icône, avec chaque update ; un champ omis est rendu comme absent.

Paramètres de Live Update

Ces clés vont à l’intérieur de l’objet root_params du bloc de contenu android. Le titre, le corps et la grande icône utilisent les champs de notification push Android standard (title, body, custom_icon).

Paramètre	Type	Description
pw_live_op	string	Opération du cycle de vie : start, update ou end. Requis.
pw_live_id	string	Identifiant d’activité stable partagé par toutes les notifications push d’une même Live Update. Requis.
pw_live_progress	int	Valeur de progression, mesurée par rapport à la somme des longueurs des segments.
pw_live_progress_indeterminate	bool	Affiche une animation indéterminée au lieu d’une valeur concrète.
pw_live_segments	JSON string	Segments de progression ordonnés, chacun {"color": "#RRGGBB", "length": N}.
pw_live_extras	JSON string	Données arbitraires transmises à un fournisseur de style personnalisé.
pw_live_when	long	Ancre temporelle de l’en-tête, en millisecondes d’époque.
pw_live_chronometer	bool	Affiche l’heure de l’en-tête comme un chronomètre en cours.
pw_live_chronometer_count_down	bool	Un chronomètre en cours décompte au lieu de compter.
pw_live_show_when	bool	Affiche ou non la colonne de l’heure de l’en-tête. Vaut true par défaut.

Note

Les valeurs dans root_params sont livrées à l’appareil sous forme de chaînes de caractères, donc pw_live_segments et pw_live_extras doivent être passés comme des chaînes encodées en JSON, comme le montrent les exemples ci-dessous.

Les quatre champs temporels se combinent comme suit : avec pw_live_show_when défini sur false, l’heure est masquée ; sinon, pw_live_when est l’ancre, pw_live_chronometer la transforme en un compteur en direct, et pw_live_chronometer_count_down fait que ce compteur fonctionne à rebours.

Notification push de démarrage

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"
    }
  }'

Notification push de mise à jour

Envoyez une update avec le même pw_live_id chaque fois que l’activité progresse. Répétez les segments et l’icône — une mise à jour qui les omet s’affichera sans eux.

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"
    }
  }'

Notification push de fin

La notification push terminale n’a besoin que de l’opération et de l’identifiant.

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"
    }
  }'

Personnaliser l’apparence

Le SDK est livré avec un style de progression par défaut construit à partir de pw_live_progress, pw_live_progress_indeterminate et pw_live_segments. Pour prendre le contrôle total de la barre de progression, implémentez LiveUpdateProgressStyleProvider et façonnez vous-même un Notification.ProgressStyle.

Le fournisseur est le seul point de personnalisation. Le SDK gère toujours la configuration du canal, les indicateurs ongoing et promoted, la grande icône, les boutons d’action et l’heure de l’en-tête — un fournisseur personnalisé ne peut que façonner la barre de progression, il ne peut donc pas rompre l’éligibilité à la promotion. Il doit être sans état (stateless) : dérivez le style retourné uniquement à partir du LiveUpdateState fourni. S’il lève une exception, le SDK se rabat sur le style par défaut et la notification est quand même publiée.

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
    }
}

Enregistrez le fournisseur avec une balise <meta-data> dans AndroidManifest.xml. La classe doit avoir un constructeur public sans argument.

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

Utilisez LiveUpdateState.getExtras() pour lire le JSON que vous avez envoyé dans pw_live_extras et adapter le style à vos propres données métier.

Gérer les Live Updates depuis votre application

Le serveur pilote chaque start, update et end, il n’y a donc pas d’API côté application pour publier ou rafraîchir une Live Update. La façade PushwooshLiveUpdates ne couvre que ce que le serveur ne peut pas faire — rejeter une mise à jour localement et vérifier lesquelles sont à l’écran.

import com.pushwoosh.liveupdates.PushwooshLiveUpdates;

// Rejeter une Live Update spécifique lorsque l'utilisateur termine l'activité dans l'application,
// sans attendre la notification push terminale "end" du serveur
PushwooshLiveUpdates.endLiveUpdate("order_4521");

// Lister les identifiants d'activité actuellement affichés par cette application
List<String> active = PushwooshLiveUpdates.getActiveIds();

// Effacer tout ce que cette application affiche, par exemple lors de la déconnexion
PushwooshLiveUpdates.endAllLiveUpdates();

Toutes les méthodes peuvent être appelées en toute sécurité depuis n’importe quel thread et sont des opérations sans effet (no-op) sur les appareils inférieurs à Android 16.

Liens connexes

• Aperçu du SDK Android Pushwoosh
• Référence de l’API du SDK Android Pushwoosh
• API de messagerie
• Notifications centrées sur la progression d’Android