Documentation

• Clé

  Code de suivi (navigateur)

  pk_, publique, dans la page

  API serveur

  sk_, secrète, sur ton serveur

• source

  Code de suivi (navigateur)

  browser

  API serveur

  server

• Déclenche un postback d'affiliation

  Code de suivi (navigateur)

  Non

  API serveur

  Oui

• ip et user_agent

  Code de suivi (navigateur)

  Lus par Oriva sur la connexion

  API serveur

  À fournir toi-même (ceux du visiteur)

Une clé pk_ ne peut envoyer que des événements browser, une clé sk_ que des événements server. Le postback d'affiliation n'est déclenché que par une vente serveur : une clé publique est visible par tous, elle ne doit pas pouvoir créer une commission.

Tu le trouves, déjà rempli avec ton sous-domaine et ta clé, dans l'étape « Code de suivi » de ton espace. Il charge oriva.js depuis ton sous-domaine de suivi (t.<ton-domaine>) et expose une fonction, oriva(commande, …). Tu peux l'appeler avant que le script soit chargé : les appels sont mis en file et rejoués.

<script async src="https://t.<ton-domaine>/oriva.js"></script>
<script>window.oriva=window.oriva||function(){(oriva.q=oriva.q||[]).push(arguments)};oriva('init',{key:'pk_…'});</script>

oriva('init', options)

Déjà présent dans le code fourni. Envoie un page_view au chargement.

• key

  Rôle

  Ta clé pk_. Obligatoire.

• host

  Rôle

  Le sous-domaine de suivi. Par défaut, celui d'où oriva.js est chargé.

• page_view

  Rôle

  false pour ne pas envoyer le page_view automatique.

oriva('consent', { ads })

Oriva démarre sans consentement publicitaire. Tant que tu n'as pas appelé oriva('consent', { ads: true }), les événements partent quand même, mais sans cookie visiteur, sans identifiant de clic, sans email ni téléphone, et rien n'est envoyé à Meta, TikTok, Google Ads ni ChatGPT Ads.

oriva('consent', { ads: false }) retire le consentement et efface le cookie visiteur. Le consentement n'est gardé qu'en mémoire : sur chaque page, ta bannière doit le redonner. Exemples pour Axeptio, Didomi, Cookiebot, tarteaucitron, Complianz et CookieYes.

oriva('identify', données)

Retient l'email, le téléphone ou d'autres données du visiteur pour tous les événements suivants de la page. Elles sont normalisées et hachées en SHA-256 dans le navigateur, avant de partir. À appeler avant un lead ou un purchase, par exemple quand le formulaire est envoyé.

oriva('identify', { email: 'jane@example.com', phone: '06 12 34 56 78' });

oriva('track', nom, données)

Envoie un événement.

oriva('track', 'purchase', {
  event_id: 'commande-1001',
  value: 49.9,
  currency: 'EUR',
  order_id: '1001',
  content_ids: ['sku-42'],
});

• event_id : ta référence stable. Sans elle, le code en génère une au hasard, et la même vente envoyée aussi par ton serveur sera comptée deux fois chez les plateformes.
• value : en unités, pas en centimes (49.9 veut dire 49,90 €).
• currency : code ISO à 3 lettres. Absent, Oriva prend la devise de ton domaine.
• user_data : comme identify, mais pour cet événement seulement.
• Toute autre clé part dans custom_data (voir ce qui en est transmis aux plateformes).

Sur purchase, un rafraîchissement de la page de remerciement renvoie le même event_id : la vente n'est pas comptée deux fois.

Ce que le code capte tout seul

Seulement avec le consentement publicitaire, au chargement de la page :

• les identifiants de clic dans l'URL : fbclid, ttclid, gclid, gbraid, wbraid, msclkid, aff_click_id, oppref ;
• les paramètres utm_source, utm_medium, utm_campaign, utm_content, utm_term ;
• subid, s1, s2, s3, s4, s5 ;
• les cookies des pixels déjà présents sur la page : _fbc, _fbp (Meta), _ttp, ttclid (TikTok), __oppref, __obref (OpenAI).

Tu n'as rien à faire pour ça.

POST https://t.<ton-domaine>/api/v1/collect
X-Oriva-Key: sk_…
Content-Type: application/json

Un événement par requête, avec les champs ci-dessous. Exemple complet et bonnes pratiques. Ta clé secrète reste sur ton serveur, dans une variable d'environnement.

