Tealium Collect HTTP API — V3 アーリーアクセス

Tealium Collect HTTP APIの使用を開始するには、Tealiumアカウントマネージャーに連絡してください。

動作原理

Tealium Collectは、GETおよびPOSTメソッドをサポートするHTTPエンドポイントです。

https://collect.tealiumiq.com/event

セッションは、訪問スコープ属性プロパティに基づいて決定されます。

地域およびグローバルエンドポイント

Tealium Collectはクロスリージョナルエンドポイントであり、任意のプロファイルが任意の地域でTealium Collectにイベントデータを送信できます。APIはプロファイルの正しい地域を認識し、その地域のESPにデータを送信します。

Tealium Collectは以下の2つのホストをサポートしています：

• collect.tealiumiq.com
  最も近いTealium Collectサーバー（最も遅延が少ないもの）にイベントを送信します。
• collect-<region>.tealiumiq.com
  プロファイルの地域にあるTealium Collectサーバーにイベントを送信します。

セキュアなTealium Collectエンドポイントの場合、グローバルエンドポイントは内部的にcollect.tealiumiq.comに、地域エンドポイントはcollect-<region>.tealiumiq.comにマッピングされます。

レート制限

Tealium Collect HTTP API — V3は、最大100イベント/秒のレート制限をサポートしています。

例えば、以下のように送信する場合：

• 1回の呼び出しにつき1イベントの場合、100回/秒を送信できます。
• 1回の呼び出しにつき10イベントの場合、10回/秒を送信できます。
• 1回の呼び出しにつき100イベントの場合、1回/秒を送信できます。

レート制限を超えると、TealiumはHTTP 429レスポンスを送信し、リクエストが多すぎることを示します。

ビジネスニーズが高いイベント制限を要求する場合は、Tealiumアカウントマネージャーに連絡してください。

エンドポイントマッピング

以下の表は、セキュアでないTealium CollectエンドポイントをセキュアなTealium Collectエンドポイントにマッピングしたものです。

訪問識別子

AudienceStreamは、以下の組み合わせを使用して訪問を追跡します：

• 匿名ID：通常、訪問を匿名で追跡するために使用されるID（例：デバイスまたはブラウザから）。既知の訪問の場合は、ユーザー識別子に基づいて値を使用します。
• ユーザー識別子：訪問が既知の場合に送信されます。特定のデバイスではなく、ユーザーを識別する値に基づいています。

匿名ID

匿名IDは、AudienceStreamがイベントと訪問の間で訪問を関連付けるために使用する匿名識別子です。この値がGUIDであり、訪問に対して一貫性があることを確認してください。

匿名IDのキー名はtealium_visitor_idです。

ビジネスケースに応じて、匿名値または既知のユーザー識別子に基づいた値を使用してください。

匿名値

Tealium iQタグ管理を使用してAPI呼び出しをサーバー間で行い、匿名訪問プロファイルをエンリッチする場合、tealium_visitor_idの値はutag_main_v_idクッキーの値と一致する必要があります。utag.jsの組み込み変数についての詳細は、JavaScript (Web) > データレイヤーを参照してください。

Adobe LaunchまたはGoogle Tag Managerを使用している場合、値はTEALクッキーのv部分と一致する必要があります。

既知の訪問サーバー間

訪問ID属性（例：email_address）の値が存在する場合に既知の訪問のデータを送信するときは、以下のものを連結して含めます：

• アカウント

• プロファイル

• 訪問ID属性IDおよび値

  訪問ID属性IDは、属性リストの属性名の隣または詳細情報が展開された中で見つけることができます。詳細については、属性についてを参照してください。

• tealium_visitor_idパラメータ内の値

例えば、以下の値を持っている場合：

• アカウント名：my-account
• プロファイル：main
• 訪問ID属性ID：7688
• 顧客番号の値：45653454

これらの値を次のように連結します：

"tealium_visitor_id":"__my-account_main__7688_45653454__"

tealium_visitor_idが正しくフォーマットされていることを進める前に確認してください。フォーマットが正しくないパラメータはAudienceStreamでエラーを引き起こし、適切に追跡されない可能性があります。

例 JSON：

{
    "tealium_account"    : "my-account",
    "tealium_profile"    : "main",
    "tealium_event"      : "user_login",
    "email_address"      : "user@example.com",
    "tealium_visitor_id" : "__my-account_main__7688_45653454__"
}

匿名訪問を使用する場合でも、既知の訪問を使用する場合でも、API呼び出しが一貫したtealium_visitor_idを含んでいない場合、各イベントは新しい訪問を生成し、訪問のスティッチングが不可能になります。

ユーザー識別子

AudienceStreamを使用する場合、トラッキングコールに既知のユーザー識別子を渡すことができます。例えば、email_addressやlogin_idです。

EventStreamを使用していて、ベンダーコネクタにIDを提供する必要がある場合も、ユーザー識別子が必要です。

AudienceStreamでは、これらのユーザー識別子は訪問ID属性をエンリッチするために使用されます。

権限要件

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

認証

