# Intégration du SDK Circuy

Le script se charge depuis `https://cdn.circuy.net/v1/sdk.js`. La clé publique du projet, visible dans le dashboard, identifie les parcours à exécuter. Elle n'est pas un secret : elle autorise uniquement la lecture des parcours publiés et l'envoi de la télémétrie depuis une origine déclarée.

## Chargement

```html
<script
  src="https://cdn.circuy.net/v1/sdk.js"
  data-key="pk_votre_cle"
  data-tours="https://cdn.circuy.net/v1/p/pk_votre_cle/manifest.json"
  async
></script>
```

Le SDK charge le manifeste, puis chaque version publiée. Si `data-events-url` est absent, l'URL de télémétrie est déduite du manifeste (`/v1/events` sur la même origine).

Le SDK filtre lui-même selon l'URL de la page, l'audience et la fréquence d'affichage. Le manifeste est identique pour tous les visiteurs d'un même projet.

## Délai de publication

Une publication ne purge aucun cache. Le nouveau contenu est servi à une URL qui n'existait pas auparavant ; le manifeste, lui, expire de lui-même.

| Situation | Délai avant qu'une publication soit visible |
| --- | --- |
| Site à trafic régulier | 60 secondes |
| Visiteur isolé dont le manifeste est encore en cache | jusqu'à 10 minutes, son passage déclenchant le rafraîchissement |
| Nouveau visiteur, cache vide | immédiat |

Ce délai est un engagement, pas un incident. Recharger son site trois secondes après avoir publié ne montre pas encore le changement, et c'est le comportement attendu.

## Origines autorisées

Les lectures (manifeste et versions) sont publiques. Les écritures de télémétrie, en revanche, ne sont acceptées que depuis les origines déclarées sur le projet. Ajoutez l'origine exacte de votre site (`https://app.exemple.com`), sans chemin.

## Télémétrie

Le SDK envoie un lot d'événements vers `POST /v1/events` lorsque l'onglet passe en arrière-plan. Circuy n'enregistre ni adresse IP, ni cookie, ni URL complète, ni identifiant persistant. L'identifiant de session est aléatoire et local au navigateur.

## Stockage sur le terminal du visiteur

Le SDK écrit uniquement ce qui suit. Circuy n'y a pas accès. Ces clés servent à reprendre un parcours interrompu et à ne pas rejouer un parcours déjà vu.

| Clé | Emplacement | Contenu | Durée |
| --- | --- | --- | --- |
| `circuy:{clé}:{parcours}` | `localStorage` | progression (`stepId`, `version`, `updatedAt`) | 24 heures |
| `circuy:{clé}:seen` | `localStorage` | identifiants des parcours déjà vus | jusqu'à suppression par le visiteur |
| `circuy:{clé}:sid` | `sessionStorage` | identifiant de session aléatoire | fin de session du navigateur |

`{clé}` est la clé publique du projet. Le client responsable de traitement intègre cette description à sa propre documentation ; Circuy ne tranche pas à sa place la question du consentement.

Le contrat de sous-traitance est dans [dpa.md](dpa.md).