Salesforce CDP Mobile SDK | Salesforce CDP API 開発者ガイド

前提条件

Salesforce CDP Mobile SDK を使用するには、Salesforce データソースコネクタを作成して、エンドポイントを自動生成します。Salesforce CDP アプリケーションにログインして、[Web サイトおよびモバイルアプリケーション] 画面の左側のパネルに移動します。ユーザインターフェースでアプリケーションコネクタを作成することで、データソースを設定します。詳細は、『Salesforce CDP 実装ガイド』を参照してください。

Web データコネクタから取得した appSourceId と生成されたエンドポイントを使用して Salesforce CDP Mobile SDK を初期化します。

SDK のダウンロード

Salesforce CDP Mobile SDK を次のいずれかのソースからダウンロードします。

Android
iOS

SDK のインストール

Salesforce CDP Mobile SDK をモバイルアプリケーションに追加するには、CocoaPods を使用するか、またはソースコードにコールを組み込みます。

CocoaPods

CocoaPods は、プロジェクト用のサードパーティライブラリを容易に一元管理できるようにする場所を提供します。CocoaPods を使用して Salesforce CDP Mobile SDK を iOS モバイルアプリケーションに統合するには、Podfile を作成して連動関係を追加します。

1use_frameworks!
2          
3          target '<Your Target>' do
4             pod 'SALESFORCE-CDP-SDK-IOS-SDK', '~> 1.0'
5          end

手動でのインストール

手動でインストールするには、自分で書いたコードですべての連動関係を管理する必要があります。複数のライブラリが連動関係を共有していて、それぞれが異なるバージョンを指定できる場合には、すべての連動関係を満足する最適なライブラリバージョンをモバイルアプリケーション開発者の責任で指定する必要があります。

SDK の設定

API を使用する Web サービスを Salesforce CDP Mobile SDK を使用して呼び出すためには、事前に設定が必要です。CdpConfigBuilder ヘルパークラスを使用して SDK を設定し、必要な appId とエンドポイントを指定します。必要に応じて trackScreens、trackLifecycle、sessionTimeout も設定します。

1let config = CdpConfigBuilder(appId: {REPLACE WITH APP ID}, endpoint: {REPLACE WITH ENDPOINT})
2       .trackScreens({True|False})
3       .trackLifecycle({True|False})
4       .sessionTimeout({Int})
5       .build()

SDK の設定手順

Salesforce CDP Mobile SDK は 2 ステップの手順で使用できるようになります。

Salesforce CDP Mobile SDK を設定して、Salesforce CDP の (UUID 形式の) アプリケーション ID と Salesforce Tenant Specific Endpoint (TSE) を指定します。
1let config = CdpConfigBuilder(appId: {REPLACE WITH APP ID}, endpoint: 2 {REPLACE WITH ENDPOINT}).build()

Salesforce CDP Mobile SDK を初期化します。

1_ = CdpSdk.configure(config)
2          Congratulations! The CDP SDK is now configured and ready to use. You can verify that by inspecting the state of the CDP SDK instance:
3          CdpSdk.shared.state
4          Example output:
5          {
6            "name":"cdp",
7            "config": {
8               "sessionDuration":600,
9               "screenTrackingEnabled":false,
10               "lifecycleEventTrackingEnabled":false,
11               "appId":"YOUR APP ID",
12               "endpoint":"YOUR ENDPOINT"
13            },
14            "consentManager":{
15               "deviceId":"YOUR DEVICE ID",
16               "consent":"pending"
17            },
18            "eventManager":{
19               "queueSize":0
20            },
21            "sessionManager":{
22               "sessionId":"SESSION ID"
23            }
24          }

設定しなかったプロパティではデフォルト値が使用されます。

設定パラメータ

Salesforce CDP Mobile SDK の設定パラメータを下表に示します。

