Roktとのクレジットカード統合
統合の概要
この統合ドキュメントでは、Roktが提供できる特定の統合機能について説明しています。現在の統合方法や潜在的な統合方法の網羅的なリストではありません。詳細については、アカウントディレクターと相談してください。
Roktは、Roktクレジットカードプロバイダーオーバーレイプラグインがホストするiframe内でアプリケーションフローをレンダリングします。このプラグインは以下の機能を持っています：
- Web SDKおよび親ページとの通信のプロキシとして機能します。
- お使いのドメインでホストされ、標準のWebアプリケーションである必要があります。
- Roktを介して提供する各ユニークなクレジットカードのデータフィールドには、アプリケーションページのURLを含める必要があります。
クレジットカードの申し込みページとRoktプラグインとの間のやり取りは、ブラウザベースのメッセージパッシングを介して有効になります。具体的な実装の詳細とコードサンプルは、以下に含まれています。
リアルタイムのアプリケーションの判断
クレジットカードの申し込みプロセスは、関連する配置コンテンツを表示するために、Roktとの間でプラグインのAPIを介してリアルタイムで申請の判断を通信する必要があります。後で解決される保留中の判断については、イベント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から送信されるイベントを安全に受信するために、ターゲットプラグインはウィンドウ上でメッセージイベントで受信した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" });
「準備完了」メッセージを送信する前に、メッセージイベントのリッスンを開始することが重要です。
Roktへのメッセージの送信
ターゲットプラグインは、取得したMessagePort上のpostMessageAPIを使用して親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の実装
以下は、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' }, '*')
}
使用方法:
const transport = new FrameTransport()
transport.on('config', body => {
console.log(body.creditCard)
})
transport.listen()
transport.send('complete', { status: 'approved' })
transport.send('close')