Last updated Oct 24, 2023

In-cart integration

Integrating your cart with Rokt

Subscribe to Rokt placement cart changes

The in-transaction/cart integration notifies your frontend whenever a customer selects a Rokt upsell opportunity, allowing for the change to be reflected in a customer's cart. This is achieved by listening to the V2_CART_ITEM_UPDATED message of a placement, which is triggered every time a customer makes changes to selected items on the Rokt side.

You can subscribe to that message by using the Selection.on method which allows you to listen for messages from any selected placement. The payload of those messages is described in UpdateCartItemPlacementMessageBody.

Additionally, you can provide extra information by passing attributes to better tailor an offers' selection to a customer. In some cases, depending on your catalog provider, additional information may be required for Rokt to retrieve catalog items.

// (...) 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);
});

Update Rokt placement cart from your cart

In the scenario where your cart changes need to be reflected on the Rokt side, you can send messages to the Placement to do so. For your convenience, you can send a message to each placement in selection by using the Selection.send method. The affected Rokt placement will listen and action accordingly. The payload of this message is described in UpdateCartItemPartnerMessageBody.

note

Please be advised that certain changes will not be performed if the configuration does not allow it. For instance, if a forced upsell has a minimum quantity of 1, and the placement receives a message from the partner to remove that selection, the placement will not action it.

Be sure though, there is always a message sent back to the partner from the placement, to close the loop and share the Rokt placement cart state to the partner, to ensure both carts are aligned (please see section above).

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

selection.send("V2_UPDATE_CART_ITEM", payload);

Checking placement availability

This extension involves your backend issuing a call to Rokt to check if any placements are available. You can then decide if your upsell page should be displayed or skipped. In this scenario, your pages have most likely already been generated on the backend, and you have already included customer and transaction data to Rokt in the initial call. Since that call may have already generated your session ID, the Rokt JavaScript API requires you to include your session ID in the Rokt.createLauncher method so both interactions can be paired together for identification and performance reasons.

// (...) loading Rokt script

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

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

Checking placement is valid

Some Rokt offers contain fields the customer must complete before moving on in the transaction flow. An example of this is filling out a form or selecting yes/no on an offer.

These types of offers contain validation messaging that displays a warning to the customer indicating the action they must take before proceeding.

The behavior is optional and needs to be enabled through IntegrationLauncher.use() method before making a selection. Once the partner validation module is obtained you can check if the current placements are valid using the getValidationStatus method. The method returns a JavaScript Promise that waits until the placements have resolved their first validation state as defined. The resolved value looks like:

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;
    }>;
  }>;
}

Example usage

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);
    }
  }
};