Sync et rétention des données

Vue d’ensemble

Par défaut, Presage stocke toutes les données localement dans le navigateur (localStorage). Cela fonctionne très bien pour l’adaptation sur un seul appareil, mais les données sont perdues lorsque l’utilisateur vide son navigateur.

Avec une licence Presage Pro (19$/mois), vous pouvez synchroniser les événements, les traits et les signaux vers un backend pour :

• Persistance multi-appareils — le contexte utilisateur le suit d’un navigateur à l’autre
• Rétention longue durée — les événements sont conservés au-delà de la limite de 30 jours du navigateur
• Tableau de bord analytics — visualisez le comportement utilisateur, la distribution de maturité et l’utilisation des fonctionnalités
• Sécurité par domaine — restreignez votre licence aux domaines autorisés uniquement

Installation

1. Obtenir une clé de licence

Inscrivez-vous sur dashboard.presage-kit.dev, créez un projet et copiez votre clé de licence.

2. Configurer votre client

Passez un objet sync à createAdaptiveClient avec votre clé de licence :

import {
  createAdaptiveClient,
  createLocalStorageDriver,
} from '@presage-kit/core'

const client = createAdaptiveClient({
  persistence: {
    driver: createLocalStorageDriver('my-app'),
  },
  sync: {
    license: 'pk_live_abc123…',
    // Surcharges optionnelles (valeurs par défaut) :
    // batchIntervalMs: 10_000,
    // maxBatchSize: 100,
    // maxRetries: 3,
    onSyncError: (error) => {
      console.warn('[presage sync]', error.type, error.message)
    },
  },
  rules: [
    // …vos règles d'adaptation
  ],
})

3. Configurer les domaines autorisés

Dans le tableau de bord, accédez aux paramètres de votre projet et ajoutez vos domaines de production. Localhost est toujours autorisé pour le développement.

Fonctionnement de la synchronisation

Presage utilise une stratégie batch-and-flush pour minimiser le trafic réseau :

1. Mise en lot — les événements, changements de traits et mises à jour de signaux sont mis en file d’attente en mémoire plutôt qu’envoyés individuellement.
2. Intervalle de flush — toutes les 10 secondes (configurable via batchIntervalMs), la file est vidée en une seule requête HTTP vers https://api.presage-kit.dev/api/v1/ingest.
3. Flush par taille — si la file atteint maxBatchSize (100 par défaut) avant le timer, elle est vidée immédiatement.
4. Résilience hors-ligne — si un flush échoue à cause d’une erreur réseau, les événements sont remis en file et retentés au prochain intervalle. Presage utilise un backoff exponentiel (1s, 2s, 4s) jusqu’à maxRetries tentatives.
5. Dégradation gracieuse — si la licence est invalide ou le domaine non autorisé, la synchronisation est désactivée définitivement pour la session. Le moteur principal continue de fonctionner localement sans interruption.
6. Flush à la destruction — quand client.destroy() est appelé, un dernier flush est tenté pour ne perdre aucune donnée lors du déchargement de la page.

Statut de synchronisation

Le client expose un atome réactif syncStatus pour refléter l’état de la synchronisation dans votre interface :

import type { SyncStatus } from '@presage-kit/core'

// SyncStatus = 'idle' | 'validating' | 'active' | 'degraded' | 'disabled'

if (client.syncStatus) {
  client.syncStatus.subscribe((status: SyncStatus) => {
    switch (status) {
      case 'idle':
        // Sync configuré mais pas encore validé
        break
      case 'validating':
        // Vérification de la licence en cours
        break
      case 'active':
        // Licence valide — les événements se synchronisent
        break
      case 'degraded':
        // Erreur réseau lors de la validation — nouvelle tentative prévue
        break
      case 'disabled':
        // Licence invalide ou domaine non autorisé
        break
    }
  })
}

Quand syncStatus est null, la synchronisation n’est pas configurée (plan Gratuit).

Sécurité

Presage utilise une liste de domaines autorisés pour prévenir l’abus de licence :

• Chaque requête de synchronisation inclut un en-tête X-Origin avec le window.location.origin actuel.
• Le backend compare cette origine avec les domaines que vous avez configurés dans le tableau de bord.
• Si l’origine ne correspond pas, le backend retourne un 403 Forbidden et le client désactive la synchronisation pour le reste de la session.
• localhost et 127.0.0.1 sont toujours autorisés pour ne jamais bloquer le développement.

Le callback onSyncError reçoit un objet d’erreur typé qui distingue les erreurs auth (licence invalide), forbidden (domaine non correspondant), rate_limit, network et server — vous permettant de gérer chaque cas de manière appropriée.