Data Cloud 開発者ガイド
jData Cloud Mobile SDK
前提条件
Data Cloud Mobile SDK を使用するには、Salesforce データソースコネクタを作成して、エンドポイントを自動生成します。Data Cloud アプリケーションにログインして、[Web サイトおよびモバイルアプリケーション] 画面の左側のパネルに移動します。ユーザインターフェースでアプリケーションコネクタを作成することで、データソースを設定します。詳細は、「Data Cloud 実装ガイド」を参照してください。
Web データコネクタから取得した appSourceId と生成されたエンドポイントを使用して Data Cloud Mobile SDK を初期化します。
SDK のインストール
Data Cloud Mobile SDK をモバイルアプリケーションに追加するには、CocoaPods を使用するか、またはソースコードにコールを組み込みます。
CocoaPods
1use_frameworks!
2
3 target '<Your Target>' do
4 pod 'SALESFORCE-CDP-SDK-IOS-SDK', '~> 1.0'
5 end手動でのインストール
手動でインストールするには、自分で書いたコードですべての連動関係を管理する必要があります。複数のライブラリが連動関係を共有していて、それぞれが異なるバージョンを指定できる場合には、すべての連動関係を満足する最適なライブラリバージョンをモバイルアプリケーション開発者の責任で指定する必要があります。
SDK の設定
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 の設定手順
-
Data Cloud Mobile SDK を設定して Data Cloud の (UUID 形式の) アプリケーション ID と Salesforce Tenant Specific Endpoint (TSE) を指定します。
1let config = CdpConfigBuilder(appId: {REPLACE WITH APP ID}, endpoint: 2 {REPLACE WITH ENDPOINT}).build() -
Data Cloud Mobile SDK を初期化します。 設定しなかったプロパティではデフォルト値が使用されます。
1_ = CdpSdk.configure(config) 2 Congratulations! The SDK is now configured and ready to use. You can verify that by inspecting the state of the 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 }
設定パラメータ
Data Cloud Mobile SDK の設定パラメータを下表に示します。
| 設定 | 型 | 説明 |
|---|---|---|
| appId | string | 必須。appId 設定は、モバイルアプリケーションを Data Cloud プラットフォームに対して一意に識別し、有効な UUID (ユニバーサル一意識別子) の形式で指定する必要があります。CdpSdkBuilder に対して無効な appID を指定すると、致命的なエラーが発生します。 |
| endpoint | string | 必須。endpoint 設定は、作成および追跡されるイベントを Data Cloud Mobile SDK Web サービスがどこに送信すべきかを指定します。エンドポイントは、次の形式の有効な Data Cloud URL である必要があります。 |
| trackScreens | boolean | 省略可能。デフォルトは false です。trackScreens を有効化すると、モバイルアプリケーションの ScreenEntry イベントを自動的に追跡します。イベントは、イベントタイプが「ScreenView」、属性が「screenname」のエンゲージメントイベントとして収集されます。 |
| trackLifecycle | boolean | 省略可能。デフォルトは false です。trackLifecycle を有効化すると、アプリケーションライフサイクルイベントの AppForegrounded と AppVersionChanged を自動的に追跡します。イベントはエンゲージメントイベントして収集されます。AppVersionChanged イベントのイベントタイプは「AppUpdate」、属性は「previousVersion」です。AppForegrounded イベントのイベントタイプは「AppFirstLaunch」または「AppLaunch」で、属性はありません。 |
| sessionTimeoutInSeconds | int | 省略可能。デフォルトは 600 です。sessionTimeoutInSeconds 設定は、モバイルアプリケーションがバックグラウンドの状態で何秒経過したら現在のセッションが期限切れになるかを表します。セッション管理は次のように行われます。まず、エンドユーザがモバイルアプリケーションを起動すると、Data Cloud Mobile SDK は新しいセッションを開始します。このセッションは、アプリケーションがフォアグラウンドの状態のときに維持されます。ユーザがモバイルアプリケーションをバックグラウンドに送ると、SDK はタイマーを起動して、現在のセッションが期限切れになるまでの時間を計測します。セッションが期限切れになる前にユーザがモバイルアプリケーションをフォアグラウンドに戻すと、タイマーがクリアされてセッションが継続します。そうでなければセッションが終了します。 |
1let sdk = CdpSdk.configure(config)1CdpSdk.shared1// Initially
2 <Cdp.CdpSdk: 0x600001854780>
3 // After reconfiguring
4 <Cdp.CdpSdk: 0x600001865da0>ログレベル
ログは任意ですが重要な SDK の機能です。モバイルアプリケーション開発者は、Data Cloud 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 プロパティ
1CdpSdk.shared.state1{
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)、あるいは会社のプライバシーポリシーなど、同意やプライバシーに関する義務の管理を支援するため、Data Cloud Mobile SDK にはイベントデータの収集を許可したり制限したりするための管理ソリューションが用意されています。
モバイルアプリケーションは、デバイスの所有者に対してデータの収集へのオプトインまたはオプトアウトの選択肢を表示し、選択に応じて Data Cloud Mobile SDK の consent プロパティを設定する必要があります。
同意の付与
Data Cloud Mobile SDK は、モバイルアプリケーションがデータ収集に対するユーザの同意を得るまでは、モバイルデバイスから Data Cloud アプリケーションにイベントを送信することができません。下記のように同意を付与することでアプリケーションをクイックスタートできます。
>1CdpSdk.shared.consent = Consent.optInConsent パラメータ
Data Cloud Mobile SDK の設定パラメータを下表に示します。
| Consent 値 | デフォルト | 説明 |
|---|---|---|
| Consent.optIn | いいえ | Consent が optIn に設定されていると、設定されている Data Cloud エンドポイントにイベントが送信されて収集されます。 |
| Consent.optOut | いいえ | Consent が optOut に設定されていると、Data Cloud Mobile SDK はモバイルアプリケーションによって作成されたイベントを無視します。この場合は、イベントがキューに登録されたりデバイスから送信されたりすることはありません。Consent が optOut に設定された時点でキューに登録されているイベントが存在する場合は、Data Cloud Mobile SDK はそれらのイベントをメモリから削除します。 |
| Consent.pending | はい | Data Cloud Mobile SDK が新たに初期化された時点では、同意の初期状態は pending (保留中) になります。この状態では、イベントはローカルに収集されますが、Data Cloud への転送は制限されます。Consent が pending から optIn に変更された時点でキューに登録されているイベントが存在する場合は、Data Cloud Mobile SDK はそれらのイベントを CDP エンドポイントに送信します。 |
1// grant consent
2 CdpSdk.shared.consent = Consent.optIn
3
4 // revoke consent
5 CdpSdk.shared.consent = Consent.optOutロケーションの追跡
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 を指定します。
注意: アプリケーション開発者として、ロケーションを追跡する許可をエンドユーザから得る必要があります。アプリケーション開発者は、ロケーションの追跡許可を求め、ロケーションを取得して、必要な精度範囲を保証する責任を負います。
イベントの追跡
Data Cloud Mobile SDK では、イベントを追跡することで、エンドユーザによるモバイルアプリケーションとのインタラクションに関する詳細なデータを収集できます。イベントは、イベントタイプとイベント属性 (省略可能) で構成されます。Data Cloud Mobile SDK では、現時点ではエンゲージメントとプロファイルの 2 つのイベントオブジェクトがサポートされています。
イベントの追跡
1let event = Event.engagement(eventType: "CartAbandonment", attributes:
2 ["sku": "COFFEE-NTR-06", "tag price": 19.99])1CdpSdk.shared.track(event: event)追跡するイベントを確認するには、Data Cloud Mobile SDK の state プロパティ (CdpSdk.shared.state) の eventManager セクションで queueSize を調べます。
これで Data Cloud Mobile SDK の設定と初期化が完了し、イベントを作成して、そのイベントを追跡のために Data Cloud アプリケーションに送信しました。
Data Cloud Mobile SDK 管理ソリューションの Consent は、pending、optIn、optOut という 3 つの値から構成される列挙型です。Consent は、SDK の初期化時に内部で pending に設定されます。SDK を使用するモバイルアプリケーションは、Consent を optIn または optOut に更新できますが、pending に戻すことはできません。
Data Cloud Mobile SDK による顧客データの収集に関する同意管理の詳細を下表に示します。
イベントパラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
| eventType | string | 必須。予約されている値: AppFirstLaunch、AppLaunch、AppUpdate、ScreenView。イベントタイプを空白またはスペースのみにすることはできません。 |
| attributes | dictionary | 省略可能。イベント属性。いくつかの制限が適用されます。
|
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)