API Live Activities iOS

Documentation Apple :

• À propos des Live Activities
• Mise à jour et fin des Live Activities avec les notifications push d’ActivityKit

startLiveActivity

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

Permet de créer des Live Activities iOS.

Corps de la requête

Paramètre	Type	Requis/Optionnel	Description
application	String	Requis	Code d’application Pushwoosh
auth	String	Requis	Jeton d’accès API depuis le Control Panel de Pushwoosh.
notifications	Array	Requis	Tableau JSON des paramètres de message. Voir les détails dans le tableau Notifications ci-dessous.

Notifications

Paramètres utilisés dans le tableau notifications :

Paramètre	Type	Requis/Optionnel	Description
content	String	Requis	Contenu de repli pour les appareils exécutant des versions d’iOS inférieures à 16.1 qui ne prennent pas en charge les Live Activities. Sur iOS 16.1+ (avec prise en charge des Live Activities), le contenu provient du champ live_activity.
title	String	Optionnel	Le titre du message de notification.
live_activity	Object	Requis	Données de Live Activity pour créer une Live Activity dans iOS.
live_activity.content-state	Object	Requis	Contenu pour la notification de Live Activity.
live_activity.attributes-type	String	Requis	Le type d’attributs utilisé dans la Live Activity.
live_activity.attributes	Object	Requis	Attributs pour la Live Activity.
live_activity_id	String	Requis	Un identifiant unique pour la Live Activity. Utilisé pour cibler cette activité lors de l’appel à updateLiveActivity. Doit être unique par session d’activité.
filter	String	Optionnel	Le nom d’un filtre Pushwoosh (segment). Voir Nom du Segment / Filtre. La Live Activity sera démarrée sur tous les appareils correspondant à ce filtre.
devices	Array of Strings	Optionnel	Une liste de jetons d’appareil. La Live Activity ne sera démarrée que sur les appareils spécifiés.
send_date	String	Optionnel	Planifie le push qui démarre la Live Activity pour une date et une heure spécifiques — fonctionne avec le ciblage par filter ou par devices. Utilisez le format AAAA-MM-JJ HH:mm, ou now pour un démarrage immédiat (c’est aussi la valeur par défaut lorsque le paramètre est omis). La date ne doit pas être antérieure de plus d’un jour ou postérieure de plus de 30 jours, sinon la requête est rejetée avec une erreur de validation.
timezone	String	Optionnel	Le fuseau horaire utilisé pour interpréter send_date. S’il est omis, send_date est interprété en UTC.
apns_priority	Integer	Optionnel	Contrôle la priorité de livraison APNs pour ce push de Live Activity. Accepte 10 (haute priorité, livré avec l’en-tête apns-priority: 10 pour un rendu instantané sur un écran verrouillé) ou 5 (basse priorité, livré avec apns-priority: 5 pour préserver la batterie de l’appareil). Toute autre valeur est traitée comme 5, sans erreur de validation. Chaque push de Live Activity a par défaut une priorité de 5, qu’il contienne ou non un contenu d’alerte (content/title) — définissez explicitement apns_priority: 10 pour demander une livraison à haute priorité. Voir Push sensible au temps et priorité de livraison ci-dessous.

Attention

Le démarrage à distance d’une Live Activity via startLiveActivity nécessite iOS 17.2+ sur l’appareil — les versions antérieures ne prennent pas en charge l’API pushToStartTokenUpdates sur laquelle ce point de terminaison s’appuie. Voir Démarrer une Live Activity avec une notification push à distance.

Lors du ciblage d’un filter (segment), l’heure d’envoi planifiée correspond au moment où Pushwoosh commence à distribuer le push, et non à un instant de livraison garanti — pour les grandes audiences, la livraison aux appareils individuels peut avoir quelques minutes de retard par rapport à send_date, car le taux d’envoi pour les pushes de Live Activity ne peut pas être personnalisé avec send_rate.

Exemple de requête

Avec filtre

{
  "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"
      }
    ]
  }
}

Avec appareils

{
  "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"]
      }
    ]
  }
}

Démarrage planifié

{
  "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"
      }
    ]
  }
}

Exemple de réponse

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

Note :

Lisez cet article pour en savoir plus sur l’utilisation des Live Activities avec le SDK iOS de Pushwoosh.

updateLiveActivity

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

Permet de mettre à jour et de terminer les Live Activities iOS

Corps de la requête

Paramètre	Type	Requis/Optionnel	Description
auth	String	Requis	Jeton d’accès API depuis le Control Panel de Pushwoosh.
application	String	Requis	Code d’application Pushwoosh
notifications	Array	Requis	Tableau JSON des paramètres de message. Voir les détails dans le tableau Notifications ci-dessous.

Notifications

Paramètres utilisés dans le tableau notifications :

