Intégration SDK

Audience

Cette surface API est destinée aux partenaires d'intégration construisant sur le réseau Rokt. Les partenaires e-commerce de Rokt intégrant des emplacements sur leur propre page de paiement devraient utiliser les documents développeur Rokt Ecommerce à la place.

Une fois qu'un marchand est enregistré via POST /v1/accounts/register/partnership, la réponse contient le account_id et, si vous avez fourni pages, un page_identifier par surface. Les pages du marchand nécessitent :

Le SDK Rokt chargé une fois par page (le script de chargement à l'étape 1 ci-dessous).
Un appel selectPlacements sur chaque surface, en passant le page_identifier correspondant. Pour les surfaces intégrées, un élément ancre (<div id="rokt-container"></div> par défaut) où l'emplacement doit être rendu.

Consultez Pages et Dispositions pour le vocabulaire des surfaces et comment la réponse se mappe à votre code SDK.

Cette page couvre l'intégration standard des applications multipages. Pour les applications à page unique, consultez les notes SPA en bas.

1. Charger le SDKLien direct vers 1. Charger le SDK

Intégrez le chargeur dans le <head> de la page du marchand. Le chargeur récupère launcher.js de manière asynchrone et résout une promesse lorsqu'il est prêt.

attention

Remplacez <your-rokt-account-id> par le account_id renvoyé par la réponse POST /v1/accounts/register/partnership du marchand. Chaque marchand a son propre account_id.

remarque

Utilisateurs de Google Tag Manager : assurez-vous que le champ document.write est coché sur la balise HTML personnalisée. Sans cela, l'étape d'injection de script du chargeur est bloquée et le SDK ne s'initialise jamais.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- Meta tags -->

  <!-- Part #1: Load the Rokt SDK -->
  <script type="module">
    window.RoktLauncherScriptPromise = new Promise((resolve, reject) => {
      const target = document.head || document.body;
      const script = document.createElement("script");
      script.type = "text/javascript";
      script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
      script.fetchPriority = "high";
      script.crossOrigin = "anonymous";
      script.async = true;
      script.id = "rokt-launcher";

      script.addEventListener('load', () => resolve());
      script.addEventListener('error', (error) => reject(error));

      target.appendChild(script);
    });
  </script>

  <!-- Other scripts and meta tags -->
</head>
<body>
  <!-- Your HTML content here -->

  <!-- Part #2: As soon as customer attributes are available, render the placement -->
  <script type="module">
    await window.RoktLauncherScriptPromise;

    const launcher = await window.Rokt.createLauncher({
      // SDK param (camelCase); the API registration response returns account_id (snake_case)
      accountId: "<your-rokt-account-id>",
      sandbox: true,
    });

    await launcher.selectPlacements({
      identifier: "confirmation_page",   // ← page_identifier from /register response, matched per surface
      attributes: {
        email: "",
        firstname: "",
        lastname: "",
        confirmationref: "",
        billingzipcode: "",
        amount: "",
        country: "",
        currency: "",
        mobile: "",
        // ... additional attributes
      },
    });
  </script>

  <!-- Your HTML content here -->
</body>
</html>

Chargez le SDK tôt (dans <head>), puis invoquez selectPlacements dès que les attributs client (email, total de la commande, etc.) sont disponibles. Une disponibilité plus précoce des attributs donne au SDK plus de temps pour rendre l'emplacement avant que la page ne soit interactive.

2. Attributs clientLien direct vers 2. Attributs client

Transmettez autant que possible des éléments suivants que le processus de paiement du marchand collecte. Plus d'attributs signifient une meilleure pertinence et des taux de remplissage plus élevés.

Attribut	Description
`email`	Email brut, non haché. Signal d'identité principal.
`firstname`, `lastname`	Nom du client.
`confirmationref`	Numéro de confirmation de commande.
`billingzipcode`	Code postal de facturation.
`amount`	Total de la commande.
`country`	Code pays ISO 3166-1 alpha-2 (`US`, `GB`, `AU`).
`currency`	Code de devise ISO 4217 (`USD`, `GBP`, `AUD`).
`mobile`	Numéro de téléphone au format E.164 (`+13125551515`).
`age`, `gender`	Signaux démographiques.
`billingaddress1`, `billingaddress2`	Adresse de facturation.
`language`	Locale de la page (ISO 639-1).
`cartItems`	Tableau JSON sous forme de chaîne des articles de ligne du panier.

Si seule la forme hachée d'un identifiant est disponible, utilisez email_sha256 ou mobile_sha256 à la place de email / mobile.

3. Sandbox vs productionLien direct vers 3. Sandbox vs production

Lors des tests, définissez sandbox: true dans l'appel createLauncher. Lorsque le marchand est prêt à être en ligne, définissez sandbox: false ou supprimez complètement le champ.

astuce

L'intégration directe du snippet est le chemin recommandé, mais le déploiement du SDK via un gestionnaire de balises (Google Tag Manager, Tealium, Adobe Experience Platform) est également pris en charge. L'injection directe minimise la surcharge de temps de chargement et évite les pièges spécifiques aux gestionnaires de balises.

4. Emplacements intégrésLien direct vers 4. Emplacements intégrés

Si le préréglage de partenariat crée un emplacement intégré, la page du marchand doit inclure l'élément HTML cible auquel l'emplacement s'ancre (par défaut : <div id="rokt-container"></div>). Le sélecteur exact est configuré dans le préréglage de partenariat.

5. Tester l'intégrationLien direct vers 5. Tester l'intégration

Confirmez dans la console du navigateur du marchand que :

window.Rokt est défini après le chargement de launcher.js
createLauncher se résout sans erreurs
selectPlacements est appelé avec les attributs du client remplis

Si selectPlacements retourne avec succès mais qu'aucun emplacement ne s'affiche, vérifiez que le identifier que vous passez correspond au page_identifier retourné par /register pour cette surface. La liste complète des identifiants (confirmation_page, tracking_page, returns_page) est documentée dans Pages et Dispositions.

astuce

Chargement lent des pages ? Si l'emplacement s'affiche systématiquement après que la page soit interactive et que le marchand le signale comme un problème de vitesse de chargement, une iframe préparative peut préchauffer le SDK avant que selectPlacements ne soit appelé. Contactez votre interlocuteur Rokt si vous souhaitez explorer cette option ; c'est une optimisation par marchand, pas une valeur par défaut.

Applications monopageLien direct vers Applications monopage

Pour les SPA (React, Vue, Angular, etc.), appelez selectPlacements chaque fois que l'itinéraire change vers une page qui doit afficher un emplacement Rokt. Ne pas appeler createLauncher plus d'une fois par session.