Last updated 24 oct. 2023

Intégration dans le panier

Intégration de votre panier avec Rokt

S'abonner aux modifications du panier de placement Rokt

L'intégration dans le panier permet de notifier votre interface utilisateur chaque fois qu'un client sélectionne une opportunité de vente incitative Rokt, ce qui permet de refléter les modifications dans le panier du client. Cela est réalisé en écoutant le message V2_CART_ITEM_UPDATED d'un placement, qui est déclenché à chaque fois qu'un client apporte des modifications aux articles sélectionnés du côté Rokt.

Vous pouvez vous abonner à ce message en utilisant la méthode Selection.on, qui vous permet d'écouter les messages de n'importe quel placement sélectionné. Le contenu de ces messages est décrit dans UpdateCartItemPlacementMessageBody.

De plus, vous pouvez fournir des informations supplémentaires en passant des attributs pour mieux adapter la sélection des offres à un client. Dans certains cas, en fonction de votre fournisseur de catalogue, des informations supplémentaires peuvent être nécessaires pour que Rokt puisse récupérer les articles du catalogue.

// (...) chargement du script Rokt et création de l'instance Integration Launcher

const selection = await launcher.selectPlacements({
  attributes: {
    // attributs requis par Rokt pour récupérer les articles du catalogue
    eventId: "eventId",
    venueName: "venueName",
    // tout attribut supplémentaire
    email: "email",
  },
});

selection.on("V2_CART_ITEM_UPDATED").subscribe((event) => {
  // Vous devez fournir votre code ci-dessous pour refléter les modifications dans votre panier
  clientCart.updateCart(event.body.cartItem, event.body.oldCartItem);
});

Mettre à jour le placement Rokt du panier à partir de votre panier

Dans le scénario où les modifications apportées à votre panier doivent être reflétées du côté Rokt, vous pouvez envoyer des messages au Placement pour le faire. Pour votre commodité, vous pouvez envoyer un message à chaque placement sélectionné en utilisant la méthode Selection.send. Le placement Rokt concerné écoutera et agira en conséquence. La charge utile de ce message est décrite dans UpdateCartItemPartnerMessageBody.

remarque

Veuillez noter que certaines modifications ne seront pas effectuées si la configuration ne le permet pas. Par exemple, si une vente forcée a une quantité minimale de 1 et que le placement reçoit un message du partenaire pour supprimer cette sélection, le placement ne l'exécutera pas.

Cependant, assurez-vous qu'un message est toujours renvoyé au partenaire depuis le placement, pour boucler la boucle et partager l'état du panier du placement Rokt avec le partenaire, afin de garantir que les deux paniers sont alignés (veuillez consulter la section ci-dessus).

const selection = await launcher.selectPlacements({
  attributes: {
    // attributs requis par Rokt pour récupérer les articles du catalogue
  },
});

selection.send("V2_UPDATE_CART_ITEM", payload);

Vérification de la disponibilité des emplacements

Cette extension implique que votre backend envoie une requête à Rokt pour vérifier si des emplacements sont disponibles. Vous pouvez ensuite décider si votre page de vente incitative doit être affichée ou ignorée. Dans ce scénario, vos pages ont probablement déjà été générées en backend, et vous avez déjà inclus les données client et de transaction à Rokt dans l'appel initial. Étant donné que cet appel a peut-être déjà généré votre ID de session, l'API JavaScript de Rokt vous demande d'inclure votre ID de session dans la méthode Rokt.createLauncher afin que les deux interactions puissent être associées pour des raisons d'identification et de performance.

// (...) chargement du script Rokt

const launcher = await Rokt.createLauncher({
  accountId: "roktAccountId",
  sessionId: "uniqueSessionId", // ID de session généré par le backend de Rokt
});

// (...) le reste de la logique d'intégration

Vérification de la validité de l'emplacement

Certaines offres Rokt contiennent des champs que le client doit remplir avant de passer à l'étape suivante de la transaction. Un exemple de cela est de remplir un formulaire ou de sélectionner oui/non pour une offre.

Ces types d'offres contiennent des messages de validation qui affichent un avertissement au client indiquant l'action qu'il doit prendre avant de continuer.

Le comportement est facultatif et doit être activé via la méthode IntegrationLauncher.use() avant de faire une sélection. Une fois que le module de validation du partenaire est obtenu, vous pouvez vérifier si les emplacements actuels sont valides en utilisant la méthode getValidationStatus. La méthode renvoie une promesse JavaScript qui attend que les emplacements aient résolu leur premier état de validation tel que défini. La valeur résolue ressemble à ceci :

interface PlacementValidationStatus {
  // Vous permet de déterminer rapidement s'il y a des erreurs
  isValid: boolean;
  // C'est la liste des emplacements avec validation
  placements: Array<{
    // C'est l'élément de l'emplacement contenant une erreur,
    // vous permettant de faire défiler jusqu'à lui s'il y a une erreur
    element: HTMLIFrameElement;
    // Les emplacements afficheront leurs propres messages d'erreur, mais c'est un
    // tableau qui vous fournit les messages d'erreur si vous
    // souhaitez les répéter quelque part. Il sera vide si valide
    errors: Array<{
      message: string;
    }>;
  }>;
}

Exemple d'utilisation

const partnerValidation = await launcher.use('PartnerValidation');

const selection = await launcher.selectPlacements({
    attributes: {
        /* ... */
    },
});

// Lorsque le client clique sur ce bouton, vous vérifiez l'état de validation des emplacements
document.querySelector("button.check-validation").onclick = async () => {
  await selection.ready();  
  const result = await partnerValidation.getValidationStatus();

  // Déterminez rapidement si les emplacements contiennent un emplacement invalide
  console.log(result.isValid);

    // Boucle à travers
  for (const placement of result.placements) {
    console.log(
      "l'élément est : " +
        element.getBoundingClientRect().top +
        "px depuis le haut de la page"
    );
    console.log("le placement a : " + placement.errors.length + " erreurs");

    for (const [i, error] of placement.errors.entries()) {
      console.log("l'erreur de placement : " + i + " est " + error);
    }
  }
};