🐡

Salesforce Data Cloud Interactions SDKのスキーマファイルを調べてみた

2024/09/20に公開

sdk

Salesforce

datacloud

tech

TL;DR

Salesforce Data Cloudは、Salesforce製品だけでなく、S3や外部システム、さらにWebサイトやアプリのデータも取り込むことができます。Webサイトのユーザー情報や行動データを連携するには、Interactions SDKというWebSDKを使用し、それに対応するスキーマファイルを作成する必要があります。この記事では、主にスキーマファイルについて解説します。Salesforce Data Cloudは、Salesforce製品だけではなく、S3や外部システムの連携ができますが、Webやネイティブアプリ上のデータについても取り込むことができます。Webサイト内のユーザー情報や行動情報の連携にはInteractions SDK というWebSDKを利用する必要がありますが、それに合わせてとしてスキーマファイルの作成も必要です。本記事ではスキーマファイルについて解説したいと思います。

WebSDKの仕組み

Webサイトのデータをトラッキングするためには、以下の手順が必要です:

WebSDKをサイトに埋め込む（HTMLに直接、またはタグマネージャー経由）
トラッキングのタイミングや取得するデータを定義する（Sitemap）
Sitemapに記述したJavaScriptコードは自動的にWebSDKのソースコードに出力されるため、サイト側での追加の実装は基本的に不要です。

こちらのページにSitemapのサンプルがあります。SalesforceInteractionsというのはWebSDKのクラス名ですが、DOM操作用のメソッドも提供しており、jQueryのような感覚で使えるので便利です。

SalesforceInteractions.init().then(() => {
  const { 
    listener, 
    CatalogObjectInteractionName,
    resolvers
  } = SalesforceInteractions
  
  const global = {
    locale: 'en_US',
    listeners: [
      listener('click', '.item', (event) => {
        SalesforceInteractions.sendEvent({
            interaction : {
                name : "Quick View Catalog Object",
                catalogObject: { 
                  type : "Product", 
                  id : "65e4e737",
                  attributes: {
                    description: "Shoes"
                  }
                }
            }
        })
      })
    ],
    onActionEvent: (actionEvent) => {
      console.log(actionEvent)
    }
  }
  
  const pageTypeDefault = {...}
  
  const pageTypes = [...]
  
  SalesforceInteractions.initSitemap({ 
    global, 
    pageTypes,
    pageTypeDefault 
  })
})

スキーマファイル

Sitemapで指定したデータをData Cloudに送信するには、あらかじめデータ形式をスキーマファイルとして登録しておく必要があります。

スキーマファイルの構造

スキーマファイルのサンプルは、こちらからダウンロードすることができます。スキーマファイルは以下のような構造を持ちます。

{
    "records": [
        {
            "masterLabel": "イベント表示名",
            "developerName": "Data Cloud内で実際に利用されるイベント名",
            "category": "Engagement or Profile",
            "externalDataTranFields": [
                // データ属性の定義
            ]
        }
    ]
}

recordsの配列には、各種取得データがオブジェクト形式で格納されています。下記は、ボタンクリックのデータを取得するためのオブジェクトを記載した例です。

{
    "records": [
        {
          "masterLabel": "Button Click",
          "developerName": "buttonClick",
          "category": "Engagement",
          "externalDataTranFields": [
            {
              "masterLabel": "category",
              "dataType": "Text",
              "developerName": "category",
              "isDataRequired": true
            },
            {
              "masterLabel": "dateTime",
              "dataType": "DateTime",
              "developerName": "dateTime",
              "isDataRequired": true
            },
            {
              "masterLabel": "deviceId",
              "dataType": "Text",
              "developerName": "deviceId",
              "isDataRequired": true
            },
            {
              "masterLabel": "eventId",
              "dataType": "Text",
              "developerName": "eventId",
              "isDataRequired": true,
              "primaryIndexOrder": 1
            },
            {
              "masterLabel": "eventType",
              "dataType": "Text",
              "developerName": "eventType",
              "isDataRequired": true
            },
            {
              "masterLabel": "sessionId",
              "dataType": "Text",
              "developerName": "sessionId",
              "isDataRequired": true
            },
            {
              "masterLabel": "interactionName",
              "dataType": "Text",
              "developerName": "interactionName",
              "isDataRequired": false
            },
            {
              "masterLabel": "pageView",
              "dataType": "Number",
              "developerName": "pageView",
              "isDataRequired": false
            },
            {
              "masterLabel": "sourceChannel",
              "dataType": "Text",
              "developerName": "sourceChannel",
              "isDataRequired": false
            },
            {
              "masterLabel": "sourceLocale",
              "dataType": "Text",
              "developerName": "sourceLocale",
              "isDataRequired": false
            },
            {
              "masterLabel": "sourcePageType",
              "dataType": "Text",
              "developerName": "sourcePageType",
              "isDataRequired": false
            },
            {
              "masterLabel": "sourceUrl",
              "dataType": "Text",
              "developerName": "sourceUrl",
              "isDataRequired": false
            },
            {
              "masterLabel": "sourceUrlReferrer",
              "dataType": "Text",
              "developerName": "sourceUrlReferrer",
              "isDataRequired": false
            },
            {
              "masterLabel": "clickTarget",
              "dataType": "Text",
              "developerName": "clickTarget",
              "isDataRequired": false
            },
            {
              "masterLabel": "customSessionId",
              "dataType": "Text",
              "developerName": "customSessionId",
              "isDataRequired": false
            }
          ],
          "fieldCount": 17,
          "availabilityStatusLabel": {
            "label": "使用中",
            "rawValue": "INUSE"
          },
          "streamingAppLabel": "コネクタ名"
        }
    ]
}

各種項目については、こちらが参考になります。
また、externalDataTranFieldsについては、こちらに参考情報があります。

必須属性

externalDataTranFieldsには、以下の6つの属性が必須です。

deviceId
eventId
dateTime（ISO8601形式）
eventType
category
sessionId

カスタム属性の追加

必要に応じて、カスタム属性を追加できます。

{
  "masterLabel": "clickTarget",
  "dataType": "Text",
  "developerName": "clickTarget",
  "isDataRequired": false
}

その他の連携データ項目を追加して、スキーマファイルをアップロードすると、次のような画面が表示されます。

データの送信

Sitemapにイベント送信コードを記述します。

listener('click', '.button-1', () => {
    SalesforceInteractions.sendEvent({
        interaction: {
            name: 'buttonClick',
            clickTarget: 'ボタン1',
        },
    })
})

Data Streamを作成し、サイト上でボタンをクリックすると、データがData Cloudに取り込まれます。

この記事を通じて、Salesforce Data CloudとWebサイトデータの連携方法、特にスキーマファイルの重要性と構造について理解を深めていただければ幸いです。

※本記事は、私が所属する会社とは一切関係のない事柄です。