HTTP API - 高度な着信ウェブフックのセットアップガイド | 受信Webhooks

動作原理

HTTP API - 高度なデータソースは、条件付きで着信リクエストボディを解析できる汎用のデータソースです。このデータソースは、複雑なオブジェクトのフラット化とバッチイベントのサポートを備えたHTTPエンドポイントを提供し、単一のHTTPコールでリアルタイムのイベントデータを収集することができます。このエンドポイントは柔軟であり、ウェブページのトラッキングピクセルとして、またはカスタムアプリケーションのJSON APIとして実装することができます。

このデータソースはHTTP APIデータソースと似ていますが、複雑なJSONオブジェクトとバッチ処理のサポートが追加されています。HTTP POSTを使用して送信されるイベントは、次のようにフラット化されます。

イベント属性名は、オブジェクトのプロパティを小文字に変換し、アンダースコア（"_"）で結合して作成されます。例：
元のデータ："alpha" : { "beta" : true }
フラット化されたイベント属性："alpha_beta" : true
配列内の数値、ブール値、および文字列は保持されます。
配列内のオブジェクトと配列は文字列化されます。

このデータソースタイプは、リアルタイムでデータを送信する必要があり、標準のTealium Collectエンドポイントの形式要件を満たすためにリクエストを変更できない場合に使用します。

バッチイベント

HTTP API - 高度なデータソースのHTTPエンドポイントは、単一のリクエスト内で複数のイベントをサポートしています。これらのイベントはバッチイベントと呼ばれます。バッチイベントでは、すべてのレコードのステータスに基づいて1つのレスポンスコードが返されます。単一のレコード/イベントが失敗した場合、そのイベントのみが失敗し、残りのイベントは処理されます。

レート制限

HTTP API - 高度なデータソースは、最大100イベント/秒のレート制限をサポートしています。

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

1回の呼び出しあたり1つのイベントを送信する場合、1秒あたり100回の呼び出しを送信できます。
1回の呼び出しあたり10個のイベントを送信する場合、1秒あたり10回の呼び出しを送信できます。
1回の呼び出しあたり100個のイベントを送信する場合、1秒あたり1回の呼び出しを送信できます。

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

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

必要条件

Tealium EventStreamまたはTealium AudienceStream

リクエスト形式

HTTP API - 高度なデータソースはPOSTメソッドをサポートしています。GETメソッドのリクエストの場合は、HTTP APIを使用してください。

APIエンドポイント

HTTP API - 高度なデータソースにアクセスするためには、次のエンドポイントを使用します：

https://collect.tealiumiq.com/integration/event/ACCOUNT/PROFILE/DATA_SOURCE_KEY?tealium_trace_id=TRACEID

tealium_trace_idクエリパラメータの使用はオプションであり、トレースツールのデバッグ時にのみ使用する必要があります。トレースの使用方法の詳細については、トレースについてを参照してください。

データソースキーを見つけるには、データソースダッシュボードに移動し、使用するデータソースをクリックして、データソースキーフィールドからキーをコピーします。

訪問識別子

AudienceStreamは、訪問を追跡するために次の組み合わせを使用します：

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

匿名ID

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

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

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

匿名の値

AudienceStream	EventStream
必須	N/A

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

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

既知の訪問サーバーからサーバーへ

AudienceStream	EventStream
必須	推奨

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

アカウント
プロファイル
訪問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属性を豊かにします。

データソースの追加

このセクションでは、HTTP API - 高度なデータソースを追加し、ウェブフックを作成する方法について説明します。

続行する前に、HTTP API - 高度なデータソースを追加し、プロファイルを公開する必要があります。

関連：データソースの追加方法

レスポンスコード

レスポンスコード	説明
HTTP 204	リクエストが成功しました
HTTP 400	不正なJSONリクエスト
HTTP 404

例

HTTP API - 高度な着信ウェブフックは、Javascript、bashスクリプト、またはcurlを使用してHTTP API Advancedコールを送信する場合に便利です。

ペイロードとしてのJSON配列

ペイロード全体としてJSON配列を渡す場合、複数のイベント（バッチ処理）として扱われます。

