この文章は Salesforce 機械翻訳システムを使用して翻訳されました。詳細はこちらをご参照ください。

Customer Data Platform Web SDK

Customer Data Platform Web SDK は、イベントを Customer Data Platform に送信するように Web サイトを設定するための低レベル API です。顧客エンゲージメントデータとユーザプロファイルデータの両方を収集して Customer Data Platform に送信するように Web サイトを設定します。同意管理システムが組み込まれており、ユーザが許可した場合にのみデータを収集できるようになっています。これらのコールはアプリケーションインターフェースから使用することで最大限に活用できますが、テナント固有のエンドポイントを使用してメソッドを外部からコールすることもできます。

新しいバージョンの Web SDK を使用できます。Customer Data Platform Web SDK バージョンをまだ実装していない場合は、最新の Salesforce Interactions SDK バージョンを実装することをお勧めします。

重要

前提条件

Customer Data Platform Web SDK を使用するには、Salesforce データソースコネクタを作成します。Customer Data Platform にログインして Web コネクタを設定します。設定についての詳細は、「Customer Data Platform 実装ガイド」を参照してください。

Web サイトコネクタのソース ID とテナント固有のエンドポイントを使用して Customer Data Platform Web SDK を初期化します。

SDK のダウンロード

Customer Data Platform Web SDK のソースを次からダウンロードします。

Customer Data Platform Web SDK

SDK の設定

Web SDK は、この設定オブジェクトを消費してイベントリスナを自動的に生成し、関連 DOM 要素に割り当てます。設定オブジェクトの構造には、次のようにいくつかの属性があります。client 以外のすべての属性は省略可能です。

SDK の設定: クライアントパラメータ

設定	型	説明
appSourceId	String	必須。この値は、Salesforce システム管理者から入手してください。
beaconEndpoint	String	必須。次の構造を使用します。 .
authEndpoint	String	次の構造を使用します。 .
deviceId	String	クライアント設定で定義することもできます。指定しなかった場合は、SDK によって作成、管理される識別子が使用されます。
sessionId	String	Web SDK によって自動的に入力されます。
consentEventTypeName	String	同意イベント種別の名前を設定します。ほとんどの設定ではデフォルト名の `consentLog` で問題ありません。
retryAttempts	Integer	ビーコンサービスへの送信に失敗したイベントの再試行回数です。
retryDelayMS	Integer	ビーコンサービスへの送信に失敗したイベントの再試行間隔 (ミリ秒) です。
automaticallyTrackNavigationEvents	Boolean	このフラグを有効にすると、Web SDK はユーザによるページナビゲーションイベントを追跡して、`document.location.hash` と `document.location.pathname` を取得します。

SDK の設定: 信号

信号は、Web SDK エンジンがイベントリスナをページ上の適切な DOM 要素に割り当てるために使用する、設定オブジェクトの主要部分です。信号は設定の重要なピースであり、初期化後に更新する必要があります。信号の name、schema、category は必須項目です。

CDP.configure メソッドをコールすると、新しい信号セットが登録される前に、ページ上のすべての登録済み信号が削除されます。

メモ

SDK の設定: 信号の対応付け

登録済み信号の mapping 項目は、Web ページからデータを取得して信号の対象スキーマセット項目に対応付けるために使用されます。2 つの対応付け設定がサポートされます。

ページ

ページ対応付けでは、セレクタと一致する要素のテキスト値を取得して、スキーマイベント項目の値として使用します。scope 値は、DOM 内のどの要素を使用してセレクタクエリを実行するかを制御します。event は、取得する信号をトリガした要素を示します。他のすべての値は、ドキュメントのルートから開始されたことを示します。
データ

データ対応付けは、データプロバイダから返された値を取得します。データプロバイダは、JavaScript オブジェクトを返します。attribute 値は、そのオブジェクトの対象属性をスキーマイベント項目に対応付けるために使用されます。

SDK の設定: セレクタ

信号内で参照されるすべてのセレクタはここで設定します。各セレクタは、1 つ以上の DOM 要素を返します。Web SDK では 3 種類のセレクタがサポートされます。

セレクタは、DOM 要素へのパスを定義する CSS セレクタのみでも構成できます。
セレクタは、CSS セレクタと、パスの最後の要素を示すテキスト属性で構成できます。
CSS セレクタとテキストの一致だけでは必要な機能を実装できない特別なケースには、カスタム JavaScript を作成して対応できます。

SDK の設定: スキーマ

スキーマをエクスポートして SDK に読み込みます。

SDK の設定: データプロバイダ

データプロバイダは、画面上の要素から直接取得できない情報を提供します。これらは、データレイヤから JavaScript オブジェクトを返す関数です。この関数は、処理する信号をトリガしたイベントが含まれる domEvent パラメータを渡します。

設定オブジェクトの例

SDK の初期化

ページ上での SDK のライフサイクルの最初のステップは初期化です。初期化では、パラメータを設定 (例: Web サイトコネクタのソース ID を appSourceId に設定) し、テナント固有のエンドポイントから作成された承認エンドポイントやビーコンエンドポイントを SDK に渡します。

CDP.initialize(CONFIG) - 初期読み込み時に SDK を設定します。クライアントの設定が必要です。
CDP.register(CONFIG) - 設定パラメータを更新、作成、上書きします。

URL からのパラメータの取得

Web サイトのユーザ追跡コードで実行する一般的な動作として、URL で渡されたクエリパラメータから値を取得することがあります。Customer Data Platform Web SDK には次の get 関数が用意されており、Web アドレスからパラメータを取得します。

イベントの送信

Customer Data Platform Web SDK の主な機能は、Web サイトから Customer Data Platform に信号を送り戻すことです。複雑なバックグラウンド処理の大半は sendEvent() メソッドが担ってくれるため、開発者は承認の処理、ペイロードの作成、接続の管理などに煩わされることなく、送信するデータの収集に集中できます。送信イベントはスキーマと一致する必要があります。

この例では、商品ビューエンゲージメントイベントを送信しています。商品データは、DOM、データオブジェクト、URL パラメータ、またはこれらのソースの組み合わせから取得されます。すべての Customer Data Platform イベントの必須項目は SDK によって入力され、提供されたイベントデータと組み合わされます。

デフォルトでは、SDK は GET でイベントを送信しますが、イベントペイロードが 1024 文字を超える場合は、コンテンツ種別の application/x-www-form-urlencoded を使用した POST を実行します。

同意の管理

Customer Data Platform Web SDK は、セッションを超えて同意設定を維持しません。各サイトビジターごとに同意設定を渡してください。この設定により、Web サイトで使用している既存の同意管理ソリューションに SDK を容易に統合できます。

使用している同意管理システムからのコールバックで下記の関数を使用してください。SDK が保存している Cookie は、Web サイトの同意管理には使用できません。SDK は、イベントを送信する前に同意が得られているかどうかを確認するだけです。

このコールは、トリガされたアクションをイベントとして通知する許可を SDK に付与します。このコールは、CDP.consentOptIn(); イベントを送信して、ユーザがオプトインしたことを示す Cookie を作成します。以降のページ読み込み時にこの Cookie が存在すると、直ちにイベントの転送が開始されます。

このコールは、同意を削除してイベントの送信を中止します。Cookie が削除され、イベントの転送が直ちに停止します。

Customer Data Platform 開発者ガイド