Roktによるクレジットカード統合

統合概要

注記

この統合ドキュメントは、Roktが提供できる特定の統合機能について説明しています。現在または将来の統合方法の網羅的なリストではありません。詳細を話し合うには、アカウントディレクターにご相談ください。

Roktは、Roktクレジットカードプロバイダーオーバーレイプラグインによってホストされるiframe内でアプリケーションフローをレンダリングします。このプラグインは:

• Web SDKおよび親ページとの通信をプロキシします。
• あなたのドメインでホストされ、標準のウェブアプリケーションである必要があります。
• Roktを介して提供する各ユニークなクレジットカードのデータフィールドにアプリケーションページのURLを含める必要があります。

クレジットカード申請ページとRoktプラグイン間の相互作用は、ブラウザベースのメッセージパッシングを介して有効になります。コードサンプルを含む具体的な実装の詳細は以下に記載されています。

リアルタイムアプリケーション決定

クレジットカード申請プロセスは、関連する配置コンテンツを表示するために、プラグインのAPIを介してRoktとリアルタイムで申請決定を通信する必要があります。後で解決される保留中の決定については、Event APIまたは他のデータ配信メカニズムを介してこれらの結果をRoktに返すべきです。

アプリケーションをiframeでホスティングする

パートナーページの上に直接サードパーティのクレジットカード申請ワークフローを有効にするために、Roktはターゲットのクレジットカード申請フォームをiframe内に埋め込むラッパープラグインを管理します。

コンテンツセキュリティポリシーの考慮事項

クレジットカード申請フォームのコンテンツセキュリティポリシーがRoktのドメイン（https://apps.rokt.com）を介してホスティングを許可していることを確認してください。そうでない場合、Roktのプラグインは関連するページでアプリケーションフォームをホスティングできません。

Iframeのサイズ

Roktのクレジットカードプラグインは、ユーザーの画面に合わせてクレジットカード申請をリサイズし、中央に配置し、背景のグラデーションを作成します。

プラグインタイムアウト時の削除

Roktは、iframe/プラグインの状態を監視し、iframeが正しく読み込まれない場合でも最適なユーザーエクスペリエンスを保証します。このため、Rokt Web SDKは、ターゲットプラグインがonloadイベントを発行した後、MessagePortハンドシェイクを待つタイマーを開始します。これにより、タイムアウトが発生してプラグインがハングしたことを示す場合、RoktのWeb SDKはプラグインを削除できます。

<script>タグに適用される属性は、ターゲットスクリプト内のJavaScriptが完全に評価される前にドキュメントのonloadイベントをトリガーします。これにより、遅いデバイスではJavaScriptの評価にタイムアウトが許容する以上の時間がかかる可能性があります。このため、プラグイン初期化ロジックを含む<script>は同期的にロードされることが重要です。

メッセージによる通信

注記

このドキュメントの最後には、このハンドシェイクを示す実装があり、ターゲットアプリケーションに直接コピーできます。以下では、このハンドシェイクについて詳しく説明します。

メッセージ形式

RoktのWeb SDKは、初期ハンドシェイク後に取得したMessagePortを通じて、ブラウザのpostMessage APIを使用してターゲットプラグインにデータを送信します。

メッセージの詳細は、イベントのevent.dataプロパティに提供され、以下の構造に従います:

type PluginMessage = {
  type: PluginMessageAction
  payload?: BasicObject
}

Roktプラグインへの初期接続

Roktドメインでホストされているiframeからのイベントを安全にリッスンするために、ターゲットプラグインは、window上のメッセージイベントで受信したMessagePortを取得し、リッスンする必要があります。

このMessagePortは、2つのフレーム間の通信を促進し、イベントがドメインによってフィルタリングされることを保証します。これにより、ターゲットプラグインがRokt以外のエンティティによって不正に開かれないようにします。

以下は、Roktプラグインとの通信を初期化するための設定例です:

// メッセージポートのリッスンを開始
const onPort = new Promise((res) => {
  function onPort(event) {
    // 信頼できないドメインをフィルタリング
    if (event.origin.endsWith(".rokt.com")) {
      window.removeEventListener("message", onPort);
      res(event.ports[0]);
    }
  }
  window.addEventListener("message", onPort);
});

// 空のメッセージは、ターゲットプラグインがMessagePortを受信する準備ができていることを親に示します
window.parent.postMessage({ type: 'send-port' }, "*");

// ポートが到着したとき
const port = await onPort;

// ポート上でpostMessageイベントのリッスンを開始
port.addEventListener("message", (event) => {
  const { type, payload } = event.data;
});

// MessagePortにメッセージの送信を開始させ、
// バッファされたメッセージを再生
port.start();

// Rokt Web SDKにメッセージを送信
port.postMessage({ type: "close" });

注記

「ready」メッセージを送信する前に、メッセージイベントのリッスンを開始することが重要です

Roktへのメッセージ送信

ターゲットプラグインは、取得したMessagePort上でpostMessage APIを使用して親Roktフレームにメッセージを送信できます。

// ...

port.postMessage({ type: 'close' })

イベント

Roktプラグインからクレジットカードアプリケーションへのイベント

• イベント名: config

プラグインが起動した際に一度送信され、正しくレンダリングするために必要なすべての情報を含みます。

type Payload = {
  creditCard: unknown
  offer: unknown
  partner: {
    name: string
  }
}

注記

configペイロードに見つかるフィールドを事前入力することで、申請者のアプリケーションの摩擦を減らします

クレジットカードアプリケーションからRoktプラグインへのイベント

• イベント名: complete

顧客がアプリケーションを完了した際に送信され、完了ステータスを示します。

type Payload = {
  status:
    'approved' |
    'pending' |
    'declined'
}

• イベント名: interactive

プラグインのUIがインタラクティブになった際に送信されます - ユーザーによってレンダリングされ、操作可能であると定義されます。

これはプラグインによって手動でトリガーされ、通常は使用されているフレームワークの初期レンダリングサイクルの後に行われます。

void

• イベント名: close

プラグインがパートナーページから削除される準備が整った際に送信されます。

これにより、ターゲットプラグイン内のJavaScriptのさらなる実行が停止され、ページから削除されます。

void

• イベント名: failure

プラグインが重大なエラーで失敗し、パートナーページからの削除が必要な場合に送信されます。

これにより、ターゲットプラグイン内のJavaScriptのさらなる実行が停止され、ページから削除されます。

void

Example FrameTransport Implementation

以下は、MessagePortハンドシェイクのためのラッパー実装で、消費のための簡略化されたAPIです。これはシンプルな出発点として意図されており、コピーしてES6クラスやTypeScriptに変換するか、そのまま使用することができます。

export function FrameTransport() {
  const onPort = new Promise(res => {
    const onMessage = (event) => {
      if (event.origin.endsWith(".rokt.com")) {
        window.removeEventListener('message', onMessage)
        res(event.ports[0]);
      }
    }
    window.addEventListener('message', onMessage)
  })

  this.on = async (type, callback) => {
    const port = await onPort
    port.addEventListener('message', event => {
      if (event.data.type === type) {
        callback(event.data.payload)
      }
    })
  }

  this.send = async (type, body) => {
    const port = await onPort
    port.postMessage({ type, payload: body })
  }

  this.listen = async () => {
    const port = await onPort
    port.start()
  }

  window.parent.postMessage({ type: 'send-port' }, '*')
}

Usage:

const transport = new FrameTransport()

transport.on('config', body => {
  console.log(body.creditCard)
})

transport.listen()

transport.send('complete', { status: 'approved' })
transport.send('close')