Intégration API

Spécification OpenAPI de Forecast Signals API.

Cette documentation explique comment structurer et envoyer vos données de suivi vers l’API Forecast Signals.

Structure des évènements

Chaque évènement envoyé à l’API Forecast Signals doit respecter une structure précise au format JSON, composée de trois parties principales.

{
  "event_name": "",
  "event_properties": {
    "key": "value"
  },
  "user_properties": {
    "key": "value"
  }
}

Exemple d’appel via curl :

curl -X POST https://forecast.example.com/action/v1 \
  -H "Content-Type: application/json" \
  -H "X-Forecast-Client-Key: votre_cle_client" \
  -d '{
    "event_name": "account_creation",
    "event_properties": { ... },
    "user_properties": { ... }
  }'

Authentification

Certains évènements nécessitent une authentification via un header HTTP :

Header	Type	Description
`X-Forecast-Client-Key`	`string`	Clé client requise pour certains types d’évènements (ex: `home_content`).

Champs de base

Champ	Type	Description
`event_name`	`string`	Nom de l’évènement.
`event_properties`	`object`	Données liées à l’évènement suivi. La liste des propriétés possibles est indiquée ci-dessous.
`user_properties`	`object`	Données liées au profil de l’utilisateur. La liste des propriétés possibles est indiquée ci-dessous.

Propriétés de l’évènement

L’objet event_properties contient les données liées à l’évènement suivi. Chaque évènement n’utilise qu’une partie de ces propriétés.

Liste complète des propriétés disponibles :

Propriété	Type	Description
`articleId`	`string`	Identifiant de l’article associé à l’évènement.
`articleIdBag`	`array`	Liste des identifiants d’articles, triés par position d’affichage (du haut vers le bas, de gauche à droite).
`c`	`string`	Consentement de l’utilisateur pour le traitement des données personnelles.
`ca`	`string`	Consentement de l’utilisateur pour le traitement des données à des fins publicitaires.
`clickedArticleId`	`string`	Identifiant de l’article ayant reçu un clic.
`clientId`	`string`	Identifiant client utilisé pour identifier l’usage du service.
`cm`	`string`	Consentement de l’utilisateur pour le traitement des données à des fins statitistiques. Valeurs possibles : `exempt`, `optin`, `optout`.
`countryCode`	`string`	Code pays (ISO 3166-1). Calculé automatiquement si non fourni.
`customlead`	`string`	Identifiant personnalisé du lead. Incompatible avec `l`.
`device`	`string`	Type d’appareil utilisé.
`displayedArticleIdBag`	`array`	Liste des identifiants d’articles affichés, ordonnés par temps d’affichage.
`du`	`string`	URL du document web.
`editionId`	`string`	Identifiant de l’édition.
`formula`	`string`	Identifiant de l’offre d’abonnement.
`globalId`	`string`	Identifiant global Sirius de l’article.
`isArticleUnlocked`	`boolean`	Indique si l’article est déverrouillé dans le contexte actuel.
`isVoluntary`	`boolean`	Indique si l’utilisateur s’est désabonné volontairement.
`l`	`string`	Identifiant du lead. Incompatible avec `customlead`.
`lang`	`string`	Langue de l’article.
`lastArticleUrl`	`string`	Dernière URL d’article (payant ou gratuit) consultée avant l’évènement.
`lastTeaserUrl`	`string`	Dernière URL d’article payant consultée avant l’évènement.
`navigationType`	`string`	Type de navigation. Valeurs possibles : `navigate`, `reload`, `back_forward`. Référence : MDN.
`pt`	`string`	Type de page. Valeurs possibles : `article`, `home`, `search`, `search_results`.
`placementId`	`string`	Identifiant de l’emplacement du widget.
`r`	`number`	Taux de lecture de l’article par le lead (de 0 à 100).
`reason_code`	`string`	Code du motif de désabonnement.
`ref`	`string`	URL de provenance (referer).
`source`	`string`	Source d’origine de l’évènement.
`subdivisionCode`	`string`	Code de subdivision (ISO 3166-2). Calculé automatiquement si non fourni.
`t`	`integer`	Temps de lecture de l’article par le lead (en secondes).
`u`	`string`	URL de la page.
`zoneBag`	`array`	Tableau d’objets représentant les zones. Chaque objet contient : `articleIdBag` (array of strings) et `zoneId` (string).
`zoneId`	`string`	Identifiant de la Tracking Zone.

