Flux de données

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.

• Le solde de récompenses actuel d’un utilisateur
• Le dernier statut de commande
• Des recommandations de produits personnalisées

​

Comment fonctionnent les flux de données

1. Créez un flux de données – Configurez la façon dont OneSignal se connecte à votre API.
2. Attachez le flux de données à un modèle de message.
3. Insérez les champs de réponse dans votre message en utilisant la syntaxe Liquid.
4. Au moment de l’envoi, OneSignal effectue un appel API pour chaque destinataire, analyse la réponse et injecte les données dans votre message.

​

Exemple : Afficher les points de récompense

Hi {{ first_name }},

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

Keep shopping to earn more points!

​

Création et utilisation d’un flux de données

​

1. Configurez votre flux de données

• Nom : Un nom descriptif comme « API de récompenses client » pour vous aider à distinguer les flux. Les noms uniques sont recommandés mais pas obligatoires.
• Alias : Un identifiant court comme rewards utilisé dans la syntaxe Liquid (par ex., {{ data_feed.rewards.points }}). Doit être unique, en minuscules, alphanumérique, sans espaces ni caractères spéciaux.
• Méthode : La méthode HTTP que OneSignal utilise pour contacter votre API. Généralement GET, mais POST est également pris en charge.
• URL : Votre point de terminaison API. Prend en charge la syntaxe Liquid afin que OneSignal puisse récupérer des données spécifiques à l’utilisateur.

https://acme.com/customers/user_id={{ external_id }}/rewards

• En-têtes : Paires clé-valeur requises par votre API (par ex., jetons d’authentification). Prend en charge la syntaxe Liquid.
• Corps : Corps de requête JSON optionnel. Prend en charge la syntaxe Liquid, comme les webhooks Journey.

{
	"customer_id": "{{ subscription.external_id }}"
}

​

2. Attachez le flux de données à votre modèle de message

1. Accédez à Messages > Templates
2. Dans la section Message, sélectionnez le bouton Personalization

3. Activez Data Feeds et sélectionnez votre flux

4. Enregistrez votre modèle

​

3. Utilisez les données dans votre message

{
	"external_id": "a1-b2c3",
	"points": 193,
	"status_level": "Gold"
}

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

• Utiliser un flux de données
• Utiliser le flux de données rewards
  • Rappel : le flux rewards sait appeler l’API avec l’external_id du destinataire
• À partir de la réponse, insérer la valeur de l’élément points (193) et de l’élément status_level (Gold)

​

Exigences et limites

• Accepter l’authentification en une seule étape avec des jetons d’authentification dans les en-têtes
• Répondre rapidement. Moins de 250 ms recommandé (cela affecte directement la vitesse d’envoi)
• Renvoyer du JSON. Les autres formats ne sont pas pris en charge pour le moment.
  • Si vous avez besoin d’un format différent, partagez votre cas d’utilisation.
• Gérer votre volume d’envoi. Une limite de taux faible sur votre API ralentit la livraison des messages.
• Renvoyer des charges utiles de taille raisonnable. Maintenez les réponses sous 50 Ko pour de meilleures performances.

• Un flux de données par modèle. Récupérez tout ce dont vous avez besoin en une seule réponse API.
• Un appel API par flux de données par message.
• Journeys uniquement. Pas encore disponible pour d’autres méthodes d’envoi.
• Pas d’enchaînement d’appels. La charge utile d’un flux de données ne peut pas être utilisée pour appeler un autre.

​

Configuration de votre API

​

Authentification

Authorization: Bearer YOUR_TOKEN

X-API-Key: YOUR_KEY

​

Corps de requête JSON

​

Réponse JSON

​

Paramètres de personnalisation

https://api.example.com/users/{{external_id}}/data
https://api.example.com/rewards?email={{email | url_encode}}

{
	"customer_id": "{{ external_id }}",
	"email": "{{ subscription.email }}"
}

​

Limites de taux

​

Gestion des erreurs

​

Liste de contrôle de démarrage

