Tealium API v3 - Visitor Privacy API（旧称：Visitor Lookup API）

このAPIを使用すると、特定の訪問者に関する既知のデータを取得したり、訪問者レコードを削除したり、削除リクエストのステータスを確認したりすることができます。

この記事では、Tealium v3 APIの使用方法について説明します。以前のVisitor Privacy v2 APIも引き続き利用できますが、将来的には非推奨となります。

動作原理

訪問者の検索は、アカウントからのVisitor ID属性に基づいて行われます。

制限と使用目的

Visitor Privacy APIは、GDPRやCCPAなどの規制要件を満たすために設計されており、高いボリュームの使用には適していません。このAPIへの接続は、常に1つ（1）のみ開いていることを推奨します。1日あたりのAPI呼び出し回数が1000回を超えると予想される場合は、アカウントマネージャーに連絡してください。

レート制限

Visitor Privacy APIのデフォルトのレート制限は、1秒あたり50リクエストです。

認証

ベアラートークンは、すべてのAPI呼び出しの認証に使用され、APIキーではありません。APIキーは認証呼び出しでのみ使用されます。ベアラートークンに加えて、認証応答には、後続のサーバーサイドAPI呼び出しで使用する必要がある、リージョン固有のホスト名も含まれます。

ベアラートークンをAPIキーから生成する方法については、Tealium API V3 Getting Startedガイドを参照してください。

訪問者フィールド

訪問者は、以下のフィールドを含むJSONオブジェクトとして返されます。

オブジェクト名	タイプ	説明
`live`	ブール値	訪問者が現在ライブセッション中である場合は`true`に設定されます。
`visitor`	オブジェクト	属性データタイプごとにサブオブジェクトを持つ訪問者オブジェクト：訪問者ID：`secondary_ids : { }` 数値/数値の配列： `"metrics" : { }` `"metric_lists" : { }` 文字列/文字列の配列/文字列のセット： `"properties" : { }` `"property_lists" : { }` `"property_sets" : { }` `"audiences" : { }` ブール値/ブール値の配列： `"flags" : { }` `"flag_lists" : { }` 日付：`"dates" : { }` バッジ：`"badges" : { }` 集計：`"metric_sets" : { }`

応答の例

{
    "live": false,
    "visitor": {
        "metrics": {
            "初回訪問からの経過週数": 0.14,
            "累計参照訪問数": 11,
            "累計訪問回数": 12,
            "平均訪問時間（分）": 0.36,
            "累計イベント数": 35,
            "サイトでの総滞在時間（分）": 4.27,
            "直接訪問数": 1
        },
        "dates": {
            "最終訪問": 1521217490000,
            "last_visit_start_ts": 1521217490000,
            "初回訪問": 1521134626000
        },
        "properties": {
            "利用したブラウザの累計バージョン（お気に入り）": "Chrome",
            "利用したブラウザの累計タイプ（お気に入り）": "Chrome",
            "プロファイル": "main",
            "利用したデバイスの累計（お気に入り）": "Mac desktop",
            "利用したプラットフォームの累計（お気に入り）": "browser",
            "最後のイベントURL": "http://www.tealium.com/",
            "アカウント": "tealium",
            "利用したオペレーティングシステムの累計（お気に入り）": "Mac OS X"
        },
        "flags": {
            "再訪問者": true
        },
        "badges": ["Unbadged"],
        "metric_sets": {
            "利用したオペレーティングシステムの累計": {
                "Mac OS X": 12
            },
            "利用したデバイスの累計": {
                "Mac desktop": 12
            },
            "利用したブラウザの累計バージョン": {
                "Chrome": 12
            },
            "利用したブラウザの累計タイプ": {
                "Chrome": 12
            },
            "利用したプラットフォームの累計": {
                "browser": 12
            }
        }
    }
}

訪問者の取得

次のGETコマンドを使用して、訪問者レコードを取得します。

GET /v3/privacy/visitor/accounts/{account}/profiles/{profile}?attributeId={attributeId}&attributeValue={attributeValue}&prettyName={prettyName}

このコマンドでは、次のパラメータを使用します。

attributeId
- アカウントからのVisitor ID属性を表す数値ID。
attributeValue
- 検索する値。
- 特殊文字を含む値はURLエンコードする必要があります。
prettyName
- 応答で属性キーが表示される方法を示すブール値：
  - True - 属性は「Lifetime Order Value」などのユーザーフレンドリーな名前で表示されます。
  - False - 属性は「28471」などの数値IDで表示されます。

この呼び出しでは、認証APIで返されたリージョン固有のホストを使用する必要があります。詳細については、Getting Started > Region-Specific Hostを参照してください。

必要な権限

サーバーサイドのリーダー、エディター、またはパブリッシャー

cURLリクエストの例

curl -H 'Authorization: Bearer {token}' \
 -G \
'https://us-east-1-platform.tealiumapis.com/v3/privacy/visitor/accounts/my_account/profiles/main' \
 --data-urlencode 'attributeId=86' \
 --data-urlencode 'attributeValue=user@example.com' \
 --data 'prettyName=true'

応答の例

応答のフォーマットについては、例の訪問者オブジェクトを参照してください。