Propriétés de l’utilisateur

L’objet user_properties regroupe les informations relatives au profil de l’utilisateur. Comme pour les propriétés d’évènement, chaque évènement n’en requiert qu’un sous-ensemble.

Liste complète des propriétés disponibles :

Propriété	Type	Description
`countryCode`	`string`	Code pays de l’utilisateur.
`custom_id_1`	`string`	Identifiant personnalisé 1.
`custom_id_2`	`string`	Identifiant personnalisé 2.
`custom_id_3`	`string`	Identifiant personnalisé 3.
`custom_id_4`	`string`	Identifiant personnalisé 4.
`fbci`	`string`	Identifiant client Facebook.
`formulaCode`	`string`	Code de l’offre d’abonnement.
`formulaIsForStudent`	`string`	Indique si l’offre est destinée aux étudiants.
`formulaIsPromoOffer`	`string`	Indique si l’offre est une promotion.
`gaci`	`string`	Identifiant client Google Analytics.
`subscriptionApp`	`string`	Application d’abonnement.
`subscriptionCardExpirationDate`	`string`	Date d’expiration de la carte d’abonnement.
`subscriptionDevice`	`string`	Appareil d’abonnement.
`subscriptionSource`	`string`	Source de l’abonnement.
`uid`	`string`	Identifiant de l’utilisateur.
`uis`	`string`	Indique si l’utilisateur est un abonné.
`used`	`string`	Date de fin d’abonnement (format date-time).
`usod`	`string`	Date de commande de l’abonnement (format date-time).
`ussd`	`string`	Date de début d’abonnement (format date-time).
`zipCode`	`string`	Code postal de l’utilisateur.

Catalogue des évènements

Cette section liste les évènements disponibles et les propriétés spécifiques à chacun.

Note

Cette liste n’est pas exhaustive et est en cours de documentation.

Création de compte

L’évènement account_creation doit être envoyé lors de la création d’un compte utilisateur.

Nom de l’évènement

account_creation

Propriétés de l’évènement

c, ca, clientId, cm, device, du, l ou customlead, lang, navigationType, ref, source, u.

Propriétés de l’utilisateur

uid, uis.

Contenu de la page d’accueil

L’évènement home_content suit l’affichage des contenus sur la page d’accueil. Il nécessite l’envoi du header HTTP X-Forecast-Client-Key.

Nom de l’évènement

home_content

Propriétés de l’évènement

zoneBag, clientId, editionId.

Propriétés de l’utilisateur

Aucune propriété utilisateur n’est nécessaire pour cet évènement.

Impression d’une zone de tracking

L’évènement widget_impression suit l’affichage d’une zone de tracking.

Nom de l’évènement

widget_impression

Propriétés de l’évènement

articleId, articleIdBag, c, ca, clientId, cm, device, du, l ou customlead, lang, navigationType, pt, ref, u, zoneId.

Propriétés de l’utilisateur

uid, uis.

Clic dans une zone de tracking

L’évènement widget_click suit le clic dans une zone de tracking.

Nom de l’évènement

widget_click

Propriétés de l’évènement

articleId, clickedArticleId, c, ca, clientId, cm, device, displayedArticleIdBag, du, l ou customlead, lang, navigationType, pt, ref, u, zoneId.

Propriétés de l’utilisateur

uid, uis.

Consultation d’une page

L’évènement pageview doit être envoyé lors de la consultation d’une page.

Nom de l’évènement

pageview

Propriétés de l’évènement

