Adobe Visitor Service Module | モバイル用の開始ガイド

Adobe Visitor Serviceモジュールは、AdobeのREST APIと直接連携して、訪問のExperience Cloud ID（ECID）を取得および維持します。ECIDは、Adobe TargetやAdobe AnalyticsなどのAdobeエコシステムの異なる部分で同じ訪問を識別し、一意の訪問を識別します。

AdobeのトラッキングSDKからTealium SDKに移行する場合、Adobe Visitor Serviceモジュールを使用してトラッキングペイロードでECIDを渡します。データレイヤーの新しいECIDは、Tealium EventStreamまたはTealium AudienceStreamのサーバーサイドのAdobeコネクタでマッピングされる場合があります。Adobe Visitor Serviceモジュールは、既存のECIDが存在する場合は再利用し、存在しない場合は新しいECIDを生成して、アプリ内の訪問の正確な数を確保することで、Tealium SDKへのシームレスな移行を提供します。

サポートされているプラットフォーム

次のプラットフォームは、Adobe Visitor Serviceモジュールをサポートしています：

ユースケース

サーバーサイドアナリティクスへの移行

Adobeの統合をサーバーサイドに移行し、Adobe Analyticsサーバーサイドを介してコネクタのmarketingCloudVisitorIDパラメータにECIDをマッピングし、複数のAdobe製品が連携して動作するために有効なECIDが必要です。 Tealium SDKは、EventStreamに任意のコールを送信する前にECIDをAdobeから要求し、ECIDはAdobe AnalyticsコネクタのmarketingCloudVisitorIDプロパティにマッピングされます。

Tealium iQタグ管理

Adobe Analyticsタグを使用する場合、Tealium iQタグ管理を使用することをお勧めします。これにより、ECIDがすぐに利用可能になり、保存に永続化され、非表示のWebビュー内のクッキーストアに依存しないようになります。

Adobe SDKからTealium SDKへの移行

Adobe SDKからTealiumモジュールへの移行はシームレスです。アプリが現在Adobe SDKに依存してECIDを管理している場合、Adobe SDKがTealium SDKと並行してアプリに存在するように移行期間を設けることをお勧めします。訪問に既存のAdobe ECIDがある場合は、config.adobeVisitorExistingEcidプロパティを介してTealiumモジュールに渡します。初期化時にプロパティが構成されている場合、既存のECIDが使用されます。プロパティが構成されていない場合、TealiumモジュールはAdobe APIから新しいECIDを取得します。

同じデバイス上の異なる訪問をトラッキングする

アプリ内で異なる訪問アカウントを検出した場合、ECIDをリセットして各訪問を別々にトラッキングするために、tealium.adobeVisitor?.resetVisitor()を呼び出します。これにより、現在のECIDがリセットされ、Adobe APIから自動的に新しいECIDが要求されます。

独自の訪問IDと認証状態を構成する

Visitor APIに独自の訪問IDを渡すためのいくつかの方法があります。これにより、IDサービスが匿名のECIDを既知のIDにマッチングできます。

既知の訪問IDを構成する

初期化時に訪問のIDと認証状態が既知の場合は、adobeVisitorDataProviderId構成プロパティを使用して、モジュールの開始時に訪問の既知のIDを構成します：

config.adobeVisitorDataProviderId = "01" // このタイプの訪問IDのデータプロバイダID
config.adobeVisitorAuthState = AdobeAuthState.AUTH_STATE_AUTHENTICATED
config.adobeVisitorCustomVisitorId = "customeremail@emailprovider.com"

config.adobeVisitorDataProviderId = "01" // このタイプの訪問IDのデータプロバイダID
config.adobeVisitorAuthState = .authenticated
config.adobeVisitorCustomVisitorId = "customeremail@emailprovider.com"

config.adobeVisitorDataProviderId = "01" // このタイプの訪問IDのデータプロバイダID
config.adobeVisitorAuthState = .authenticated
config.adobeVisitorCustomVisitorId = "customeremail@emailprovider.com"

config.adobeVisitorDataProviderId = "01" // このタイプの訪問IDのデータプロバイダID
config.adobeVisitorAuthState = .authenticated
config.adobeVisitorCustomVisitorId = "customeremail@emailprovider.com"

