Intégration dans le panier

S'abonner aux changements de placement du panier Rokt

L'intégration dans la transaction/panier notifie votre frontend chaque fois qu'un client sélectionne une opportunité de vente incitative Rokt, permettant ainsi de refléter le changement 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 modifie les articles sélectionnés du côté de Rokt.

Vous pouvez vous abonner à ce message en utilisant la méthode Selection.on qui vous permet d'écouter les messages de tout placement sélectionné.

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

// (...) loading Rokt script and creating Integration Launcher instance

const selection = await launcher.selectPlacements({
  attributes: {
    // attributes required by Rokt to retrieve the catalog items
    eventId: "eventId",
    venueName: "venueName",
    // any additional attributes
    email: "email",
  },
});

selection.on("V2_CART_ITEM_UPDATED").subscribe((event) => {
  // Below you should provide your code to reflect changes to your cart
  clientCart.updateCart(event.body.cartItem, event.body.oldCartItem);
});

Mettre à jour le panier de placement Rokt depuis votre panier

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

remarque

Veuillez noter que certaines modifications ne seront pas effectuées si la configuration ne le permet pas. Par exemple, si une vente incitative 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 n'agira pas.

Soyez toutefois assuré qu'un message est toujours envoyé en retour au partenaire depuis le placement, pour fermer la boucle et partager l'état du panier de placement Rokt avec le partenaire, afin de s'assurer que les deux paniers sont alignés (veuillez consulter la section ci-dessus).

const selection = await launcher.selectPlacements({
  attributes: {
    // attributes required by Rokt to retrieve the catalog items
  },
});

selection.send("V2_UPDATE_CART_ITEM", payload);

Vérification de la disponibilité du placement

Cette extension implique que votre backend émette un appel à Rokt pour vérifier si des placements 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 très probablement déjà été générées sur le backend, et vous avez déjà inclus les données du client et de la transaction à Rokt dans l'appel initial. Étant donné que cet appel peut avoir déjà généré votre ID de session, l'API JavaScript de Rokt nécessite que vous incluiez votre ID de session dans la méthode Rokt.createLauncher afin que les deux interactions puissent être associées ensemble pour des raisons d'identification et de performance.

// (...) loading Rokt script

const launcher = await Rokt.createLauncher({
  accountId: "rokt-account-id",
  sessionId: "uniqueSessionId", // session ID generated by Rokt backend
});

// (...) the rest of the integration logic

Vérification de la validité du placement

Certaines offres Rokt contiennent des champs que le client doit remplir avant de continuer dans le flux de transaction. Un exemple de cela est le remplissage d'un formulaire ou la sélection de oui/non sur une offre.

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

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

interface PlacementValidationStatus {
  // Allows you to quickly determine if there are any errors
  isValid: boolean;
  // This is the list of placements with validation
  placements: Array<{
    // This is the element of the placement containing an error,
    // allowing you to scroll to it if an error is present
    element: HTMLIFrameElement;
    // Placements will show their error own messages but this is an
    // array that provides you with the error messages should you
    // want to repeat them somewhere. It will be empty if valid
    errors: Array<{
      message: string;
    }>;
  }>;
}

Exemple d'utilisation

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

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

// When the customer clicks this button, you check the validation status of the placements
document.querySelector("button.check-validation").onclick = async () => {
  await selection.ready();  
  const result = await partnerValidation.getValidationStatus();

  // Quickly determine if the placements contain an invalid placement
  console.log(result.isValid);

    // Loop through
  for (const placement of result.placements) {
    console.log(
      "element is: " +
        element.getBoundingClientRect().top +
        "px from the top of the page"
    );
    console.log("placement has: " + placement.errors.length + " errors");

    for (const [i, error] of placement.errors.entries()) {
      console.log("placement error: " + i + " is " + error);
    }
  }
};