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 quatre parties principales.

{
  "event_type": "",
  "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_type": "lead",
    "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_type`	`string`	Type de l’événement (`article`, `lead` ou `page`).
`event_name`	`string`	Nom spécifique de l’événement.

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.
`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.

Champs de base

event_type : lead
event_name : account_creation

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

c, ca, clientId, device, du, l ou customlead, 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.

Champs de base

event_type : page
event_name : 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.

Champs de base

event_type : lead
event_name : 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.

Champs de base

event_type : lead
event_name : 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.