Customer Data Platform 開発者ガイド
jCustomer Data Platform Web SDK
前提条件
Customer Data Platform Web SDK を使用するには、Salesforce データソースコネクタを作成します。Customer Data Platform にログインして Web コネクタを設定します。設定についての詳細は、「Customer Data Platform 実装ガイド」を参照してください。
Web サイトコネクタのソース ID とテナント固有のエンドポイントを使用して Customer Data Platform Web SDK を初期化します。
SDK のダウンロード
SDK の設定
Web SDK は、この設定オブジェクトを消費してイベントリスナを自動的に生成し、関連 DOM 要素に割り当てます。設定オブジェクトの構造には、次のようにいくつかの属性があります。client 以外のすべての属性は省略可能です。
1{
2 client: {},
3 signals: [],
4 selectors: {},
5 schemas: {},
6 dataProviders: {}
7}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 は必須項目です。
1{
2 name: 'signal name',
3 schema: 'developerName of schemaEvent',
4 category: 'category', // example: engagment
5 event: {
6 type: 'click',
7 selector: 'reference to selector name'
8 },
9 mapping: {
10 "developerName of schemaEvent field": {
11 from: 'page',
12 selector: 'css selector or reference to selector name'
13 }
14 }
15}SDK の設定: 信号の対応付け
-
ページ
1signal: { 2 ... 3 mapping: { 4 "schemaFieldDeveloperName": { 5 from: "page", 6 selector: "css selector or reference to selector name", 7 scope: "event" 8 } 9 } 10}ページ対応付けでは、セレクタと一致する要素のテキスト値を取得して、スキーマイベント項目の値として使用します。scope 値は、DOM 内のどの要素を使用してセレクタクエリを実行するかを制御します。event は、取得する信号をトリガした要素を示します。他のすべての値は、ドキュメントのルートから開始されたことを示します。
-
データ
1signal: { 2 ... 3 mapping: { 4 "schemaFieldDeveloperName": { 5 from: "data", 6 provider: "dataProviderName", 7 attribute: "attributeName" 8 } 9 } 10}データ対応付けは、データプロバイダから返された値を取得します。データプロバイダは、JavaScript オブジェクトを返します。attribute 値は、そのオブジェクトの対象属性をスキーマイベント項目に対応付けるために使用されます。
SDK の設定: セレクタ
信号内で参照されるすべてのセレクタはここで設定します。各セレクタは、1 つ以上の DOM 要素を返します。Web SDK では 3 種類のセレクタがサポートされます。
- セレクタは、DOM 要素へのパスを定義する CSS セレクタのみでも構成できます。
- セレクタは、CSS セレクタと、パスの最後の要素を示すテキスト属性で構成できます。
- CSS セレクタとテキストの一致だけでは必要な機能を実装できない特別なケースには、カスタム JavaScript を作成して対応できます。
1selectors: {
2 "unique selector name": {
3 selector: '<CSS selector (e.g. ul li.productName)>'
4 },
5 "unique selector name": {
6 selector: '<CSS selector (e.g. ul li.productName)>',
7 containsText: "<Text pattern to match inside the DOM Element(s).>"
8 },
9 "unique selector name": {
10 selector: function() {
11 // Creating a dynamic selector based on data from the page's data layer
12 return document.getElementById("product_" + dataLayer.get('currentProductId'));
13 }
14 }
15}SDK の設定: スキーマ
スキーマをエクスポートして SDK に読み込みます。
1schemas: {
2 schemaId: {
3 ...
4 }
5 }SDK の設定: データプロバイダ
データプロバイダは、画面上の要素から直接取得できない情報を提供します。これらは、データレイヤから JavaScript オブジェクトを返す関数です。この関数は、処理する信号をトリガしたイベントが含まれる domEvent パラメータを渡します。
1dataProviders: {
2 functionName (domEvent) {
3 return <data based on the input param>
4 }
5 }設定オブジェクトの例
1{
2 signals: [
3 {
4 name: 'Remove from cart button',
5 category: "Engagement",
6 schema: 'RemoveFromCart',
7 event: {
8 type: 'click',
9 selector: "remove from cart button selector"
10 },
11 providers: [
12 'productCatalog'
13 ],
14 mapping: {
15 ProductId: {
16 from: 'data',
17 provider: 'productCatalog',
18 attribute: 'ProductId'
19 },
20 ShoppingCartId: {
21 from: 'data',
22 provider: 'productCatalog',
23 attribute: 'ShoppingCartId'
24 }
25 }
26 },
27 {
28 name: 'Add to cart button',
29 schema: 'AddToCart',
30 category: "Engagement",
31 event: {
32 type: 'click',
33 selector: "add to cart button selector"
34 },
35 providers: [
36 'productCatalog'
37 ],
38 mapping: {
39 ProductId: {
40 from: 'data',
41 provider: 'productCatalog',
42 attribute: 'ProductId'
43 },
44 ShoppingCartId: {
45 from: 'data',
46 provider: 'productCatalog',
47 attribute: 'ShoppingCartId'
48 }
49 }
50 },
51 {
52 name: 'Username typed',
53 schema: 'usernameTyped',
54 category: 'Profile',
55 event: {
56 type: 'keydown',
57 selector: "username textbox"
58 },
59 mapping: {
60 username: {
61 from: 'page',
62 selector: "username textbox",
63 scope: 'document'
64 }
65 }
66 },
67 {
68 name: 'Product click',
69 schema: 'ProductViewed',
70 category: "Engagement",
71 event: {
72 type: 'click',
73 selector: "product selectors"
74 },
75 providers: [
76 'productCatalog'
77 ],
78 mapping: {
79 ProductId: {
80 from: 'data',
81 provider: 'productCatalog',
82 attribute: 'ProductId'
83 }
84 }
85 },
86 {
87 name: 'opt-in',
88 schema: 'consent-opt-in',
89 category: "Consent",
90 event: {
91 type: 'click',
92 selector: "consent opt-in selector"
93 }
94 },
95 {
96 name: 'opt-out',
97 schema: 'consent-opt-out',
98 category: "Consent",
99 event: {
100 type: 'click',
101 selector: "consent opt-out selector"
102 }
103 }
104 ],
105 dataProviders: {
106 productCatalog (domEvent) {
107 return {
108 "ProductId": "product-id-9aba47743f27",
109 "ShoppingCartId": "shopping-cart-id-9aba47743f27"
110 }
111 }
112 },
113 selectors: {
114 "remove from cart button selector": {
115 selector: 'body > div.wrapper.svelte-1a3asx9 > main > div > div.slds-col.slds-size_2-of-3 > div:nth-child(3) > div:nth-child(2) > div:nth-child(6) > button:nth-child(2)'
116 },
117 "add to cart button selector": {
118 selector: 'button.slds-button.slds-button_destructive',
119 containsText: "ADD"
120 },
121 "product selectors": {
122 selector: function() {
123 return document.querySelectorAll('.stencil');
124 }
125 },
126 "consent opt-in selector": {
127 selector: '#dialog-body-id-42 > a > div > p > button.slds-button.slds-button_brand'
128 },
129 "consent opt-out selector": {
130 selector: '#dialog-body-id-42 > a > div > p > button.slds-button.slds-button_destructive'
131 },
132 "username textbox": {
133 selector: '#username'
134 }
135 }
136}SDK の初期化
1window.addEventListener('load', (event) => {
2 const CONFIG = {
3 client: {
4 "appSourceId": "app source id as guid",
5 "deviceId": "deviceId as guid", // optional
6 "beaconEndpoint": "http://server.internal:8080/web/events",
7 "authEndpoint": "http://server.internal:8080/web/authentication"
8 }
9 };
10 CDP.initialize(CONFIG);
11});- CDP.initialize(CONFIG) - 初期読み込み時に SDK を設定します。クライアントの設定が必要です。
- CDP.register(CONFIG) - 設定パラメータを更新、作成、上書きします。
URL からのパラメータの取得
Web サイトのユーザ追跡コードで実行する一般的な動作として、URL で渡されたクエリパラメータから値を取得することがあります。Customer Data Platform Web SDK には次の get 関数が用意されており、Web アドレスからパラメータを取得します。
1CDP.getUrlParam('trackingId')イベントの送信
1CDP.sendEvent("engagement", "ProductView", productData)この例では、商品ビューエンゲージメントイベントを送信しています。商品データは、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 は、イベントを送信する前に同意が得られているかどうかを確認するだけです。
1CDP.consentOptIn();このコールは、トリガされたアクションをイベントとして通知する許可を SDK に付与します。このコールは、CDP.consentOptIn(); イベントを送信して、ユーザがオプトインしたことを示す Cookie を作成します。以降のページ読み込み時にこの Cookie が存在すると、直ちにイベントの転送が開始されます。
1CDP.consentOptOut();このコールは、同意を削除してイベントの送信を中止します。Cookie が削除され、イベントの転送が直ちに停止します。