Installez le SDK navigateur

Installez le SDK une seule fois via le mécanisme global de scripts de votre framework. La balise ci-dessous concerne le HTML brut.

Les frameworks gèrent le head du document. Avec Next.js App Router, utilisez next/script dans le layout racine. Ne rendez pas un head personnalisé et n'y injectez pas cette balise avec dangerouslySetInnerHTML.

Appelez les deux méthodes principales

Utilisez JavaScript pour les comportements significatifs sans activation DOM correspondante. Pour les liens, boutons, contrôles et formulaires, ajoutez plutôt des attributs HTML.

window.splendorize.action(
  "change_billing_period",
  { placement: "pricing" },
);

<a
  href="/signup"
  data-splendorize-action="start_trial"
  data-splendorize-action-placement="hero"
>
  Start trial
</a>

<form data-splendorize-action="request_demo">
  <!-- Existing fields and submit button -->
</form>

Règles pour les actions

• Utilisez une clé d’objectif en minuscules qui commence par une lettre, contient des lettres, des chiffres et des underscores simples, et ne dépasse pas 64 caractères.
• Réutilisez la même clé sur plusieurs emplacements. Annotez un formulaire une seule fois, directement sur le formulaire, et n’ajoutez jamais d’appel programmatique pour le même geste.
• Ne générez jamais les clés ou les emplacements à partir du texte visible, de la langue, des données du visiteur, d’identifiants de compte, d’horodatages ou de variantes d’expérience.

Appelez conversion uniquement après que le flux existant de l’application a prouvé la réussite, par exemple après une réponse positive de l’API ou lorsque l’état de destination confirme le résultat.

Autorité

Déclarée côté client. Un emplacement correct donne du sens à l’événement, mais le code du navigateur ne peut pas fournir l’autorité d’un serveur authentifié.

Quand l’utiliser

Une inscription, un essai, un ajout à une liste d’attente ou une demande de démo a réellement abouti et le navigateur constitue le seul point disponible qui confirme la réussite. Ne l’appelez jamais lors du clic ou de l’envoi qui lance le processus.

const result = await startTrial();

if (result.trialStarted === true) {
  window.splendorize.conversion("trial_started");
}

Lorsque votre backend est le système qui valide la réussite, envoyez la conversion avec une requête POST vers /v1/conversion à l’aide de la clé privée du site. Les requêtes acceptées renvoient 202. url est obligatoire et doit appartenir à un domaine autorisé du projet ; name, occurredAt, referrer et les identifiants de visiteur, de session et de page vue sont facultatifs.

Autorité

Provenance authentifiée au niveau du projet. Elle est plus solide qu’une déclaration du navigateur, mais ne prouve pas l’identité d’une personne.

Quand l’utiliser

Votre backend a confirmé un résultat qui ne relève pas d’un paiement. Conservez la clé privée côté serveur et choisissez cette voie au lieu d’émettre la même conversion depuis le navigateur.

const response = await fetch("https://cdn.splendorize.com/v1/conversion", {
  method: "POST",
  headers: {
    authorization: "Bearer " + process.env.SPLENDORIZE_PRIVATE_SITE_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    name: "trial_started",
    url: "https://example.com/welcome",
    occurredAt: new Date().toISOString(),
  }),
});

if (response.status !== 202) {
  throw new Error("Splendorize rejected the conversion");
}

Connectez Stripe, récupérez stripeMetadata() après le chargement du SDK navigateur et validez les clés d’attribution prises en charge dans votre backend. Pour Checkout en mode abonnement, joignez-les aux métadonnées de la Checkout Session ainsi qu’à celles de l’abonnement. Les événements signés invoice.payment_succeeded fournissent le montant brut, la devise et l’heure du paiement ; les webhooks de remboursement et de litige ajustent la valeur nette, tandis que les webhooks d’abonnement ajoutent des signaux d’annulation et de churn. Les factures historiques ne sont pas importées.

Autorité

Garantie par le fournisseur pour le statut de la facture payée, le montant brut, la devise et l’heure du paiement. Les métadonnées Splendorize relient le parcours du visiteur ; elles ne prouvent pas le paiement.

Quand l’utiliser

Vous devez mesurer des achats associés à des factures Stripe payées avec succès ou des revenus récurrents d’abonnement. Ne transmettez pas de montants fournis par le navigateur et n’émettez pas une seconde conversion depuis le navigateur dans le seul but de revendiquer le même paiement.

const attribution = window.splendorize.stripeMetadata();

await fetch("/api/checkout", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ attribution }),
});

const attribution = Object.fromEntries(
  [
    "splendorize_site_id",
    "splendorize_visitor_id",
    "splendorize_session_id",
    "splendorize_page_view_id",
  ].flatMap((key) => {
    const value = requestBody.attribution?.[key];
    return typeof value === "string" && value.length <= 120
      ? [[key, value]]
      : [];
  }),
);

await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items,
  success_url,
  cancel_url,
  metadata: attribution,
  subscription_data: { metadata: attribution },
});

Appelez ces méthodes sur window.splendorize. Avec le loader personnalisé, toutes sauf stripeMetadata() peuvent être mises en file d’attente avant le chargement du SDK.

action(actionKey, { placement? })

Enregistre une action stable fondée sur son objectif, avec un emplacement facultatif. Elle ne déclare pas qu’un résultat est finalisé.

conversion(name?, properties?)

Enregistre une conversion déclarée côté client. Appelez-la uniquement après que l’application a confirmé la réussite.

payment({ email })

Hache l’adresse e-mail de paiement pour relier le parcours actuel du visiteur. Elle ne prouve jamais le paiement, le montant ou le chiffre d’affaires.

stripeMetadata()Après le chargement du SDK

Renvoie les identifiants d’attribution Splendorize à joindre aux métadonnées Stripe. Elle ne prouve pas le paiement.

setConsent(allowed)

Autorise ou retire le suivi persistant lorsque votre site exige un consentement préalable. Passer false efface l’attribution persistante.

Le loader généré accepte également des commandes appelables comme window.splendorize("action", "start_trial"). Dans le code de l’application, privilégiez les méthodes nommées ci-dessus, car elles sont plus faciles à lire.

Gardez une implémentation ciblée et donnez à chaque signal une seule signification précise.

• Installez un seul loader global et conservez le comportement du site en matière de consentement et de CSP.
• Conservez la clé privée du site sur le serveur ; la clé publique du site peut apparaître dans le code du navigateur.
• N’envoyez jamais de valeurs de formulaire, d’adresses e-mail, de noms, de numéros de téléphone, d’identifiants de clients ou de secrets dans les métadonnées d’action ou de conversion.
• Émettez une seule action sémantique par geste et choisissez une unique source de référence pour chaque résultat.
• Traitez l’attribution du paiement comme un simple lien d’identité, jamais comme une autorisation ou une preuve de paiement.