> ## 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 : e-mail hebdomadaire avec custom_data

> Comment l'application d'exemple Clean Beans envoie un rapport hebdomadaire par e-mail personnalisé pour chaque destinataire avec custom_data et Liquid, et comment cela se compare aux Data Feeds.

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.

Chaque dimanche, chaque foyer reçoit un e-mail récapitulant sa semaine : sessions, tâches, minutes, un classement et les chiffres de chaque personne.

![L'e-mail du rapport hebdomadaire de Clean Beans](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-email.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=386b96883e6b7af79d0406d4095f73c7)

Le rapport hebdomadaire : totaux du foyer, votre propre semaine et le classement.

Le point intéressant est la personnalisation. Tout le monde dans un foyer voit le même classement, mais chacun doit voir son propre nom et ses propres statistiques. Envoyer une requête par personne fonctionnerait, mais il existe une meilleure méthode.

## Une requête par foyer, personnalisée pour chaque personne \\

La fonction envoie **une** requête par foyer. Elle transmet toutes les données dans `custom_data`, y compris un objet `users` indexé par External ID. Le modèle sélectionne ensuite la bonne entrée pour la personne à qui il est destiné.

```typescript supabase/functions/weekly-report/index.ts theme={null}
const customData = {
  household_name: householdNames[householdId] || 'Your Household',
  week_label: weekLabel,
  household_sessions: String(householdSessions.length),
  household_tasks: String(totalTasks),
  household_mins: String(totalMins),
  top_room: topRoom,
  leaderboard,
  users,
};

    // ...

const onesignalPayload: Record<string, unknown> = {
  app_id: ONESIGNAL_APP_ID,
  template_id: ONESIGNAL_WEEKLY_TEMPLATE_ID,
  include_aliases: {
    external_id: externalIds,
  },
  target_channel: 'email',
  custom_data: customData,
};
```

Dans le modèle, une ligne de Liquid sélectionne les données du destinataire actuel.

```liquid email-templates/weekly-report.html theme={null}
{% assign user = message.custom_data.users[subscription.external_id] %}
{% assign lb = message.custom_data.leaderboard %}
```

Ensuite, `user` contient les statistiques de cette personne, et tout ce qui est lu directement dans `message.custom_data` est commun au foyer.

```liquid email-templates/weekly-report.html theme={null}
Hey {{ user.name | default: "there" }}! 👋
Here's how <strong>{{ message.custom_data.household_name | default: "your household" }}</strong> did this week.

{% for member in lb %}
  {% if forloop.index == 1 %}🥇{% elsif forloop.index == 2 %}🥈{% elsif forloop.index == 3 %}🥉{% else %}{{ forloop.index }}{% endif %}
  {{ member.name }}{% if member.name == user.name %} (you){% endif %}
{% endfor %}
```

> [!NOTE]
>
> Le second exemple Liquid est une version simplifiée du modèle, qui montre la logique sans le balisage du tableau.

## Rester sous la limite de taille \\

Le `custom_data` pour l'e-mail est limité à 10 Ko. Un grand foyer pourrait dépasser cette limite, la fonction mesure donc le payload et raccourcit le classement si nécessaire.

```typescript supabase/functions/weekly-report/index.ts theme={null}
// Check payload size (10KB limit for email)
const payloadSize = new TextEncoder().encode(JSON.stringify(customData)).length;
if (payloadSize > 10000) {
  console.warn(`Household ${householdId} custom_data is ${payloadSize} bytes (over 10KB limit). Trimming leaderboard.`);
  customData.leaderboard = customData.leaderboard.slice(0, 5);
}
```

## Planification et préférences \\

Une planification hebdomadaire appelle la fonction chaque dimanche à 09:00 UTC, avec le même principe `pg_cron` que les rappels push et l'expression `0 9 * * 0`. Seuls les utilisateurs ayant activé **Weekly Email Summary** sont inclus.

**Configuration du tableau de bord.** Dans **Messages > Templates**, créez un modèle d'e-mail, collez-y le HTML et copiez l'ID du modèle dans les secrets de votre backend. `custom_data` ne fonctionne qu'avec un modèle, `template_id` est donc obligatoire.

## L'alternative : les Data Feeds \\

Il existe une seconde façon d'intégrer des données propres à chaque personne dans un e-mail, et Clean Beans a choisi de ne pas l'utiliser. Elle mérite d'être comprise, car pour certaines applications elle est plus adaptée.

Avec `custom_data`, votre backend **pousse** les données vers OneSignal au moment de l'envoi. Avec un **Data Feed**, OneSignal **récupère** les données depuis votre API au moment où chaque e-mail est envoyé. L'envoi lui-même est lancé par un Journey, et non par votre backend.

> [!NOTE]
>
> Les exemples de cette sous-section sont illustratifs. Ils montrent comment le rapport hebdomadaire aurait été construit avec un Data Feed. Ils ne sont pas tirés de l'application.

Voici comment le rapport hebdomadaire aurait fonctionné.

**1. Exposer un endpoint qui renvoie la semaine d'une personne**

Une fonction backend reçoit un ID utilisateur et renvoie en JSON les statistiques de cet utilisateur et le classement de son foyer.

```json Response from your API theme={null}
{
  "name": "George",
  "household_name": "The Smiths",
  "week_label": "Nov 10 – Nov 16",
  "sessions": 5,
  "tasks": 19,
  "mins": 63,
  "streak": 24,
  "leaderboard": [
    { "name": "George", "sessions": 5, "mins": 63 },
    { "name": "Jonny", "sessions": 4, "mins": 52 }
  ]
}
```

**2. Créer le Data Feed dans le tableau de bord**

Dans **Settings > Data feeds**, donnez un alias au feed et faites-le pointer vers l'endpoint. L'URL et les en-têtes acceptent le Liquid, l'External ID du destinataire peut donc être transmis.

```text Data Feed configuration theme={null}
Alias:   weekly
Method:  GET
URL:     https://YOUR_PROJECT_REF.supabase.co/functions/v1/weekly-stats?user_id={{ external_id }}
Headers: { "Authorization": "Bearer YOUR_FEED_SECRET" }
```

**3. Associer le feed au modèle d'e-mail et y lire les données**

Dans le modèle, les valeurs proviennent de `data_feed`, suivi de l'alias.

```liquid Email template theme={null}
Hey {{ data_feed.weekly.name | default: "there" }}!
Here's how {{ data_feed.weekly.household_name }} did this week.

{% for member in data_feed.weekly.leaderboard %}
  {{ member.name }}: {{ member.sessions }} sessions
{% endfor %}
```

**4. L'envoyer depuis un Journey récurrent**

Un Journey dont la première étape est une fenêtre horaire le dimanche matin, avec une règle de réentrée, envoie le modèle chaque semaine. Aucun code de planification ni d'envoi ne se trouve dans votre backend.

### Laquelle utiliser \\

| | `custom_data` (ce qu'utilise Clean Beans) | Data Feeds |
| - | - | - |
| Qui lance l'envoi | Votre backend, en appelant l'API | Un Journey dans le tableau de bord |
| Quand les données sont lues | Quand votre backend construit la requête | Quand chaque message est envoyé |
| Requêtes pour un foyer de quatre personnes | Une requête vers OneSignal | Quatre appels de OneSignal vers votre API |
| Canaux | Push, e-mail et SMS | E-mail et SMS, uniquement dans les Journeys |
| Limite de taille | 10 Ko pour l'e-mail | Des réponses d'environ 50 Ko maximum sont recommandées |
| Si les données manquent | Votre code décide quoi faire | Ce destinataire ne reçoit aucun message |
| Modifier la planification ou le parcours | Une modification du backend | Une modification dans le tableau de bord |
| Exposition de votre API | Rien n'est exposé | Un endpoint public que vous devez sécuriser et garder rapide |

**Choisissez `custom_data` lorsque votre backend est déjà celui qui décide d'envoyer.** C'est le cas du rapport hebdomadaire. Le backend s'exécute selon une planification, sait quels foyers ont donné leur accord et dispose de tous les chiffres, transmettre les données ne coûte donc rien de plus. Une requête couvre tout un foyer, il n'y a aucun endpoint à protéger et une erreur apparaît dans vos propres journaux. La contrepartie est que le moment et l'audience sont définis dans le code, et que le payload a une limite de taille fixe.

**Choisissez un Data Feed lorsque l'envoi relève d'un Journey.** Un Journey décide lui-même quand envoyer un message à quelqu'un, plusieurs jours après un événement ou une fois une condition d'attente remplie, et votre backend n'est pas là pour fournir les données à ce moment-là. Un Data Feed comble ce manque, et il permet aux personnes qui gèrent la messagerie de modifier la planification, d'ajouter une branche ou de tester des variantes sans déploiement. La contrepartie est que votre API est appelée une fois par destinataire et doit répondre en environ un quart de seconde, que chaque modèle ne peut utiliser qu'un seul feed et qu'un appel en échec signifie que la personne ne reçoit rien, sans avertissement.

Pour Clean Beans, les critères décisifs étaient simples. Le backend disposait déjà des données et de la planification, le classement est commun à un foyer, une seule requête coûte donc bien moins cher qu'un appel par personne, et les préférences sont stockées dans la base de données de l'application, où le backend peut les vérifier directement.

> [card] [Personnaliser avec custom\_data](https://documentation.onesignal.com/docs/fr/personalization-api-custom-data.md)
>
> Limites de taille et modèles d'accès Liquid.

> [card] [Data feeds](https://documentation.onesignal.com/docs/fr/data-feeds.md)
>
> Intégrer des données en temps réel dans les e-mails et SMS des Journeys.

> [card] [Utiliser la syntaxe Liquid](https://documentation.onesignal.com/docs/fr/using-liquid-syntax.md)
>
> Filtres, boucles et conditions.


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