[
  {
    "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
    "my_string": "12345a",
    "Detail": {
      "Name": "Event A"
    }
  },
  {
    "tealium_visitor_id": "e0f7e1bb7c5efa1afeba05fc4ddf93aa86caee629",
    "my_string": "12345b",
    "Detail": {
      "Name": "Event B"
    }
  }
]

このペイロードは、次のように複数のイベントに変換されます：

// 最初のイベント
  {
    "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
    "my_string": "12345a",
    "detail_name":  "Event A"
  }

  // 2番目のイベント
  {
    "tealium_visitor_id": "e0f7e1bb7c5efa1afeba05fc4ddf93aa86caee629",
    "my_string": "12345b",
    "detail_name":  "Event B"
  }

ペイロード内のキー値としてのJSON配列

ペイロード内のキーの値として配列を渡す場合、配列は文字列の配列にフラット化されます。

例えば、次の配列：

{
   "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
   "my_string": "12345a",
   "detail_name": "Event A",
   "events": [
       {
           "id": "1",
           "name": "Event A"
       },
       {
           "id": "2",
           "name": "Event B"
       },
       {
           "id": "3",
           "name": "Event C"
       }
   ]
}

次のような文字列の配列にフラット化されます：

{
   "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
   "my_string": "12345a",
   "detail_name": "Event A",
       "events": [
        "{\"id\":\"1\",\"name\":\"Event A\"}",
        "{\"id\":\"2\",\"name\":\"Event B\"}",
        "{\"id\":\"3\",\"name\":\"Event C\"}"
    ]
}

複雑なビジネスケースや要件の場合は、HTTP API - 高度なエンドポイントの代わりまたは追加として、Tealiumイベント変換関数を使用することを検討してください。

複雑なオブジェクト

このセクションでは、複雑なオブジェクトの入力コードとフラット化された出力の例を提供します。

フラット化前

次の購入イベントの例は、クライアントサイドのeコマースイベントが複雑なオブジェクトでフラット化される方法を示しています。

{
   "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
   "my_string": "12345a",
   "detail_name": "Event A",
  "ecommerce": {
    "event": "purchase",
    "purchase": {
      "customer": {
        "id": "8237572",
        "email": "john.smith@example.com",
        "city": "San Diego",
        "state": "CA",
        "country": "United States"
      },
      "order": {
        "id": "ORD123456",
        "store": "mobile web",
        "subtotal": "2524.00",
        "total": "2549.00"
      },
      "product": {
          "name": ["Product One", "Product Two"],
          "id": ["PROD123","PROD456"],
          "price": ["12.00","1250.00"],
          "brand": ["Ralph Lauren","Lucky"],
          "category": ["Apparel","Apparel"],
          "quantity": [1,1]
        }
    }
  }
}

フラット化後

フラット化後、購入イベントは次のようになります：

{
   "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
   "my_string": "12345a",
   "detail_name": "Event A",
    "ecommerce_event": "purchase",
    "ecommerce_purchase_customer_id": "8237572",
    "ecommerce_purchase_customer_email": "john.smith@example.com",
    "ecommerce_purchase_customer_city": "San Diego",
    "ecommerce_purchase_customer_state": "CA",
    "ecommerce_purchase_customer_country": "United States",
    "ecommerce_purchase_order_id": "ORD123456",
    "ecommerce_purchase_order_store": "mobile web",
    "ecommerce_purchase_order_subtotal": "2524.00",
    "ecommerce_purchase_order_total": "2549.00",
    "ecommerce_purchase_product_name": ["Product One", "Product Two"],
    "ecommerce_purchase_product_id": ["PROD123","PROD456"],
    "ecommerce_purchase_product_price": ["12.00","1250.00"],
    "ecommerce_purchase_product_brand": ["Ralph Lauren","Lucky"],
    "ecommerce_purchase_product_category": ["Apparel","Apparel"],
    "ecommerce_purchase_product_quantity": [1,1]
}

制限事項

ペイロードの最大サイズは3.5 MBです。
リクエストごとに処理できるレコード数は、ペイロードのサイズに制限されます。