> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Application d'exemple : Live Activities

> Comment l'application d'exemple Clean Beans démarre, met à jour et termine des Live Activities iOS depuis son backend, avec le code du widget et les requêtes API.

Cette page fait partie de [Application d'exemple : une intégration OneSignal complète](https://documentation.onesignal.com/docs/fr/example-full-integration-overview.md), qui suit une application réelle de bout en bout. L'application s'appelle **Clean Beans**, un planning de ménage pour les logements partagés, construite avec Expo (React Native) et un backend Supabase.

Une Live Activity est une petite vue mise à jour en direct sur l'écran de verrouillage iOS et dans la Dynamic Island. Clean Beans en utilise deux : un compte à rebours jusqu'au créneau de ménage de l'utilisateur et une alerte lorsqu'une série est sur le point de s'arrêter.

![Une Live Activity de rappel de ménage sur l'écran de verrouillage iOS](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-LiveActivity-countdown.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=d3e51363076f6271d5f47cfec850e5e2)

Le rappel de ménage en compte à rebours sur l'écran de verrouillage.

Les Live Activities sont normalement démarrées par l'application. Clean Beans les démarre depuis le backend, car elles doivent apparaître à une heure précise, que l'application soit ouverte ou non. Le **push-to-start** de OneSignal le rend possible.

## Configurer l'application \\

Une application multiplateforme peut laisser OneSignal gérer le cycle de vie de la Live Activity. Un seul appel au démarrage suffit côté JavaScript.

```typescript app/_layout.tsx theme={null}
// Enable Live Activities with the default attributes type
OneSignal.LiveActivities.setupDefault({
  enablePushToStart: true,
  enablePushToUpdate: true,
});
```

Le seul code natif à écrire est la mise en page du widget, en SwiftUI. Clean Beans ajoute l'extension de widget au projet iOS avec un petit plugin de configuration Expo, de sorte que le projet peut toujours être régénéré de zéro à chaque compilation.

```javascript plugins/withLiveActivityWidget.js theme={null}
const WIDGET_TARGET_NAME = "CleanBeansWidgetExtension";
const WIDGET_BUNDLE_ID_SUFFIX = ".CleanBeansWidgetExtension";
const DEPLOYMENT_TARGET = "16.2";
```

## Dessiner le widget \\

Le widget utilise `DefaultLiveActivityAttributes` de OneSignal, qui transporte des données libres. Un seul widget sert les deux activités : il lit une valeur `type` et choisit une mise en page.

```swift plugins/widget/CleanBeansWidgetLiveActivity.swift theme={null}
struct CleanBeansWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DefaultLiveActivityAttributes.self) { context in
            // Dispatch based on activity type
            let activityType = context.attributes.data["type"]?.asString() ?? "streak-warning"

            if activityType == "cleaning-reminder" {
                CleaningReminderLockScreen(context: context)
            } else {
                StreakWarningLockScreen(context: context)
            }

        } dynamicIsland: { context in
            let activityType = context.attributes.data["type"]?.asString() ?? "streak-warning"

            if activityType == "cleaning-reminder" {
                return cleaningReminderDynamicIsland(context: context)
            } else {
                return streakWarningDynamicIsland(context: context)
            }
        }
    }
}
```

Chaque mise en page lit ses valeurs dans les données envoyées par le backend. Les `attributes` sont fixés au démarrage de l'activité. Le `state` peut changer à chaque mise à jour.

```swift plugins/widget/CleanBeansWidgetLiveActivity.swift theme={null}
let title = context.attributes.data["title"]?.asString() ?? "Streak Warning"
let message = context.state.data["message"]?.asDict()?["en"]?.asString()
    ?? "Your streak is at risk!"
let streakCount = context.state.data["streakCount"]?.asInt() ?? 0
let midnightTs = context.state.data["midnightTs"]?.asInt() ?? 0
let midnightDate = Date(timeIntervalSince1970: Double(midnightTs))
```

Un compte à rebours est dessiné avec le style minuteur de SwiftUI, qui avance sur l'appareil sans autre mise à jour du serveur.

## Alerte de série : démarrer une activité depuis le backend \\

À 19 h, heure locale, toute personne ayant une série en cours et n'ayant pas fait de ménage dans la journée reçoit un compte à rebours jusqu'à minuit. La fonction horaire trouve ces personnes avec la même correspondance de fuseau horaire que les rappels push, puis démarre une activité pour chacune.

```typescript supabase/functions/streak-warning/index.ts theme={null}
const payload = {
  event: 'start',
  activity_id: activityId,
  include_aliases: {
    external_id: [user.id],
  },
  target_channel: 'push',
  event_attributes: {
    data: {
      title: 'Streak Warning',
    },
  },
  event_updates: {
    data: {
      message: {
        en: `Your ${user.streakCount}-day streak ends at midnight!`,
      },
      streakCount: user.streakCount,
      midnightTs: user.midnightTs,
      userName: user.name,
    },
  },
  name: 'Streak Warning',
  contents: {
    en: `Your ${user.streakCount}-day streak ends at midnight!`,
  },
  headings: {
    en: 'Streak at risk!',
  },
  priority: 10,
};

const res = await fetch(
  `https://api.onesignal.com/apps/${ONESIGNAL_APP_ID}/activities/activity/DefaultLiveActivityAttributes`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Key ${ONESIGNAL_REST_API_KEY}`,
    },
    body: JSON.stringify(payload),
  }
);
```

![Une Live Activity d'alerte de série en compte à rebours jusqu'à minuit](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-LA-warning.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=586ca54b6a57f7d1647d5e9bb5aa874f)

L'alerte de série en compte à rebours jusqu'à minuit.

## Rappel de ménage : démarrer, mettre à jour, terminer \\

Le rappel de ménage passe par trois phases. Chacune fait l'objet d'une requête distincte pour la même activité.

| Phase | Quand | Requête | Ce qu'affiche le widget |
| - | - | - | - |
| Compte à rebours | Une heure avant le créneau | `start` | Un minuteur jusqu'à l'heure de début |
| Active | Le créneau commence | `update` | « It's your scheduled cleaning time, jump to it! » |
| Terminée | Le créneau se termine | `end` | Fermée au bout de cinq secondes |

La fonction détermine dans quelle phase chaque utilisateur doit se trouver.

```typescript supabase/functions/cleaning-activity/index.ts theme={null}
function getDesiredPhase(
  currentHour: number,
  window: CleaningWindow,
): 'countdown' | 'active' | null {
  const reminderHour = (window.start - 1 + 24) % 24;

  // Active: inside the cleaning window
  if (isHourInRange(currentHour, window.start, window.end)) return 'active';

  // Countdown: the single hour before the window starts
  if (currentHour === reminderHour) return 'countdown';

  return null;
}
```

Elle enregistre la phase actuelle dans le profil de l'utilisateur et n'envoie une requête que lorsque la phase souhaitée est différente. La tâche horaire peut ainsi être exécutée plusieurs fois sans risque.

La mise à jour et la fin utilisent un endpoint différent de celui du démarrage. L'activité est indiquée dans l'URL, ces requêtes ne contiennent donc aucun ciblage.

```typescript supabase/functions/cleaning-activity/index.ts theme={null}
async function updateCleaningActivity(activityId: string): Promise<boolean> {
  const payload = {
    event: 'update',
    event_updates: {
      data: {
        message: { en: "It's your scheduled cleaning time, jump to it!" },
        phase: 'active',
        targetTs: 0,
      },
    },
    name: 'Cleaning Active',
    contents: { en: "It's your scheduled cleaning time!" },
    priority: 10,
  };

  // ...
}

