Tealium Collect HTTP API — V3 早期アクセス | Tealium 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イベント、1秒あたり100回の呼び出しを送信できます。
1回の呼び出しにつき10イベント、1秒あたり10回の呼び出しを送信できます。
1回の呼び出しにつき100イベント、1秒あたり1回の呼び出しを送信できます。

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

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

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

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

非セキュアなTealium Collectエンドポイント	セキュアなグローバルTealium Collectエンドポイント	セキュアなリージョナルTealium Collectエンドポイント	HTTPメソッド	説明
`/event`	`/v3/collect/event`	`/v3/collect/regional/event`	GET POST	ブラウザベースでないリクエストのためのRESTfulエンドポイント。
`/integration/event/` `{account}/{profile}/` `{datasourceID}`	`/v3/collect/integration/` `event/accounts/` `{account}/profiles/` `{profile}/datasources/` `{datasourceID}`	`/v3/collect/regional/` `integration/event/accounts/` `{account}/profiles/{profile}/` `datasources/{datasourceID}`	POST	HTTP Advanced HTTP APIおよびCommunicationsデータソースが内部的に使用するエンドポイント。
`/bulk-event`	`/v3/collect/bulk-event`	`/v3/collect/regional/bulk-event`	POST	1つのリクエストで複数のイベント（最大10）を送信します。

訪問の識別子

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

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

匿名ID

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

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

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

匿名値

AudienceStream	EventStream
必須	N/A

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

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

既知の訪問サーバー間

AudienceStream	EventStream
必須	推奨

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

アカウント
プロファイル
訪問ID属性IDと値
訪問ID属性IDは、属性リストの属性名の隣にあるか、詳細を展開した中にあります。詳細については、About Attributesを参照してください。
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キーからベアラートークンを生成する方法については、Authenticationを参照してください。

必要なパラメータ

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

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

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

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

追加のイベント属性は、トラッキングのニーズに応じてカスタムパラメータとして送信されます。これらのパラメータも、Customer Data Hubでイベント属性として定義する必要があります。

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メソッドは、リクエストヘッダーをContent-Type: application/jsonに構成し、ペイロードを有効な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

`/bulk-event`の例

cURLリクエストの例

curl --location --request POST 'https://{host}/v3/collect/bulk-event' \
--header 'Authorization: Bearer eyJ0eXAi***' \
--header 'Content-Type: application/json' \
--data-raw '{
    "shared": {
      "tealium_account": "{account}",
      "tealium_profile": "{profile}",
      "tealium_environment": "prod",
      "tealium_datasource": "{datasource}",
      "tealium_visitor_id": "abc123_071222_1"
    },
    "events": [
      {
        "page_name": "test1",
        "tealium_event": "page_view"
      },
      {
        "page_name": "test2",
        "tealium_event": "page_view"
      }
    ]
}'

レスポンスの例

< HTTP/2 200
< date: Fri, 15 Jul 2022 00:07:37 GMT
< content-type: application/json
< content-length: 0
< x-amzn-requestid: 11f79456-cdb8-4ccc-8cc7-e8a54db79414
< x-region: us-east-1
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: 7277c009-f9f5-47a2-9fe6-61f05c98e6fd
< x-amz-apigw-id: VSBnlEqkIAMFbFA=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-01e68ac980b602444
< expires: Fri, 15 Jul 2022 00:07:37 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:07:37 GMT

`/integration/event`の例

cURLリクエストの例

curl --location --request POST 'https://{host}/v3/collect/integration/event/accounts/{account}/profiles/{profile}/datasources/{datasourceId}' --header 'Authorization: Bearer eyJ0***' --header 'Content-Type: application/json' --data-raw '{
  "tealium_event": "page_view",
  "tealium_datasource": "{datasourceId}",
  "page_type": "123",
  "outerObject": {
    "innerobject":"1234"
  },
  "page_name": "kek"
}'

レスポンスの例