設定	型	説明
appId	string	必須。appId 設定は、モバイルアプリケーションを Salesforce CDP プラットフォームに対して一意に識別し、有効な UUID (ユニバーサル一意識別子) の形式で指定する必要があります。CdpSdkBuilder に対して無効な appID を指定すると、致命的なエラーが発生します。
endpoint	string	必須。endpoint 設定は、作成および追跡されるイベントを Salesforce CDP Mobile SDK Web サービスがどこに送信すべきかを指定します。エンドポイントは、次の形式の有効な Salesforce CDP URL である必要があります。 `1https://{tenant specific 2 endpoint id}.c360a.salesforce.com. [description here of allowed domains]` CdpSdkBuilder に対して無効なエンドポイントを指定すると、致命的なエラーが発生します。
trackScreens	boolean	省略可能。デフォルトは false です。trackScreens を有効化すると、モバイルアプリケーションの ScreenEntry イベントを自動的に追跡します。イベントは、イベントタイプが「ScreenView」、属性が「screenname」のエンゲージメントイベントとして収集されます。
trackLifecycle	boolean	省略可能。デフォルトは false です。trackLifecycle を有効化すると、アプリケーションライフサイクルイベントの AppForegrounded と AppVersionChanged を自動的に追跡します。イベントはエンゲージメントイベントして収集されます。AppVersionChanged イベントのイベントタイプは「AppUpdate」、属性は「previousVersion」です。AppForegrounded イベントのイベントタイプは「AppFirstLaunch」または「AppLaunch」で、属性はありません。
sessionTimeoutInSeconds	int	省略可能。デフォルトは 600 です。sessionTimeoutInSeconds 設定は、モバイルアプリケーションがバックグラウンドの状態で何秒経過したら現在のセッションが期限切れになるかを表します。セッション管理は次のように行われます。まず、エンドユーザがモバイルアプリケーションを起動すると、Salesforce CDP Mobile SDK は新しいセッションを開始します。このセッションは、アプリケーションがフォアグラウンドの状態のときに維持されます。ユーザがモバイルアプリケーションをバックグラウンドに送ると、SDK はタイマーを起動して、現在のセッションが期限切れになるまでの時間を計測します。セッションが期限切れになる前にユーザがモバイルアプリケーションをフォアグラウンドに戻すと、タイマーがクリアされてセッションが継続します。そうでなければセッションが終了します。

次に、CdpSdk オブジェクトに対して configure メソッドをコールして、定義されている設定で共有インスタンスをインスタンス化します。

1let sdk = CdpSdk.configure(config)

これで、Salesforce CDP Mobile SDK がイベントを収集できるようになります。Salesforce CDP Mobile SDK シングルトンインスタンスは、CdpSdk.shared を使用して参照します。

1CdpSdk.shared

初期化済みの Salesforce CDP Mobile SDK インスタンスの設定を変更することはできませんので注意してください。再び CdpSdk.configure() をコールすると、既存のインスタンスは破壊され、新しい Salesforce CDP Mobile SDK インスタンスが作成されます。

1// Initially
2        <Cdp.CdpSdk: 0x600001854780>
3          // After reconfiguring
4          <Cdp.CdpSdk: 0x600001865da0>

ログレベル

ログは任意ですが重要な SDK の機能です。モバイルアプリケーション開発者は、Salesforce CDP Mobile SDK の出力の詳細レベルを選択できます。ログはデフォルトでは無効化されており、CdpSdk 共有インスタンスに対して setLogLevel メソッドで有効化して、ログレベルとログ出力を定義する必要があります。これにより、ネイティブな統合ログシステムを使用してログが取得されます。

ログパラメータ

1CdpSdk.setLogLevel(MCLogLevel.debug, logOutputter: LogOutputter())

パラメータ	型	説明
logLevel	MCLogLevel	必須。ログ出力の詳細レベルを定義します。使用できるオプションは、error、warning、debug、none です。
logOutputter	LogOutputter	必須。出力を定義します。ネイティブな統合ログシステムを使用してログを取得します。

ログレベルの定義

ログレベル	デフォルト	説明
MCLogLevel.error	いいえ	このログレベルは、重要なビジネス使用事例が完了できなくなる、復旧不能なエラーの詳細を提供します。
MCLogLevel.warning	いいえ	このログレベルは、SDK インテグレーションに問題があるか、普段とは異なる状況に遭遇した状況の詳細を提供します。警告は、潜在的に危険ではあるものの復元可能なエラーに関連付けられます。
MCLogLevel.debug	いいえ	省略可能。このログレベルは、SDK がタスク、イベント、エラーの詳細をどのように処理したかに関する詳細な低レベルの情報を提供します。デバッグログにより、開発者はアプリケーションを診断して問題をトラブルシューティングできます。
trackLifecycle	はい	省略可能。ログを無効化します。