モジュールは、必要に応じて新しいIDを自動的に要求し、その後、TealiumConfigプロパティで指定された既知のIDとECIDをリンクするために追加のAPIコールを送信します。

訪問がログイン時にIDと認証状態を渡す必要がある場合は、次のメソッドを呼び出して、訪問の既知のIDを匿名のECIDにリンクします：

tealium.adobeVisitorApi?.linkEcidToKnownIdentifier("myidentifier", "123456", AdobeAuthState.AUTH_STATE_AUTHENTICATED, null)

tealium?.adobeVisitorApi?.linkECIDToKnownIdentifier("myidentifier", adobeDataProviderId: "123456", .unknown)

TealiumAdobeVisitor.linkEcidToKnownIdentifier("myidentifier", "123456", AuthState.unknown, value => {
                console.log("AdobeVisitor Data: " + JSON.stringify(value))
});

TealiumAdobeVisitor.linkEcidToKnownIdentifier("myidentifier", "123456", AuthState.unknown)

トラブルシューティング

次に、異なるAPIの失敗動作のリストを示します：

Adobe組織IDが見つからない場合
モジュールが有効になっているが、Adobe組織IDがTealiumConfigオブジェクトに渡されていない場合、モジュールは無効になり、トラッキングコールはAdobe ECIDなしで続行されます。
無効なAdobe組織ID
モジュールは、リトライ制限（デフォルト：5）までリトライを試みます。リトライ制限を超えた後、トラッキングコールはECIDなしで通常通り続行され、キューに入っているリクエストはすぐに送信されます。
Adobe APIがエラーまたは空の応答を返す場合
リクエストの送信中にエラーが返された場合、接続の失敗など、モジュールはリトライ制限（デフォルト：5）までリトライを試みます。リトライ制限を超えた後、トラッキングコールはECIDなしで通常通り続行され、キューに入っているリクエストはすぐに送信されます。
モジュールが上記の（2）または（3）に遭遇したが、訪問の以前のECIDがTealiumConfigオブジェクトで提供されている場合。最大リトライ後、モジュールは提供された訪問IDの値を使用し、リクエストをブロックしません。

データをTealiumに送信することが最優先である場合は、リトライ回数を0に構成して、失敗した場合にECIDを取得しないようにします。リトライ回数はconfig.adobeVisitorRetriesプロパティで制御されます。

データレイヤー

次の変数がデータレイヤーに追加されます：

変数	タイプ	説明
`adobe_ecid`	`String`	Adobe ECID。モジュールがAdobe Visitor APIからECIDを正常に取得した場合、すべてのトラッキングコールに存在します。
`adobe_error`	`String`	エラータイプの説明。例：`Org ID Not Set. ECID is not included from track requests`
`queue_reason`	`String`	訪問IDが利用可能になる前にモジュールによってイベントがキューに入れられます。

URLデコレーション

Adobeの製品は、Adobe Analytics JavaScriptタグなどのWebコンテキストでロードされる場合、自動的にExperience Cloud IDを使用します。このIDは、Webページのクエリ文字列でadobe_mcパラメータとして渡されます。adobe_mcパラメータには、パイプ文字（|）で区切られた複数の値が含まれます。

コンポーネント	説明	例
MCMID	Adobe Visitor Serviceから取得したExperience Cloud ID	1234
MCORGID	Adobe組織ID	12345@AdobeOrg
TS	タイムスタンプ（秒単位）	1655826247

結果のURLは次のとおりです：

https://tealium.com/?adobe_mc=MCMID=1234|MCORGID=12345@AdobeOrg|TS=1655826247

adobe_mcパラメータはURLエンコードされています。

Adobe Visitor Serviceモジュールには、この機能をサポートするための2つのメソッドが用意されています。

タグ管理モジュール

adobe_mcパラメータは、タグ管理モジュールのTealium Webビューで使用されるURLに自動的に追加されます。

カスタムWebビュー

アプリがコンテンツを表示するためにWebビューを使用する場合、Adobe ECIDをそのWebビューで利用可能にする必要があります。これにより、WebビューでロードされるすべてのAdobe製品がユーザーのECIDを知ることができます。これにより、ユーザーがネイティブアプリとWebビューの両方で異なるユーザーとして表示されることが防止されます。