エラーメッセージ

このタスクの潜在的なエラーメッセージは次のとおりです。

エラーメッセージ	説明
400	`{ "message": "You are missing an attribute Id or Attribute Value"}`
401	`{ "message": "Unauthorized"}`
404	`Visitor not found in system { "transactionId": {transactionId} }`
429	`{ "message": "Too many requests"}`
500	`{ "message": "Internal Server Error"}`

訪問者の削除

1つ以上の訪問者レコードを削除する前に、次の点に注意してください。

訪問者レコードの削除リクエストは、訪問者IDの値に関連するすべてのデータの削除をもたらします。これには、ステッチされた訪問者レコードも含まれます。
削除リクエストは処理のためにキューに入れられ、1〜4日かかる場合があります。
訪問者が別の訪問者に置き換えられた場合、または別の訪問者によって置き換えられた場合、ステッチされたすべての訪問者が削除されます。
DELETEコマンドのパラメータは、URLエンコードされたフォームフィールドとして渡す必要があります。クエリ文字列パラメータとしてではありません。

次のDELETEコマンドを使用して、訪問者レコードを削除します。

DELETE /v3/visitor/privacy/accounts/{account}/profiles/{profile}
  attributeID={value}
  attributeValue={value}

このコマンドでは、次のパラメータを使用します。

attributeId
アカウントからのVisitor ID属性を表す数値ID。
attributeValue
検索する値。

必要な権限

サーバーサイドのパブリッシャー

cURLリクエストの例

curl -H 'Authorization: Bearer {token}' \
-X DELETE \
'https://us-east1-platform.tealiumapis.com/v3/privacy/visitor/accounts/my_account/profiles/main' \
--data-urlencode "attributeId=86"
--data-urlencode "attributeValue=user@example.com"

応答の例

削除リクエストへの応答には、transaction_idとステータスが含まれます。transaction_idは、前のリクエストのステータスを確認するためにGETトランザクション呼び出しで使用されます。次のステータス文字列が可能です：PENDING、SUCCESS、またはFAILED。

成功した応答では、202 Acceptedメッセージが表示され、transactionIdの値が返されます。同じaccount、profile、attributeId、attributeValueを持つリクエストが既にPENDINGのトランザクションステータスで存在する場合、既存のトランザクションIDが返されます。

{
"transactionId" : "{transactionId1}"
}

エラーメッセージ

このタスクの潜在的なエラーメッセージは次のとおりです。

エラーメッセージ	説明
400	`{ "message": "You are missing an attribute Id or Attribute Value"}`
401	`{ "message": "Unauthorized"}`
404	`Visitor not found in system { "transactionId": {transactionId} }`
429	`{ "message": "Too many requests"}`

トランザクションの取得

トランザクションとは、DELETE訪問者リクエストを指します。DELETE訪問者リクエストは後で処理されるため、transaction_idはそのリクエストの一意のレコードであり、処理ステータスを確認する際に使用されるIDです。

次のGETコマンドを使用して、トランザクションのステータスを確認します。

GET /v3/privacy/visitor/accounts/{account}/profiles/{profile}/transactions/{transaction_id}

必要な権限

サーバーサイドのリーダー、エディター、またはパブリッシャー

cURLリクエストの例

APIキーからベアラートークンを生成する方法については、Tealium API V3 Getting Startedガイドを参照してください。ベアラートークンはAPI呼び出しで使用されます。

curl -H 'Authorization: Bearer {token}' \
https://platform.tealiumapis.com/v3/privacy/visitor/accounts/my_account/profiles/main/transactions/0123456789

応答の例

応答には、キー/値のペアを1つ持つオブジェクトが含まれます。キーはtransaction_idであり、値は次のステータス文字列のいずれかです：PENDING、SUCCESS、またはFAILED。

{
  "0123456789" : "SUCCESS"
}

エラーメッセージ

このタスクの潜在的なエラーメッセージは次のとおりです。

エラーメッセージ	説明
401	`{ "message": "Unauthorized"}`
404	`Visitor not found in system { "transactionId": {transactionId} }`
429	`{ "message": "Too many requests"}`

Visitor ID属性の取得

次のGETコマンドを使用して、アカウントで利用可能なVisitor ID属性のリストを取得します。

GET /v3/privacy/visitor/accounts/{account}/profiles/{profile}/ids

必要な権限

サーバーサイドのリーダー、エディター、またはパブリッシャー

cURLリクエストの例

curl -H 'Authorization: Bearer {token}' \
https://platform.tealiumapis.com/v3/privacy/visitor/accounts/my_account/profiles/main/ids

応答の例

このコマンドの応答は、数値IDとVisitor ID属性の名前を表すキー/値のペアのオブジェクトです。

{
  "43" : "Email Address",
  "57" : "Tax ID Number"
}

エラーメッセージ

このタスクの潜在的なエラーメッセージは次のとおりです。

エラーメッセージ	説明
401	`{ "message": "Unauthorized"}`
404	`{ "message" : "No Visitor ids were found for the account and profile"}`
429	`{ "message": "Too many requests"}`
500	`{ "message" : "Internal Server Error"}`