メインコンテンツまでスキップ

カートとの統合

Roktとのカートの統合​

Roktの配置のカート変更を購読する​

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

選択した配置からメッセージを購読するには、Selection.onメソッドを使用します。このメソッドを使用すると、任意の選択した配置からのメッセージをリッスンすることができます。これらのメッセージのペイロードは、UpdateCartItemPlacementMessageBodyで説明されています。

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

// (...) Roktスクリプトの読み込みとIntegration Launcherインスタンスの作成

const selection = await launcher.selectPlacements({
  attributes: {
    // Roktがカタログアイテムを取得するために必要な属性
    eventId: "eventId",
    venueName: "venueName",
    // その他の属性
    email: "email",
  },
});

selection.on("V2_CART_ITEM_UPDATED").subscribe((event) => {
  // 以下には、カートの変更を反映するためのコードを記述する必要があります
  clientCart.updateCart(event.body.cartItem, event.body.oldCartItem);
});

Roktのカートを更新する​

カートの変更がRokt側に反映される必要がある場合、Placementにメッセージを送信してそれを行うことができます。便利のために、Selection.sendメソッドを使用して選択された各Placementにメッセージを送信することができます。影響を受けるRoktのPlacementは、メッセージを受け取り、それに応じてアクションを実行します。このメッセージのペイロードについては、UpdateCartItemPartnerMessageBodyを参照してください。

注記

特定の変更は、設定によって実行されない場合がありますのでご注意ください。例えば、強制的なアップセルが最小数量1であり、パートナーからその選択を削除するメッセージがPlacementに送信された場合、Placementはそれを実行しません。

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

const selection = await launcher.selectPlacements({
  attributes: {
    // Roktがカタログアイテムを取得するために必要な属性
  },
});

selection.send("V2_UPDATE_CART_ITEM", payload);

プレースメントの利用可能性をチェックする​

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

// (...) Roktスクリプトの読み込み

const launcher = await Rokt.createLauncher({
  accountId: "roktAccountId",
  sessionId: "uniqueSessionId", // Roktバックエンドで生成されたセッションID
});

// (...) 統合ロジックの残り部分

プレースメントの妥当性を確認する​

一部のRoktオファーには、トランザクションフローを進める前に顧客が入力する必要があるフィールドが含まれています。これには、フォームの入力やオファーに対するはい/いいえの選択などがあります。

このようなタイプのオファーには、顧客に対して進行する前に行動を起こす必要があることを示すバリデーションメッセージが表示されます。

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

interface PlacementValidationStatus {
  // エラーがあるかどうかを素早く判断できます
  isValid: boolean;
  // バリデーションを持つプレースメントのリストです
  placements: Array<{
    // エラーを含むプレースメントの要素です。
    // エラーが存在する場合、それにスクロールすることができます
    element: HTMLIFrameElement;
    // プレースメントは独自のエラーメッセージを表示しますが、
    // エラーメッセージを別の場所で繰り返し表示したい場合に使用できる
    // エラーメッセージの配列です。妥当な場合は空になります
    errors: Array<{
      message: string;
    }>;
  }>;
}

使用例

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

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

// 顧客がこのボタンをクリックしたとき、プレースメントのバリデーションステータスを確認します
document.querySelector("button.check-validation").onclick = async () => {
  await selection.ready();  
  const result = await partnerValidation.getValidationStatus();

  // プレースメントに無効なプレースメントが含まれているかを素早く判断します
  console.log(result.isValid);

    // ループ処理
  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);
    }
  }
};
この記事は役に立ちましたか？