• Quelles données veux-je afficher dans mon message ? Travailler à rebours à partir d’un simple plan avec les éléments à remplir depuis votre API identifiés vous aidera à organiser votre réflexion.
• Ces données sont-elles disponibles via un seul point de terminaison API ?
• Comment vais-je authentifier les requêtes API ?
• Quel identifiant ou autre élément de données vais-je utiliser pour récupérer les données personnalisées ?
• Cet identifiant est-il déjà stocké dans OneSignal ? Si non, comment sera-t-il rempli ?
• Mon API peut-elle gérer le volume de requêtes que je vais générer ?
• Que se passe-t-il si mon API n’a pas de données pour un utilisateur ?

​

Exemples et cas d’utilisation avancés

• Iterating with loops: abandoned cart
• Custom events properties
• Conditional display: order status
• Automation without personalization
• Personalized coupon codes

Disons que vous avez un flux de données cart qui renvoie un tableau d’articles dans le panier de l’utilisateur, plus le montant total du panier en dollars :

{
  "items": [
    {
      "name": "Blue Running Shoes",
      "price": 84.00,
      "image_url": "https://acme.com/blue-running-shoes.png"
    },
    {
      "name": "Protein Bar",
      "price": 5.99,
      "image_url": "https://acme.com/protein-bar.png"
    }
  ],
  "total": 89.99
}

Si vous voulez afficher chaque article dans le panier, plus le total du panier, vous pouvez utiliser une boucle for en Liquid :

<ul>
  {% for item in data_feed.cart.items %}
    <li>
      <strong>{{ item.name }}</strong><br>
      ${{ item.price }}<br>
      <img src="{{ item.image_url }}" alt="{{ item.name }}">
    </li>
  {% endfor %}
</ul>

<p>Cart total: ${{ data_feed.cart.total }}</p>

Cela donnera :

- Blue Running Shoes
- $84.00
- <running shoes image>
- Protein Bar
- $5.99
- <protein bar image>
Cart total: $89.99

Si vous utilisez l’éditeur de blocs d’e-mail, lors de l’insertion de ce type de syntaxe Liquid complexe, en particulier si vous devez inclure des images ou des liens, pour de meilleurs résultats, utilisez l’élément de bloc HTML personnalisé.

Vous voulez voir comment déclencher cet e-mail de panier abandonné à l’aide d’événements personnalisés ? Consultez l’onglet Propriétés d’événements personnalisés pour le flux de travail complet.

En poursuivant l’exemple précédent du panier abandonné, comment pourrions-nous savoir comment récupérer ce panier particulier en premier lieu ?Une méthode pourrait être de créer un Journey déclenché par un événement personnalisé cart_abandoned, où les propriétés incluent un cart_id. Dans cet exemple, cet événement est envoyé à OneSignal via API :

curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Accept: application/json' \
  --data '{
  "events": [
    {
      "name": "cart_abandoned",
      "external_id": "user_12345",
      "properties": {
        "cart_id": 98765
      }
    }
  ]
}'

L’utilisateur user_12345 entre dans le journey lorsque cet événement est déclenché, puis atteint un nœud envoyant un e-mail. Ce modèle d’e-mail est configuré avec le flux de données cart, où l’URL est définie pour récupérer le contenu d’un panier particulier comme ceci :

https://acme.com/carts/{{ journey.event.cart_abandoned.data.cart_id }}

Ainsi, lorsque cet événement particulier est ingéré et déclenche le Journey :

1. La valeur cart_id de 98765 sera stockée dans le Journey
2. Lorsque l’étape d’e-mail est atteinte, le flux de données cart référencera cette valeur cart_id et l’utilisera pour appeler l’API du panier
3. Les propriétés JSON renvoyées seront analysées et insérées dans l’e-mail comme dans l’exemple précédent ci-dessus

Vous voulez voir comment afficher conditionnellement le contenu du flux de données selon le statut de commande ? Consultez l’onglet Affichage conditionnel : statut de commande pour en savoir plus.

Disons que vous voulez inclure le statut de la commande d’un client, mais n’inclure un lien de numéro de suivi que si la commande a été expédiée. Vous pouvez utiliser une instruction if pour ce faire :