すべてのAPI呼び出しを認証するために使用されるのはAPIキーではなくベアラートークンです。APIキーは認証呼び出しでのみ使用されます。ベアラートークンに加えて、認証応答には後続のサーバーサイドAPI呼び出しで使用する必要がある地域固有のホスト名が含まれています。

APIキーからベアラートークンを生成する方法については、認証を参照してください。

必要なパラメータ

Tealium Collectは、各リクエストで以下の標準パラメータをサポートしています：

• tealium_account - Tealiumアカウントの名前。
• tealium_profile - Tealiumプロファイルの名前。デフォルトはmainです。
• tealium_datasource - (オプション) データソースキー。詳細については、データソースについてを参照してください。
• tealium_event - (推奨) トラッキング目的のイベント名。
• tealium_visitor_id - (AudienceStreamに必要) イベントに関連する訪問の匿名化された一意の識別子（訪問識別子セクションを参照）。
• tealium_trace_id - (オプション) Traceで使用するため。

リクエストの形式は使用するHTTPメソッドによって異なります。以下の例ではプレースホルダー値が次の形式で表されています：{VALUE}。

カスタムイベントパラメータ

追加のイベント属性は、トラッキングニーズに応じてカスタムパラメータとして送信されます。これらのパラメータをアカウントのイベント属性として定義してください。

GETメソッド

GETメソッドは、エンドポイントのクエリ文字列にキーと値のペアを使用してデータを渡します。この方法は、HTMLベースの実装と互換性を持たせるために1x1の透明なGIFを返します。

/eventの例

cURLリクエストの例

curl -i -X GET 'https://{host}/v3/collect/event?tealium_account={account}&tealium_profile={profile}&tealium_event=user_login&email_address=user@example.com'
--header 'Authorization: Bearer eyJ0**'

レスポンスの例

< HTTP/2 200
< date: Fri, 15 Jul 2022 00:08:50 GMT
< content-type: image/gif
< content-length: 43
< x-amzn-requestid: 03bb378a-2619-4440-9d5a-c1e7d0e8d2ae
< x-amzn-remapped-content-length: 43
< x-region: us-east-1
< x-acc: {account}:{profile}:2:event
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: f513ef4b-5870-4fa4-b908-38c5e12bf3e4
< x-amz-apigw-id: VSBy2Fu6oAMFezA=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-0182b50695a2297ec
< expires: Fri, 15 Jul 2022 00:08:50 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< x-tid: f513ef4b58704fa4b90838c5e12bf3e4
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:08:50 GMT

POSTメソッド

POSTメソッドはJSONペイロードをサポートしており、リクエストヘッダーにはContent-Type: application/jsonを構成し、ペイロードは有効なJSON文字列としてフォーマットする必要があります。

/eventの例

cURLリクエストの例

curl --location --request POST 'https://{host}/v3/collect/event' --header 'Authorization: Bearer eyJ0eXA***' --header 'Content-Type: application/json' --data-raw '{
"tealium_account": "{account}",
"tealium_datasource": "w12c8s",
"tealium_profile": "{profile}",
"tealium_event": "page_view",
"page_type": "123",
"page_name": "testName"
}'

レスポンスの例

< HTTP/2 200
< date: Fri, 15 Jul 2022 00:08:03 GMT
< content-type: application/json
< content-length: 0
< x-amzn-requestid: ad5c154f-3053-4991-9a60-45b35745eba7
< x-region: us-east-1
< x-acc: {account}:main:2:event
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: 1d6b9c12-16c3-44a9-95c9-78afeabaf8e0
< x-amz-apigw-id: VSBroH24oAMFXpQ=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-0a95ad51791af67ac
< expires: Fri, 15 Jul 2022 00:08:03 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< x-tid: abc123_071422_1
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:08:03 GMT

HTML

Tealium Collectは、HTML内の<img>タグで参照できます。ブラウザのキャッシュのため、ランダムに生成された値を含むキャッシュバスターという追加パラメータを含めることが重要です。

キャッシュバスターの例：

var cb=Math.random()*100000000000;

この変数はTealium Collectピクセルのクエリストリングに追加されます：

<img height="1" width="1" style="display:none" src="//collect.tealiumiq.com/event?tealium_account={ACCOUNT}&tealium_profile={PROFILE}&tealium_event=user_login&email_address=user@example.com&cb=' + cb + '"/>

JavaScript

Tealium Collectはクロスドメインリクエストをサポートしているため、あなたのウェブサイトから私たちのドメインにPOSTを送信できます。レスポンスヘッダーには以下が含まれます：Access-Control-Allow-Origin: [http://your_domain.com](http://your_domain.com/)

var event = {
   "tealium_account" : "{ACCOUNT}",
   "tealium_profile" : "{PROFILE}",
   "tealium_event"   : "user_login",
   "email_address"   : "user@example.com"
};

var xhr = new XMLHttpRequest();
xhr.open("POST", "https://collect.tealiumiq.com/event");
xhr.send(JSON.stringify(event));

レスポンスヘッダーには以下が含まれます：

Access-Control-Allow-Origin: [<http://your_domain.com>](<http://your_domain.com>)

Tealium Collect HTTP APIの使用を開始するには、Tealiumアカウントマネージャーに連絡してください。