Paramètre	Type	Requis/Optionnel	Description
live_activity	Object	Requis	Données de Live Activity pour mettre à jour une Live Activity dans iOS.
live_activity.event	String	Requis	Spécifie le type d’événement. Utilisez "update" pour mettre à jour la Live Activity ou "end" pour la fermer.
live_activity.content-state	Object	Requis	Objet avec des paires clé-valeur utilisé pour passer des données à la Live Activity afin de mettre à jour son contenu.
live_activity.dismissal-date	Integer	Optionnel	Le moment (en secondes) où la Live Activity doit se terminer.
live_activity_id	String	Requis	L’identifiant unique de la Live Activity à mettre à jour. Doit correspondre au live_activity_id utilisé dans startLiveActivity. La mise à jour sera livrée à tous les appareils sur lesquels cette activité a été démarrée.
live_activity.relevance-score	Integer	Optionnel	Indique au système iOS quelle Live Activity a une priorité plus élevée que les autres. Accepte des valeurs de 1 à l’infini (des valeurs jusqu’à 100 sont recommandées).
live_activity.stale-date	Integer	Optionnel	Le moment (en secondes) qui représente la date à laquelle une Live Activity devient obsolète ou périmée.
apns_priority	Integer	Optionnel	Contrôle la priorité de livraison APNs pour ce push de Live Activity. Accepte 10 (haute priorité, livré avec l’en-tête apns-priority: 10 pour un rendu instantané sur un écran verrouillé) ou 5 (basse priorité, livré avec apns-priority: 5 pour préserver la batterie de l’appareil). Toute autre valeur est traitée comme 5, sans erreur de validation. Chaque push de Live Activity a par défaut une priorité de 5, qu’il contienne ou non un contenu d’alerte (content/title) — définissez explicitement apns_priority: 10 pour demander une livraison à haute priorité. Voir Push sensible au temps et priorité de livraison ci-dessous.

Note : relevance-score n’affecte que l’ordre d’affichage parmi plusieurs Live Activities actives sur le même appareil — il n’affecte pas l’urgence de la livraison. Utilisez apns_priority pour contrôler l’urgence de la livraison d’une mise à jour.

Exemple de requête

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

Exemple de réponse

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

Lisez cet article pour en savoir plus sur l’utilisation des Live Activities avec le SDK iOS de Pushwoosh.

Push sensible au temps et priorité de livraison

Par défaut, Apple livre les mises à jour des Live Activities avec une faible priorité (apns-priority: 5) pour préserver la batterie. Lorsqu’un appareil est verrouillé, une mise à jour à faible priorité est traitée en arrière-plan et ne devient visible sur l’écran de verrouillage qu’une fois que l’utilisateur déverrouille l’appareil. Sur un appareil déjà déverrouillé, elle s’affiche toujours instantanément. Utilisez le paramètre apns_priority décrit ci-dessus pour demander une livraison à haute priorité (apns-priority: 10) afin que la mise à jour s’affiche immédiatement sur l’écran de verrouillage, sans déverrouillage.

Non lié au bouton Push sensible au temps

Le bouton Push sensible au temps dans le Control Panel de Pushwoosh définit le interruption-level uniquement pour les notifications push standard. Il n’a aucun effet sur la priorité de livraison des Live Activities envoyées via cette API — les Live Activities utilisent un chemin de livraison distinct, contrôlé exclusivement par le paramètre de requête apns_priority.

Même avec apns_priority: 10 disponible, Apple limite la fréquence à laquelle il peut être utilisé.

Budget haute priorité APNs

Apple limite le nombre de pushes à haute priorité (apns-priority: 10) qu’une application peut envoyer par heure. Pour les activités fréquemment mises à jour (par ex. les scores en direct), réservez apns_priority: 10 pour les événements critiques et utilisez apns_priority: 5 ou moins de mises à jour pour les changements de routine. L’activation de NSSupportsLiveActivitiesFrequentUpdates dans le fichier Info.plist de votre application (voir le guide du SDK iOS) augmente ce budget pour les cas d’utilisation à haute fréquence.

Activités multiples par appareil

Vous pouvez démarrer plusieurs Live Activities sur le même appareil en appelant startLiveActivity plusieurs fois avec des valeurs live_activity_id différentes.

Par exemple, si vous démarrez deux activités : FIRST_LIVE_ACTIVITY avec filter: FILTER_NAME_1 et SECOND_LIVE_ACTIVITY avec filter: FILTER_NAME_2, un appareil qui correspond aux deux filtres aura les deux activités en cours d’exécution simultanément.

Pour mettre à jour l’une d’entre elles, passez son live_activity_id à updateLiveActivity. La mise à jour est livrée à tous les appareils où cette activité a été créée. L’autre activité n’est pas affectée.

Le paramètre relevance-score contrôle la priorité d’affichage lorsque plusieurs Live Activities sont actives sur le même appareil. Si l’espace à l’écran est limité ou si les activités sont regroupées, l’activité avec une valeur plus élevée est affichée avec une priorité supérieure.