Valables pour l'API serveur. Le code de suivi remplit lui-même event_id, source, occurred_at, url, referrer, consent, visitor_id et les identifiants de clic.

• event_id

  Obligatoire

  Oui

  Notes

  Texte, 128 caractères au plus. Unique par domaine : un second envoi avec le même event_id est accepté mais ignoré.

• name

  Obligatoire

  Oui

  Notes

  Un des événements, ou custom:<nom>.

• source

  Obligatoire

  Non

  Notes

  browser ou server, browser par défaut. Doit correspondre à la clé.

• occurred_at

  Obligatoire

  Non

  Notes

  Date ISO 8601 avec fuseau. Maintenant par défaut. Au plus 7 jours dans le passé et 5 minutes dans le futur.

• value

  Obligatoire

  Non

  Notes

  Nombre positif, en unités et pas en centimes : 49.9 veut dire 49,90 €.

• currency

  Obligatoire

  Non

  Notes

  Code ISO à 3 lettres (EUR). Absent, Oriva prend la devise de ton domaine.

• consent

  Obligatoire

  Non

  Notes

  { "ads": true } ou { "ads": false }. Absent, Oriva considère que le visiteur a refusé.

• visitor_id

  Obligatoire

  Non

  Notes

  UUID : le cookie or_vid du visiteur, pour rattacher la vente à sa visite.

• user_data

  Obligatoire

  Non

  Notes

  Objet : email, phone, first_name, last_name, zip, external_id. Voir Données personnelles.

• custom_data

  Obligatoire

  Non

  Notes

  Objet libre, 8 Ko au plus. Voir custom_data.

• click_ids

  Obligatoire

  Non

  Notes

  Objet : fbclid, ttclid, gclid, gbraid, wbraid, msclkid, aff_click_id, fbc, fbp, ttp, oppref, obref.

• utm

  Obligatoire

  Non

  Notes

  Objet : source, medium, campaign, content, term.

• sub_ids

  Obligatoire

  Non

  Notes

  Objet : subid, s1, s2, s3, s4, s5.

• url, referrer

  Obligatoire

  Non

  Notes

  URL absolue. Remplis tout seuls par le code de suivi.

• ip, user_agent

  Obligatoire

  Non

  Notes

  Serveur seulement : ceux du visiteur, jamais ceux de ton serveur. Refusés sur un événement browser.

Un texte vide compte comme absent. Les champs inconnus sont ignorés.

• page_view

  Envoyé aux plateformes

  Non

  Ce que c'est

  Une page vue. Envoyé tout seul par le code de suivi.

• view_content

  Envoyé aux plateformes

  Non

  Ce que c'est

  Une fiche produit ou un contenu consulté.

• add_to_cart

  Envoyé aux plateformes

  Non

  Ce que c'est

  Un ajout au panier.

• initiate_checkout

  Envoyé aux plateformes

  Non

  Ce que c'est

  Le début du paiement.

• lead

  Envoyé aux plateformes

  Oui

  Ce que c'est

  Un contact : formulaire, demande de devis, inscription à une liste.

• purchase

  Envoyé aux plateformes

  Oui

  Ce que c'est

  Un achat.

• complete_registration

  Envoyé aux plateformes

  Oui

  Ce que c'est

  Une création de compte.

• subscribe

  Envoyé aux plateformes

  Oui

  Ce que c'est

  Un abonnement payant souscrit.

• start_trial

  Envoyé aux plateformes

  Oui

  Ce que c'est

  Un essai démarré.

• custom:<nom>

  Envoyé aux plateformes

  Oui

  Ce que c'est

  Tout autre événement qui compte pour toi : un clic sortant, un téléchargement.

Les quatre premiers servent à ton tableau de bord Oriva. Ils ne sont envoyés à aucune plateforme. Les autres deviennent des conversions, sous ces noms :

• lead

  Meta et TikTok

  Lead

  ChatGPT Ads

  lead_created

• purchase

  Meta et TikTok

  Purchase

  ChatGPT Ads

  order_created

• complete_registration

  Meta et TikTok

  CompleteRegistration

  ChatGPT Ads

  registration_completed

• subscribe

  Meta et TikTok

  Subscribe

  ChatGPT Ads

  subscription_created

• start_trial

  Meta et TikTok

  StartTrial

  ChatGPT Ads

  trial_started