SDK の state プロパティ

Salesforce CDP Mobile SDK の共有インスタンスの state プロパティは、現在の設定、セッションの詳細、イベントキューサイズ、同意情報が含まれた JSON を返します。これらは、デバッグとトラブルシューティングで重要な情報となります。

1CdpSdk.shared.state

state プロパティは、開発とトラブルシューティングをサポートする Salesforce CDP Mobile SDK のツールの 1 つです。デバッグを行うときは必ず SDK の state プロパティで設定が想定どおりであることを確認してください。Salesforce CDP Mobile SDK の state プロパティの例:

1{
2      "name":"cdp",
3      "config": {
4          "screenTrackingEnabled":false,
5          "lifecycleEventTrackingEnabled":false,
6          "appId":"YOUR APP ID",
7          "endpoint":"YOUR ENDPOINT"
8          "sessionDuration":600
9      },
10      "sessionManager": {
11          "sessionId":"SESSION ID"
12      },
13      "eventManager": {
14          "queueSize":2
15      },
16      "consentManager": {
17          "deviceId":"YOUR DEVICE ID",
18          "consent":"opt_in"
19      }
20   }

同意管理

EU の一般データ保護規則 (GDPR) やカリフォルニア州消費者プライバシー法 (CCPA)、あるいは会社のプライバシーポリシーなど、同意やプライバシーに関する義務の管理を支援するため、Salesforce CDP Mobile SDK にはイベントデータの収集を許可したり制限したりするための管理ソリューションが用意されています。

モバイルアプリケーションは、デバイスの所有者に対してデータの収集へのオプトインまたはオプトアウトの選択肢を表示し、選択に応じて Salesforce CDP Mobile SDK の consent プロパティを設定する必要があります。

同意の付与

Salesforce CDP Mobile SDK は、モバイルアプリケーションがデータ収集に対するユーザの同意を得るまでは、モバイルデバイスから Salesforce CDP アプリケーションにイベントを送信することができません。下記のように同意を付与することでアプリケーションをクイックスタートできます。

>

アプリケーションを最初に初期化するときに、データの収集に関する同意を付与するようにユーザにお願いします。Salesforce CDP Mobile SDK の state プロパティ (CdpSdk.shared.state)を見ると、consent プロパティはデフォルト値の opt_in になっています。

1CdpSdk.shared.consent = Consent.optIn

Consent パラメータ

Salesforce CDP Mobile SDK の設定パラメータを下表に示します。

Consent 値	デフォルト	説明
Consent.optIn	いいえ	Consent が optIn に設定されていると、設定されている Salesforce CDP エンドポイントにイベントが送信されて収集されます。
Consent.optOut	いいえ	Consent が optOut に設定されていると、Salesforce CDP Mobile SDK はモバイルアプリケーションによって作成されたイベントを無視します。この場合は、イベントがキューに登録されたりデバイスから送信されたりすることはありません。Consent が optOut に設定された時点でキューに登録されているイベントが存在する場合は、Salesforce CDP Mobile SDK はそれらのイベントをメモリから削除します。
Consent.pending	はい	Salesforce CDP Mobile SDK が新たに初期化された時点では、同意の初期状態は pending (保留中) になります。この状態では、イベントはローカルに収集されますが、CDP には転送されません。Consent が pending から optIn に変更された時点でキューに登録されているイベントが存在する場合は、Salesforce CDP Mobile SDK はそれらのイベントを CDP エンドポイントに送信します。

デバイスのユーザから同意情報が得られたら、Salesforce CDP Mobile SDK の consent プロパティを次のように設定します。

1// grant consent
2          CdpSdk.shared.consent = Consent.optIn
3          
4          // revoke consent
5          CdpSdk.shared.consent = Consent.optOut

ロケーションの追跡

Salesforce CDP Mobile SDK では、すべてのイベントでロケーションを追跡できます。この機能を有効化するには、Salesforce CDP Mobile SDK の共有インスタンスで setLocation メソッドを使用して、ロケーション座標と有効期限 (秒数) を指定します。