Adobe Visitor Serviceモジュールには、WebビューのURLにクエリ文字列パラメータを追加するためのメソッドが用意されています。これにより、Adobe AnalyticsがExperience Cloud IDサービスのJavaScriptタグの代わりにモジュールによって生成されたECIDを使用するようになります。例に示すように、URLをdecorateURLメソッドに渡し、返されたURLをアプリ内でWebビューをロードするときに使用します。

このメソッドは、既にURLに存在するクエリパラメータを保持します

adobeVisitorModule?.decorateUrl(
            URL(url),
            object : UrlDecoratorHandler {
                override fun onDecorateUrl(url: URL) {
                  // Resulting URL = https://tealium.com/?myparam=abc&myparam2=bcd&adobe_mc=MCMID%3D1234%7CMCORGID%3D12345%40AdobeOrg%7CTS%3D1655826247
                  // Only for demonstration purposes; launch your app's webview with the resulting URL
                    myApp.launchWebview(url)
                }
            }
        )

let url = URL(string: "https://tealium.com/?myparam=abc&myparam2=bcd")!
tealium.adobeVisitorApi?.decorateURL(url) { url in
    // Resulting URL = https://tealium.com/?myparam=abc&myparam2=bcd&adobe_mc=MCMID%3D1234%7CMCORGID%3D12345%40AdobeOrg%7CTS%3D1655826247
    // Only for demonstration purposes; launch your app's webview with the resulting URL
    myApp.launchWebview(url)
}

TealiumAdobeVisitor.decorateUrl("https://tealium.com", value => {
    // Resulting URL = https://tealium.com/?myparam=abc&myparam2=bcd&adobe_mc=MCMID%3D1234%7CMCORGID%3D12345%40AdobeOrg%7CTS%3D1655826247
    // Only for demonstration purposes; launch your app's webview with the resulting URL
    launchUrl(value);
});

// Resulting URL = https://tealium.com/?myparam=abc&myparam2=bcd&adobe_mc=MCMID%3D1234%7CMCORGID%3D12345%40AdobeOrg%7CTS%3D1655826247
// Only for demonstration purposes; launch your app's webview with the resulting URL
TealiumAdobeVisitor.decorateUrl("https://tealium.com").then(
                    (value) =>
                        launchUrl(value));

アプリがAngularなどの非標準のURLスキームを使用してWebビューをロードする場合、Adobe Visitor APIのクエリパラメータを取得し、URLに手動で追加する必要があります。これらのメソッドは、URLエンコードされていないパラメータ名と値を返すため、値をURLに追加する前に値をエンコードする必要があります。

adobeVisitorApi?.getUrlParameters(
    object : GetUrlParametersHandler {
        override fun onRetrieveParameters(params: Map<String, String>?) {
            params?.let {
                params.forEach {
                    Log.d("ADB Visitor","Retrieved URL Parameters:${it.key} = ${it.value}")
                }
            }
        }
    }
)

tealium.adobeVisitorApi.adobeVisitorApi?.getURLParameters { params in
            guard let params = params else {
                completion(nil)
                return
            }
            // Result: params.name = adobe_mc
            //         params.value = MCMID=1234|MCORGID=12345@AdobeOrg|TS=1655826247
            // Only for demonstration purposes; call some method in your app that decorates the URL and then launches your webview
            print("Retrieved URL Parameters:\(params.name) = \(params.value)")
}

TealiumAdobeVisitor.getUrlParameters(value => {
    if (value === null || value === undefined) {
        console.log("Adobe Visitor was null");
        return;
    } else {
        for (var key of Object.keys(value)) {
            // Result: key = adobe_mc
            //         value = MCMID=1234|MCORGID=12345@AdobeOrg|TS=1655826247
            // Only for demonstration purposes; call some method in your app that decorates the URL and then launches your webview
            console.log("Retrieved URL Parameters: ", key + "=" + value[key]);
            break;
        }
    }
});

TealiumAdobeVisitor.getUrlParameters().then(
                            (value) =>
                            value?.forEach((key, value) {
                                // Result: key = adobe_mc
                                //         value = MCMID=1234|MCORGID=12345@AdobeOrg|TS=1655826247
                                // Only for demonstration purposes; call some method in your app that decorates the URL and then launches your webview
                                print("Retrieved URL Parameters: $key = $value");
                            })
                    )