• custom:<nom>

  Meta et TikTok

  <nom>

  ChatGPT Ads

  <nom>, en événement personnalisé

• Google Ads : une destination suit un seul événement, celui que tu choisis à sa création (n'importe lequel de ceux qui partent vers les plateformes). Pour suivre un lead et un achat, crée deux destinations.
• Postback d'affiliation : tous les événements qui partent vers les plateformes, ou un seul si tu en choisis un, et seulement s'ils viennent de ton serveur.
• custom:<nom> : <nom> fait de 1 à 64 caractères, en minuscules, chiffres, _ et -, et commence par une lettre ou un chiffre (custom:clic_partenaire). Chez ChatGPT Ads, crée d'abord dans ton gestionnaire de publicités un événement de conversion au nom exact (clic_partenaire) : sans lui, OpenAI accepte l'envoi mais ne compte rien.

Oriva enregistre tout ce que tu y mets (jusqu'à 8 Ko), mais n'en transmet qu'une partie :

• Meta et TikTok reçoivent seulement ces clés : content_ids, content_id, content_name, content_type, content_category, contents, num_items, order_id, predicted_ltv, search_string, status, delivery_category, quantity, query. Toute autre clé reste chez Oriva.
• ChatGPT Ads reçoit les mêmes, plus plan_id sur subscribe et start_trial.
• Google Ads ne lit pas custom_data.
• Postback : payout alimente la variable {payout} de ton URL. Toutes les variables.

order_id sert aussi à l'onglet Santé pour repérer une même commande envoyée par le navigateur et par le serveur.

Champs acceptés dans user_data : email, phone, first_name, last_name, zip, external_id.

Oriva ne garde jamais ces valeurs en clair : elles sont normalisées puis hachées en SHA-256 avant d'être écrites. Tu peux les envoyer en clair ou déjà hachées (64 caractères hexadécimaux) : une valeur déjà hachée est gardée telle quelle, à condition de l'avoir normalisée de la même façon :

• tout : espaces en début et fin retirés, minuscules ;
• téléphone : chiffres seuls, avec l'indicatif, sans + (33612345678). Un numéro qui commence par 0 sans indicatif est lu comme français ;
• code postal : sans espace ni tiret, 5 caractères au plus ;
• external_id : casse conservée.

Sans consentement publicitaire, user_data n'est pas enregistré du tout.

Succès : 202.

{ "ok": true, "event_id": "commande-1001", "deduped": false }

deduped: true : cet event_id était déjà connu, l'événement est ignoré. buffered: true : Oriva l'a mis de côté pendant un incident et l'écrira dès que possible. Dans les deux cas, ne renvoie rien.

Erreurs : toujours { "ok": false, "error": "…" }.

• 400

  error

  invalid_payload

  Ce que ça veut dire

  Un champ est invalide. issues donne le chemin et la raison de chacun.

• 400

  error

  invalid_payload:ip_and_user_agent_are_server_only

  Ce que ça veut dire

  ip ou user_agent envoyés sur un événement browser.

• 401

  error

  missing_api_key

  Ce que ça veut dire

  Pas de clé, ni dans l'en-tête X-Oriva-Key ni dans ?k=.

• 401

  error

  invalid_api_key:malformed

  Ce que ça veut dire

  La clé n'a pas le bon format.

• 401

  error

  invalid_api_key:unknown

  Ce que ça veut dire

  Clé inconnue.

• 401

  error

  invalid_api_key:revoked

  Ce que ça veut dire

  Clé révoquée.

• 401

  error

  key_scope:public_key_cannot_send_server_events

  Ce que ça veut dire

  Une clé pk_ qui envoie un événement server.

• 401

  error

  key_scope:secret_key_cannot_send_browser_events

  Ce que ça veut dire

  Une clé sk_ qui envoie un événement browser.

• 403

  error

  origin_not_allowed

  Ce que ça veut dire

  Appel depuis un navigateur, sur un autre site que ton domaine.

• 429

  error

  rate_limited

  Ce que ça veut dire

  Trop d'appels. retry_after et l'en-tête Retry-After disent dans combien de secondes réessayer.

Seul un 429 se réessaie tel quel. Un 400 ou un 401 échouera de la même façon tant que la requête ou la clé ne change pas.

• Intégrations : brancher chaque plateforme et chaque site.
• Double comptage pixel et API serveur.
• La version texte de cette page, pour ton assistant IA.