1// prepare the coordinates
2          let coordinates = Coordinates(latitude: 54.187738, longitude: 15.554440)
3          
4          // set the location coordinates and expiration time
5          CdpSdk.shared.setLocation(coordinates: coordinates, expiresIn: 60)

SDK でロケーション座標の有効期限が残っている間は、イベント属性の latitude と longitude というキー名のキー-値ペアに、ロケーション属性が自動的に付加されます。

有効期限が過ぎると、SDK ロケーション座標はクリアされ、イベントには付加されなくなります。座標の有効期限が過ぎる前にロケーションの付加を止めたい場合は、setLocation メソッドをコールして、座標値として nil を指定します。

注意: アプリケーション開発者として、ロケーションを追跡する許可をエンドユーザから得る必要があります。アプリケーション開発者は、ロケーションの追跡許可を求め、ロケーションを取得して、必要な精度範囲を保証する責任を負います。

イベントの追跡

Salesforce CDP Mobile SDK では、イベントを追跡することで、エンドユーザによるモバイルアプリケーションとのインタラクションに関する詳細なデータを収集できます。イベントは、イベントタイプとイベント属性 (省略可能) で構成されます。Salesforce CDP Mobile SDK では、現時点ではエンゲージメントとプロファイルの 2 つのイベントオブジェクトがサポートされています。

イベントの追跡

エンゲージメントイベントなど、異なるタイプのイベントを作成できます。イベントタイプを作成するには、イベントをインスタンス化して、eventType と属性のコレクション (省略可能) を渡します。

1let event = Event.engagement(eventType: "CartAbandonment", attributes: 
2          ["sku": "COFFEE-NTR-06", "tag price": 19.99])

イベントを Salesforce CDP アプリケーションに送信するには、CdpSdk 共有 インスタンスで track メソッドをコールします。

1CdpSdk.shared.track(event: event)

追跡するイベントを確認するには、Salesforce CDP Mobile SDK の state プロパティ (CdpSdk.shared.state) の eventManager セクションで queueSize を調べます。

これで Salesforce CDP Mobile SDK の設定が完了し、イベントを作成して、そのイベントを追跡するために Salesforce CDP アプリケーションに送信しました。

Salesforce CDP Mobile SDK 管理ソリューションの Consent は、pending、optIn、optOut という 3 つの値から構成される列挙型です。Consent は、SDK の初期化時に内部で pending に設定されます。SDK を使用するモバイルアプリケーションは、Consent を optIn または optOut に更新できますが、pending に戻すことはできません。

Salesforce CDP Mobile SDK による顧客データの収集に関する同意管理の詳細を下表に示します。

イベントパラメータ

パラメータ	型	説明
eventType	string	必須。予約されている値: AppFirstLaunch、AppLaunch、AppUpdate、ScreenView。イベントタイプを空白またはスペースのみにすることはできません。
attributes	dictionary	省略可能。イベント属性。いくつかの制限が適用されます。キー型: string 必須: はい予約されている値: userId、deviceId、eventId、sessionId、dateTime、eventType、category 値サポートされている型: string、int、float、double、bool、NSNull サポートされている型として認識されない値を指定すると、名前-値ペアが属性のコレクションから削除され、アクションはエラーとして記録されます。

予約されている値と一致する eventType を使用してイベントを作成するとエラーになります。予約されている値と一致する値を使用して属性ディクショナリにキーを追加すると、そのキー-値ペアは削除されます。キー-値ペアにサポートされていない型の値を指定した場合も、キー-値ペアは削除されます。例:

1// create engagement event
2          let event = Event.engagement(eventType: "CartAbandonment", attributes: ["sku": "COFFEE-NTR-06", "tag price": 19.99])
3          
4          // track engagement event
5          CdpSdk.shared.track(event: event)
6          
7          // create engagement event (no attributes)
8          let simpleEvent = Event.engagement(eventType: "SortPriceLowToHigh")
9          CdpSdk.shared.track(event: simpleEvent)
10          
11          // create profile event
12          let profileEvent = Event.profile(eventType: "UserUpdate", attributes: ["name": "John"])
13          
14          // track profile event
15          CdpSdk.shared.track(event: profileEvent)