async function endCleaningActivity(activityId: string): Promise<boolean> {
  const payload = {
    event: 'end',
    event_updates: {
      data: {
        message: { en: 'Cleaning window ended' },
        phase: 'ended',
      },
    },
    name: 'Cleaning Ended',
    dismissal_date: Math.floor(Date.now() / 1000) + 5, // dismiss after 5s
    priority: 10,
  };

  // ...
}
```

> [!NOTE]
>
> Ces requêtes utilisent `priority: 10`, car chacune correspond à un changement de phase qui doit apparaître immédiatement, et une personne en reçoit au plus quelques-unes par jour. La priorité `10` est décomptée du budget qu'Apple accorde à chaque appareil pour les mises à jour de Live Activity. Pour tout ce qui se met à jour souvent, comme un score ou une barre de progression, commencez par `5`.

> [!WARNING]
>
> Envoyez les mises à jour et les fins à `/apps/{app_id}/live_activities/{activity_id}/notifications`, et non à l'endpoint de démarrage. Clean Beans envoyait au départ les trois à l'endpoint de démarrage, et chaque mise à jour et chaque fin étaient rejetées avec « Missing required parameter - event\_attributes ».

> [!NOTE]
>
> Attribuez à chaque activité son propre `activity_id` et enregistrez-le au démarrage de l'activité. OneSignal n'accepte plus de mises à jour pour un `activity_id` une fois l'activité terminée, un ID fixe par utilisateur cesserait donc de fonctionner après le premier jour.

> [card] [Configuration multiplateforme](https://documentation.onesignal.com/docs/fr/cross-platform-live-activity-setup.md)
>
> `setupDefault` et l'extension de widget.

> [card] [Démarrer une Live Activity](https://documentation.onesignal.com/reference/start-live-activity.md)
>
> L'API push-to-start.

> [card] [Mettre à jour une Live Activity](https://documentation.onesignal.com/reference/update-live-activity-api.md)
>
> Requêtes de mise à jour et de fin.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.