< HTTP/2 204
< date: Fri, 15 Jul 2022 00:05:23 GMT
< x-amzn-requestid: e3b5bc65-8712-40a3-a87c-9d6bb8df68cf
< x-region: us-east-1
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: fadbdf55-dccb-4241-a9ce-81722fc2a8d9
< x-amz-apigw-id: VSBSnF9OIAMFxXA=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-058449c0632b25787
< expires: Fri, 15 Jul 2022 00:05:23 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:05:23 GMT

ステータスコード

以下の表は、TealiumのHTTPレスポンスステータスコードをまとめたものです：

ステータスコード	説明
`200 Status OK`	リクエストが成功しました
`400 Bad Request`	サーバーがリクエストを理解できません

400 Bad Requestステータスコードは、以下のいずれかが真である場合に発生します：

JSONキーにピリオドが含まれている、無効である、またはサイズが1MBを超えている
ファイルタイプパラメータにJSONまたはJavaScript以外の値が含まれている
account、profile、およびdatalayer_idの組み合わせが250文字を超えている、または制限された文字が含まれている
tealium_accountまたはtealium_profileが欠落している、またはタイプミスが含まれている
リクエストボディが空である

以下は、必要なtealium_accountまたはtealium_profileパラメータ値が欠落している場合の/v3/collect/eventへのGETリクエストに対する400 Bad Requestレスポンスの例で、X-Errorヘッダーに表示されます：

< HTTP/2 200
< date: Fri, 15 Jul 2022 00:03:05 GMT
< content-type: image/gif
< content-length: 43
< x-error: Missing required tealium_account or tealium_profile param value
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-region: us-west-2
< x-serverid: uconnect_i-0b80d0d9adfb124a2
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< vary: Origin
< pragma: no-cache
< expires: Fri, 15 Jul 2022 00:03:05 GMT
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-uuid: 1d0dd863-dc31-4eb2-b7a0-5b98e3b7fb5b

以下は、/v3/collect/bulk-eventへのPOSTリクエストに対する400 Bad Requestレスポンスの例です：

< HTTP/2 400
< date: Fri, 15 Jul 2022 00:01:16 GMT
< content-type: application/json
< content-length: 78
< x-amzn-requestid: 993d950d-cde4-4ee0-9f18-d3e41a3ed5ca
< x-amzn-remapped-content-length: 78
< x-region: us-east-1
< p3p: policyref="/w3c/p3p.xml", CP="NOI DSP COR NID CUR ADM DEV OUR BUS"
< x-amzn-remapped-connection: keep-alive
< x-uuid: 59afeed7-abe2-487c-bac1-a96903f4a449
< x-amz-apigw-id: VSAr9HOloAMFQkA=
< vary: Origin
< cache-control: no-transform,private,no-cache,no-store,max-age=0,s-maxage=0
< x-serverid: uconnect_i-02ccd81bf59828cde
< expires: Fri, 15 Jul 2022 00:01:16 GMT
< x-ulver: e07c919851780ad8793847fdb12df3611bcdbf78-SNAPSHOT
< pragma: no-cache
< x-amzn-remapped-date: Fri, 15 Jul 2022 00:01:16 GMT
<
* Connection #0 to host us-east-1-platform.tealiumapis.com left intact
{ "returnCode" : 1400 , "message" : "Request body must contain 'events' key."}

例

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アカウントマネージャーに連絡してください。

仕組み

地域と全球のエンドポイント

レート制限

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

訪問の識別子

匿名ID

匿名値

既知の訪問 サーバー間

ユーザー識別子

権限要件

認証

必要なパラメータ

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

GETメソッド

/eventの例

cURLリクエストの例

レスポンスの例

POSTメソッド

/eventの例

cURLリクエストの例

レスポンスの例

/bulk-eventの例

cURLリクエストの例

レスポンスの例

/integration/eventの例

cURLリクエストの例

レスポンスの例

ステータスコード

例

HTML

JavaScript

既知の訪問サーバー間

`/event`の例

`/event`の例

`/bulk-event`の例

`/integration/event`の例