カート内統合

Roktプレースメントカートの変更を購読する

トランザクション内/カート統合は、顧客がRoktのアップセル機会を選択するたびにフロントエンドに通知し、顧客のカートに変更を反映させることができます。これは、Rokt側で顧客が選択したアイテムに変更を加えるたびにトリガーされるプレースメントのV2_CART_ITEM_UPDATEDメッセージをリッスンすることで実現されます。

このメッセージを購読するには、Selection.onメソッドを使用して、選択された任意のプレースメントからのメッセージをリッスンすることができます。

さらに、オファーの選択を顧客により適合させるために属性を渡すことで追加情報を提供することができます。場合によっては、カタログプロバイダーに依存して、Roktがカタログアイテムを取得するために追加情報が必要になることがあります。

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

自分のカートからRoktプレースメントカートを更新する

自分のカートの変更をRokt側に反映させる必要がある場合、プレースメントにメッセージを送信してそれを行うことができます。便利なことに、Selection.sendメソッドを使用して、選択中の各プレースメントにメッセージを送信することができます。影響を受けたRoktプレースメントはそれをリッスンし、適切にアクションを実行します。

注記

構成がそれを許可しない場合、特定の変更は実行されないことに注意してください。例えば、強制アップセルが最小数量1を持っている場合、パートナーからその選択を削除するメッセージを受け取っても、プレースメントはそれを実行しません。

ただし、常にプレースメントからパートナーにメッセージが送信され、ループを閉じてRoktプレースメントカートの状態をパートナーと共有し、両方のカートが整合していることを確認するためのメッセージが送信されます（上記のセクションを参照してください）。

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

selection.send("V2_UPDATE_CART_ITEM", payload);

プレースメントの可用性を確認する

この拡張機能は、Roktにプレースメントが利用可能かどうかを確認するためにバックエンドが呼び出しを行うことを含みます。その後、アップセルページを表示するかスキップするかを決定できます。このシナリオでは、ページはおそらくすでにバックエンドで生成されており、初回の呼び出しでRoktに顧客とトランザクションデータを含めています。その呼び出しがすでにセッションIDを生成している可能性があるため、Rokt JavaScript APIは、識別とパフォーマンスの理由から、Rokt.createLauncherメソッドにセッションIDを含める必要があります。

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

配置の有効性の確認

一部のRoktオファーには、トランザクションフローを進める前に顧客が記入しなければならないフィールドが含まれています。例えば、フォームに記入するか、オファーに対してはい/いいえを選択することです。

このようなタイプのオファーには、顧客が進む前に取るべきアクションを示す警告を表示するバリデーションメッセージが含まれています。

この動作はオプションであり、選択を行う前に IntegrationLauncher.use() メソッドを通じて有効にする必要があります。パートナーバリデーションモジュールを取得したら、getValidationStatus メソッドを使用して現在の配置が有効かどうかを確認できます。このメソッドは、配置が定義された最初のバリデーション状態を解決するまで待機するJavaScriptのPromiseを返します。解決された値は次のようになります：

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

使用例

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