Your order is {{data_feed.order.status}}!

{% if data_feed.order.tracking_number != empty %}
Track it here: {{data_feed.order.tracking_url}}
{% endif %}

Ici, le lien de suivi ne sera affiché que si le tracking_number existe.

Les flux de données peuvent être utilisés pour insérer automatiquement des informations à jour dans vos messages sans nécessairement avoir besoin d’être personnalisés par destinataire.Par exemple, vous insérez peut-être une image de bannière en haut de vos e-mails et la changez mensuellement pour suivre les fêtes et autres événements mensuels. Plutôt que de vous souvenir de télécharger une nouvelle image sur OneSignal et de modifier tous vos modèles chaque mois, vous pourriez configurer un flux de données qui récupère l’URL de l’image de bannière actuelle depuis votre CMS ou autre emplacement de gestion d’actifs.Vous configureriez un flux de données banner qui pointe vers un point de terminaison sans aucune variable dans l’URL comme ceci :

https://acme.com/assets/email-banner

Ce qui renvoie une réponse avec l’URL de la bannière actuelle :

{
	"banner_url": "https://acme.com/assets/email-banner/2025july.png"
}

Vous configureriez votre modèle d’e-mail pour utiliser {{ data_feed.banner.banner_url }} comme URL source de l’image, automatisant ce processus à l’avenir.

Cet exemple explique comment envoyer des codes de réduction personnalisés à usage unique dans des e-mails à l’aide d’un flux de données qui récupère une valeur unique de votre API pour chaque destinataire.

​

Objectif

Envoyer un e-mail tel que :

Bonjour George, Finalisez votre réservation dans les 2 prochaines heures et économisez 10 % avec votre code personnel : XYZ123ABC

Chaque utilisateur reçoit un code de réduction unique, généré en direct via un appel API externe au moment de l’envoi de l’e-mail, valide pour la fenêtre de temps donnée et limité à cet utilisateur.

​

Prérequis

• Canal e-mail configuré dans OneSignal (votre application a la fonctionnalité e-mail activée)
• Une API externe qui accepte un identifiant utilisateur (par exemple, external_id) et un identifiant de campagne, et renvoie du JSON avec le code de réduction, la remise et l’expiration
• Un identifiant unique (tel que external_id) pour chaque utilisateur que votre API peut utiliser pour générer des codes de réduction
• Un segment ou un déclencheur (par exemple, « recherche abandonnée au cours des dernières 24 h ») utilisé pour envoyer l’e-mail via un Journey OneSignal

​

Étape 1 : Créer le flux de données

1

Navigate to Data Feeds

Dans votre application OneSignal, sélectionnez Data feeds dans la barre de navigation, puis cliquez sur New data feed.

2

Configure the Data Feed

Configurez les champs suivants :

• Data Feed Name : coupon_code_generator
• Alias : coupon
• Method : GET
• URL : https://api.example.com/generate-coupon?userId={{ external_id }}&campaign=AbandonedBooking10
• Headers :
  {
    "Authorization": "Bearer YOUR_API_TOKEN"
  }
  

3

Reference the API response

Lorsque l’API renvoie du JSON comme ceci :

{
  "code": "AB10-5F3K-HT9L",
  "discount_percent": "10%",
  "expires_in_hours": 2
}

Vous pouvez référencer ses valeurs dans votre modèle d’e-mail comme suit :

• {{ data_feed.coupon.code }}
• {{ data_feed.coupon.discount_percent }}
• {{ data_feed.coupon.expires_in_hours }}

4

Test and activate the Data Feed

Cliquez sur Send Test pour vérifier votre configuration, puis cliquez sur Activate pour rendre le flux de données disponible pour une utilisation dans les modèles.

​

Étape 2 : Créer le modèle d’e-mail

1. Dans OneSignal, allez dans Messages → Email → New Template
2. Utilisez l’alias et les champs du flux de données dans le corps de votre message. Par exemple :

<h2>Hi {{ first_name }},</h2>
<p>
Complete your booking in the next {{ data_feed.coupon.expires_in_hours }} hours and save
{{ data_feed.coupon.discount_percent }} with your personal code:
<strong>{{ data_feed.coupon.code }}</strong>
</p>