c, ca, clientId, cm, device, du, l ou customlead, lang, navigationType, pt, ref, u.

Propriétés de l’utilisateur

uid, uis.

Consultation d’une page article

L’évènement pageview doit être envoyé lors de la consultation d’une page article.

Nom de l’évènement

pageview

Propriétés de l’évènement

c, ca, clientId, cm, device, du, globalId, isArticleUnlocked, l ou customlead, lang, navigationType, pt, ref, u.

Propriétés de l’utilisateur

uid, uis.

Lecture d’un article

L’évènement read doit être envoyé lors de la lecture d’un article.

Nom de l’évènement

read

Propriétés de l’évènement

c, ca, clientId, cm, device, du, globalId, isArticleUnlocked, l ou customlead, lang, navigationType, pt, r, ref, t, u.

Propriétés de l’utilisateur

uid, uis.

Conversion

L’évènement conversion doit être envoyé lors d’une conversion (abonnement).

Nom de l’évènement

conversion

Propriétés de l’évènement

c, ca, clientId, cm, device, du, formula, l ou customlead, lang, lastArticleUrl, lastTeaserUrl, navigationType, ref, u.

Propriétés de l’utilisateur

uid, uis.

Accès au tunnel

L’évènement tunnel_access doit être envoyé lors de l’accès au tunnel d’achat.

Nom de l’évènement

tunnel_access

Propriétés de l’évènement

c, ca, clientId, cm, device, du, formula, l ou customlead, lang, lastArticleUrl, lastTeaserUrl, navigationType, ref, u.

Propriétés de l’utilisateur

uid, uis.

Commentaire

L’évènement comment doit être envoyé lorsqu’un utilisateur poste un commentaire.

Nom de l’évènement

comment

Propriétés de l’évènement

c, ca, clientId, cm, device, du, globalId, isArticleUnlocked, l ou customlead, lang, navigationType, pt, ref, u.

Propriétés de l’utilisateur

uid, uis.

Partage

L’évènement share doit être envoyé lorsqu’un utilisateur partage un contenu.

Nom de l’évènement

share

Propriétés de l’évènement

c, ca, clientId, cm, device, du, globalId, isArticleUnlocked, l ou customlead, lang, navigationType, pt, ref, u.

Propriétés de l’utilisateur

uid, uis.

Réception d’un cadeau

L’évènement gift_receive doit être envoyé lors de la réception d’un article offert.

Nom de l’évènement

gift_receive

Propriétés de l’évènement

c, ca, clientId, cm, device, du, globalId, l ou customlead, lang, navigationType, pt, ref, u.

Propriétés de l’utilisateur

uid, uis.

Partage d’un cadeau

L’évènement gift_share doit être envoyé lors du partage d’un article offert.

Nom de l’évènement

gift_share

Propriétés de l’évènement

c, ca, clientId, cm, device, du, globalId, l ou customlead, lang, navigationType, pt, ref, u.

Propriétés de l’utilisateur

uid, uis.

Désabonnement effectif

L’évènement unsubscribe_effective doit être envoyé lorsque le désabonnement est effectif.

Nom de l’évènement

unsubscribe_effective

Propriétés de l’évènement

c, ca, clientId, cm, device, du, l ou customlead, isVoluntary, lang, navigationType, reason_code, ref, u.

Propriétés de l’utilisateur

uid, uis.

Demande de désabonnement

L’évènement unsubscribe_request doit être envoyé lors d’une demande de désabonnement.

Nom de l’évènement

unsubscribe_request

Propriétés de l’évènement

c, ca, clientId, cm, device, du, l ou customlead, lang, navigationType, ref, source, u.

Propriétés de l’utilisateur

uid, uis.

Changement du consentement

L’évènement consent_change doit être envoyé lors d’un changement de consentement.

Nom de l’évènement

consent_change

Propriétés de l’évènement

c, ca, clientId, cm, du, l ou customlead, navigationType, u.

Propriétés de l’utilisateur

uid, uis.