# Oriva

> Tracking de conversion et attribution côté serveur, first-party. Un code de suivi et une API serveur reçoivent les clics et les conversions, Oriva les dédoublonne et les renvoie à Meta, TikTok, Google Ads, ChatGPT Ads et aux réseaux d'affiliation.

Référence technique complète, aussi en page web : https://www.orivaforge.com/docs

Tout ce qu'Oriva accepte, au champ près : les commandes du code de suivi, l'API serveur, la liste des événements et ce que chacun devient chez chaque plateforme. Pour brancher une plateforme pas à pas, passe par les pages [Intégrations](https://www.orivaforge.com/integrations). Si tu codes avec un assistant IA, donne-lui cette page ou sa version texte, [/llms.txt](https://www.orivaforge.com/llms.txt).

## Deux façons d'envoyer un événement

|  | Code de suivi (navigateur) | API serveur |
| --- | --- | --- |
| Clé | `pk_`, publique, dans la page | `sk_`, secrète, sur ton serveur |
| `source` | `browser` | `server` |
| Déclenche un postback d'affiliation | Non | Oui |
| `ip` et `user_agent` | Lus par Oriva sur la connexion | À 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.

## Le code de suivi

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.

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

| Option | Rôle |
| --- | --- |
| `key` | Ta clé `pk_`. Obligatoire. |
| `host` | Le sous-domaine de suivi. Par défaut, celui d'où `oriva.js` est chargé. |
| `page_view` | `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](https://www.orivaforge.com/integrations/site#consentement).

### 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é.

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

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

Envoie un événement.

```js
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](https://www.orivaforge.com/docs#custom-data)).

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.

## L'API serveur

```http
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](https://www.orivaforge.com/docs#champs). [Exemple complet et bonnes pratiques](https://www.orivaforge.com/integrations/api). Ta clé secrète reste sur ton serveur, dans une variable d'environnement.

## Les champs d'un événement

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.

| Champ | Obligatoire | Notes |
| --- | --- | --- |
| `event_id` | Oui | Texte, 128 caractères au plus. Unique par domaine : un second envoi avec le même `event_id` est accepté mais ignoré. |
| `name` | Oui | Un des [événements](https://www.orivaforge.com/docs#evenements), ou `custom:<nom>`. |
| `source` | Non | `browser` ou `server`, `browser` par défaut. Doit correspondre à la clé. |
| `occurred_at` | Non | Date ISO 8601 avec fuseau. Maintenant par défaut. Au plus 7 jours dans le passé et 5 minutes dans le futur. |
| `value` | Non | Nombre positif, en unités et pas en centimes : `49.9` veut dire 49,90 €. |
| `currency` | Non | Code ISO à 3 lettres (`EUR`). Absent, Oriva prend la devise de ton domaine. |
| `consent` | Non | `{ "ads": true }` ou `{ "ads": false }`. **Absent, Oriva considère que le visiteur a refusé.** |
| `visitor_id` | Non | UUID : le cookie `or_vid` du visiteur, pour rattacher la vente à sa visite. |
| `user_data` | Non | Objet : `email`, `phone`, `first_name`, `last_name`, `zip`, `external_id`. Voir [Données personnelles](https://www.orivaforge.com/docs#donnees-personnelles). |
| `custom_data` | Non | Objet libre, 8 Ko au plus. Voir [custom_data](https://www.orivaforge.com/docs#custom-data). |
| `click_ids` | Non | Objet : `fbclid`, `ttclid`, `gclid`, `gbraid`, `wbraid`, `msclkid`, `aff_click_id`, `fbc`, `fbp`, `ttp`, `oppref`, `obref`. |
| `utm` | Non | Objet : `source`, `medium`, `campaign`, `content`, `term`. |
| `sub_ids` | Non | Objet : `subid`, `s1`, `s2`, `s3`, `s4`, `s5`. |
| `url`, `referrer` | Non | URL absolue. Remplis tout seuls par le code de suivi. |
| `ip`, `user_agent` | Non | **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.

## Les événements

| Événement | Envoyé aux plateformes | Ce que c'est |
| --- | --- | --- |
| `page_view` | Non | Une page vue. Envoyé tout seul par le code de suivi. |
| `view_content` | Non | Une fiche produit ou un contenu consulté. |
| `add_to_cart` | Non | Un ajout au panier. |
| `initiate_checkout` | Non | Le début du paiement. |
| `lead` | Oui | Un contact : formulaire, demande de devis, inscription à une liste. |
| `purchase` | Oui | Un achat. |
| `complete_registration` | Oui | Une création de compte. |
| `subscribe` | Oui | Un abonnement payant souscrit. |
| `start_trial` | Oui | Un essai démarré. |
| `custom:<nom>` | Oui | 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 :

| Événement Oriva | Meta et TikTok | ChatGPT Ads |
| --- | --- | --- |
| `lead` | `Lead` | `lead_created` |
| `purchase` | `Purchase` | `order_created` |
| `complete_registration` | `CompleteRegistration` | `registration_completed` |
| `subscribe` | `Subscribe` | `subscription_created` |
| `start_trial` | `StartTrial` | `trial_started` |
| `custom:<nom>` | `<nom>` | `<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.

## custom_data

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](https://www.orivaforge.com/integrations/postback-affiliation).

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

## Données personnelles

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.

## Réponses et erreurs

**Succès** : `202`.

```json
{ "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": "…" }`.

| Statut | error | Ce que ça veut dire |
| --- | --- | --- |
| `400` | `invalid_payload` | Un champ est invalide. `issues` donne le chemin et la raison de chacun. |
| `400` | `invalid_payload:ip_and_user_agent_are_server_only` | `ip` ou `user_agent` envoyés sur un événement `browser`. |
| `401` | `missing_api_key` | Pas de clé, ni dans l'en-tête `X-Oriva-Key` ni dans `?k=`. |
| `401` | `invalid_api_key:malformed` | La clé n'a pas le bon format. |
| `401` | `invalid_api_key:unknown` | Clé inconnue. |
| `401` | `invalid_api_key:revoked` | Clé révoquée. |
| `401` | `key_scope:public_key_cannot_send_server_events` | Une clé `pk_` qui envoie un événement `server`. |
| `401` | `key_scope:secret_key_cannot_send_browser_events` | Une clé `sk_` qui envoie un événement `browser`. |
| `403` | `origin_not_allowed` | Appel depuis un navigateur, sur un autre site que ton domaine. |
| `429` | `rate_limited` | 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.

## Pour aller plus loin

- [Intégrations](https://www.orivaforge.com/integrations) : brancher chaque plateforme et chaque site.
- [Double comptage pixel et API serveur](https://www.orivaforge.com/guides/deduplication-pixel-api-serveur-double-comptage).
- [La version texte de cette page](https://www.orivaforge.com/llms.txt), pour ton assistant IA.

## Pages

- [Tracking server-side first-party, avec la preuve de chaque envoi | Oriva](https://www.orivaforge.com/produit)
- [Intégrations Oriva : Meta, TikTok, Google Ads, OpenAI, affiliation](https://www.orivaforge.com/integrations)
- [Meta Conversions API sans Google Tag Manager | Oriva](https://www.orivaforge.com/integrations/meta-conversions-api)
- [TikTok Events API : envoyer tes conversions côté serveur | Oriva](https://www.orivaforge.com/integrations/tiktok-events-api)
- [Conversions améliorées Google Ads côté serveur | Oriva](https://www.orivaforge.com/integrations/google-ads)
- [ChatGPT Ads : envoyer tes conversions par la Conversions API | Oriva](https://www.orivaforge.com/integrations/chatgpt-ads)
- [Postback S2S : prévenir ton réseau d'affiliation à chaque vente | Oriva](https://www.orivaforge.com/integrations/postback-affiliation)
- [Oriva pour Shopify : le suivi des achats après la coupure du 26 août | Oriva](https://www.orivaforge.com/integrations/shopify)
- [WooCommerce : envoyer tes commandes à Meta, TikTok et Google côté serveur | Oriva](https://www.orivaforge.com/integrations/woocommerce)
- [Installer Oriva sur n'importe quel site : WordPress, Webflow, Wix, GTM | Oriva](https://www.orivaforge.com/integrations/site)
- [API serveur : envoyer tes conversions à Oriva depuis ton backend | Oriva](https://www.orivaforge.com/integrations/api)
- [Tracking server-side pour media buyers et affiliés : CAPI et postbacks — Oriva](https://www.orivaforge.com/solutions/media-buyers)
- [Tracking server-side pour Shopify et WooCommerce : Meta, TikTok, Google — Oriva](https://www.orivaforge.com/solutions/e-commerce)
- [Ventes perdues par le navigateur : les renvoyer à Meta, TikTok et Google — Oriva](https://www.orivaforge.com/solutions/ventes-perdues)
- [Triple Whale, alternative Oriva : prix sur devis vs prix public](https://www.orivaforge.com/guides/oriva-alternative-a-triple-whale)
- [Stape, alternative Oriva : conteneur GTM serveur vs formulaire tout-en-un](https://www.orivaforge.com/guides/oriva-alternative-a-stape)
- [Hyros, alternative Oriva : prix indexé sur ton CA ou prix fixe](https://www.orivaforge.com/guides/oriva-alternative-a-hyros)
- [Double comptage pixel + API serveur : comment dédupliquer sur Meta, TikTok, Google Ads](https://www.orivaforge.com/guides/deduplication-pixel-api-serveur-double-comptage)
- [Google Ads : developer token supprimé, import de conversions refusé, que faire ?](https://www.orivaforge.com/guides/google-ads-developer-token-data-manager-api)
- [API Conversions activée par Meta : suffit-elle, ou faut-il un vrai server-side ?](https://www.orivaforge.com/guides/api-conversions-activee-par-meta)
- [Suivre les conversions ChatGPT Ads : pixel OpenAI, Conversions API et oppref](https://www.orivaforge.com/guides/chatgpt-ads-suivi-conversions)
- [Shopify, 26 août 2026 : ton tracking a-t-il cassé ?](https://www.orivaforge.com/guides/shopify-pixel-page-de-remerciement)