<p><a href="https://example.com/checkout?coupon={{ data_feed.coupon.code }}">Use Code Now →</a></p>

• Utilisez la syntaxe Liquid sous la forme {{ data_feed.<alias>.<field> }}
• Assurez-vous que le flux de données est attaché au modèle
• Si vous utilisez l’éditeur glisser-déposer avec une logique Liquid personnalisée, utilisez un bloc HTML

​

Étape 3 : Attacher le flux de données et déclencher l’e-mail

1. Dans le compositeur de modèle, sous Personalization, activez Data Feeds et sélectionnez votre flux (coupon_code_generator)
2. Cela garantit que OneSignal effectue l’appel API au moment de l’envoi pour chaque destinataire, remplit les données et les injecte dans l’e-mail
3. Configurez un Journey pour automatiser le message :
   • Condition d’entrée : Segment tel que « recherche abandonnée au cours des dernières 24 heures »
   • Attendre jusqu’à : Créez un événement personnalisé booking_completed. Configurez l’attente pour quitter le Journey si cet événement se déclenche, ou continuer après 1 heure. S’ils finalisent une réservation, ils sortent sans recevoir l’e-mail ; sinon, ils continuent à recevoir le code de réduction.
   • Envoyer l’e-mail : Utilisez le modèle d’e-mail de code de réduction personnalisé
   • Assurez-vous que le Journey utilise le canal e-mail et que les destinataires sont abonnés à l’e-mail

​

Étape 4 : Gérer l’utilisation et le suivi des codes de réduction

Votre backend doit :

1. Enregistrer chaque code généré avec userId, code, campaign, expiration_time et un indicateur redeemed
2. Valider et marquer les codes comme utilisés lors du paiement
3. Journaliser les données d’utilisation (utilisateur, campagne et heure) pour l’analyse du ROI

​

Exemple de flux de travail complet

Étape	Événement	Action
1	L’utilisateur déclenche le segment « recherche abandonnée »	L’utilisateur entre dans le Journey via le segment
2	Le Journey déclenche l’envoi de l’e-mail	OneSignal attache le flux de données, appelle votre API avec l’external_id de l’utilisateur et le nom de la campagne
3	L’API renvoie du JSON	OneSignal remplit les champs du flux de données de code de réduction et envoie l’e-mail
4	L’utilisateur reçoit l’e-mail	Exemple : « Bonjour George ! Économisez 10 % avec votre code personnel : AB10-5F3K-HT9L »
5	L’utilisateur utilise le code	Le backend valide et journalise l’utilisation

​

Tests

• Testez avec un utilisateur ayant un external_id connu
• Appelez votre API manuellement pour confirmer des réponses JSON correctes
• Utilisez Preview dans l’éditeur de modèles OneSignal pour vérifier que les champs du flux de données de code de réduction se remplissent
• Vérifiez les journaux API pour la latence et les erreurs
• Si un appel de flux de données échoue, OneSignal ignorera l’envoi du message à ce destinataire

​

FAQ

​

Mes valeurs de flux de données n’apparaissent pas dans le message. Que dois-je vérifier ?

1. Le flux de données est attaché au modèle (sous Personalization > Data Feeds).
2. Votre syntaxe Liquid correspond exactement à la structure de la réponse JSON — {{ data_feed.<alias>.<field> }}.
3. Le point de terminaison API renvoie du JSON valide lorsqu’il est appelé manuellement avec les mêmes identifiants.
4. Le destinataire dispose de l’identifiant requis (par ex., external_id) stocké dans OneSignal.

​

Pourquoi les messages s’envoient-ils lentement ?

​

Pourquoi certains destinataires ne reçoivent-ils pas de messages ?

​

Puis-je utiliser plus d’un flux de données dans un modèle ?

​

Les flux de données sont-ils disponibles pour les notifications push ou les SMS ?

​

Que se passe-t-il si mon API est indisponible au moment de l’envoi du message ?

​

Pages associées