# API iOS Live Activities

> Documentation Apple :
> 
> * [À propos des Live Activities](https://developer.apple.com/design/human-interface-guidelines/live-activities)
> * [Mise à jour et fin des Live Activities avec les notifications push ActivityKit](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications)

Pour permettre à un élément Live Activity de Customer Journey de construire son formulaire d'état de contenu à partir de noms de champs au lieu d'un éditeur JSON brut, publiez un schéma pour votre `attributes-type` — voir l'[API des schémas de Live Activity](/fr/developer/api-reference/live-activity-schemas-api/).



## 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](/fr/developer/api-reference/api-identifiers/#application-code)                                             |
| auth          | String | Requis           | [Jeton d'accès API](/fr/developer/api-reference/api-identifiers/#api-access-token) 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*          | Corps de l'alerte pour la notification push qui démarre la Live Activity, et le texte de repli affiché sur les appareils exécutant des versions d'iOS inférieures à 16.1. |
| title         | String | Requis*          | Titre de l'alerte pour la notification push qui démarre la Live Activity.                                                                                                            |
| live_activity    | Object           | Requis           | Données de la Live Activity pour créer une Live Activity dans iOS.                          |
| live_activity.content-state    | Object           | Requis           | Contenu pour la notification de la Live Activity.                                 |
| live_activity.attributes-type  | String           | Requis           | Le type d'attributs utilisés 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 (segment) Pushwoosh. Voir [Nom du Segment / Filtre](/fr/developer/api-reference/api-identifiers/#segment--filter-name). 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](/fr/developer/api-reference/api-identifiers/#push-token). La Live Activity ne sera démarrée que sur les appareils spécifiés. |
| send_date | String | Optionnel | Planifie la notification push qui démarre la Live Activity pour une date et une heure spécifiques — fonctionne avec le ciblage par `filter` ou `devices`. Utilisez le format `AAAA-MM-JJ HH:mm`, ou `now` pour démarrer immédiatement (c'est aussi la valeur par défaut lorsque le paramètre est omis). Ne doit pas être plus d'un jour dans le passé ou 30 jours dans le futur, 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 cette notification push de Live Activity. Accepte `10` (haute priorité, livrée avec l'en-tête `apns-priority: 10` pour un rendu instantané sur un écran verrouillé) ou `5` (basse priorité, livrée avec `apns-priority: 5` pour économiser la batterie de l'appareil). Toute autre valeur est traitée comme `5`, sans erreur de validation. Chaque notification push de Live Activity a par défaut une priorité de 5, qu'elle 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](#time-sensitive-push-and-delivery-priority) ci-dessous. |

> **Remarque :** `*` Au moins l'un des champs `content` ou `title` doit être non vide. Pushwoosh rejette une demande de démarrage si les deux sont vides.

<Aside type="caution">
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](/fr/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/#start-live-activity-with-a-remote-push-notification).

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

Les appels répétés de push-to-start s'épuisent silencieusement. Après environ dix démarrages successifs rapides, Apple cesse de livrer la notification push-to-start sous-jacente sans aucune erreur, et `startLiveActivity` renvoie toujours 200. Pendant les tests de campagne, cela ressemble à « l'API fonctionne mais rien ne se passe sur l'appareil ». Espacez les démarrages de test consécutifs.
</Aside>

### Exemple de requête

<Tabs>
<TabItem label="Avec filtre">
```json
{
  "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"
      }
    ]
  }
}
```
</TabItem>
<TabItem label="Avec appareils">
```json
{
  "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"]
      }
    ]
  }
}
```
</TabItem>
<TabItem label="Démarrage planifié">
```json
{
  "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"
      }
    ]
  }
}
```
</TabItem>
</Tabs>

### Exemple de réponse

```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}
```
> **Remarque :**
> 
> Lisez [cet article](/fr/developer/pushwoosh-sdk/ios-sdk/ios-live-activities) 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](/fr/developer/api-reference/api-identifiers/#api-access-token) depuis le Control Panel de Pushwoosh.                      |
| application    | String | Requis           | [Code d'application Pushwoosh](/fr/developer/api-reference/api-identifiers/#application-code)                                       |
| 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 la Live Activity pour mettre à jour la 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 pour mettre à jour son contenu. |
| live_activity.dismissal-date   | Integer | Optionnel           | L'heure (en secondes) à laquelle la Live Activity doit se terminer. Pour un `end`, omettez ce champ pour que la carte continue d'afficher son dernier `content-state` jusqu'à ce qu'iOS la retire d'elle-même — voir la remarque ci-dessous. Indiquez une date dans le passé pour que la carte soit retirée dès l'arrivée de cette mise à jour.                    |
| 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 | L'heure (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 cette notification push de Live Activity. Accepte `10` (haute priorité, livrée avec l'en-tête `apns-priority: 10` pour un rendu instantané sur un écran verrouillé) ou `5` (basse priorité, livrée avec `apns-priority: 5` pour économiser la batterie de l'appareil). Toute autre valeur est traitée comme `5`, sans erreur de validation. Chaque notification push de Live Activity a par défaut une priorité de 5, qu'elle 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](#time-sensitive-push-and-delivery-priority) ci-dessous. |
| content | String | Optionnel | Corps de l'alerte pour cette mise à jour. Le cas courant est une mise à jour de l'état du contenu uniquement, qui ne définit aucun des champs content, title ou subtitle et ne contient aucune alerte. |
| title | String | Optionnel | Titre de l'alerte pour cette mise à jour. Définir content, title ou subtitle déclenche une alerte et permet à `ios_sound` de jouer. Si aucun des trois n'est défini, la mise à jour reste silencieuse, ce qui est le comportement par défaut pour les mises à jour de l'état du contenu uniquement. |
| subtitle | String | Optionnel | Sous-titre de l'alerte pour cette mise à jour. Même rôle de déclenchement d'alerte que `content`/`title` ci-dessus. |
| ios_sound | String | Optionnel | Nom du fichier son dans le bundle principal de l'application. Il est inclus dans `aps.alert` avec `content`/`title`/`subtitle`, et non dans le `aps.sound` de niveau supérieur, qu'ActivityKit ignore pour les Live Activities, donc il ne joue que lorsque cette mise à jour définit également au moins l'un de ces trois. iOS limite également de son côté les alertes de Live Activity. Le même payload a été observé arrivant avec du son lors d'une livraison et sans lors de la suivante, à la fois sur l'appareil et sur le simulateur. |

> **Remarque :** `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 avec laquelle une mise à jour est livrée.

<Aside type="note">
Un `end` sans `dismissal-date` ne supprime pas la carte. Elle reste sur l'écran verrouillé en affichant le `content-state` envoyé par cette mise à jour, et le système Live Activity d'Apple la retire de lui-même dans un délai maximal de 4 heures.
</Aside>

### Exemple de requête

```json

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

### Exemple de réponse

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

> [Lisez cet article](/fr/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/) 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.

<Aside type="caution" title="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`.
</Aside>

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

<Aside type="note" title="Budget haute priorité APNs">
Apple limite le nombre de notifications push à 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](/fr/developer/pushwoosh-sdk/ios-sdk/ios-live-activities/#infoplist-configuration)) augmente ce budget pour les cas d'utilisation à haute fréquence.
</Aside>

## 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é plus élevée.