การแมปข้อกำหนด ECAPI

คู่มือนี้ช่วยให้นักพัฒนาซอฟต์แวร์ที่ใช้ข้อกําหนด IAB Tech Lab Event และ Conversion API (ECAPI) แมปข้อมูลเหตุการณ์และ Conversion กับสคีมาการนําเข้าเหตุการณ์ Data Manager API

ภาพรวม

ECAPI เป็นมาตรฐานข้อมูลแบบโอเพนซอร์สที่ไม่ขึ้นกับแพลตฟอร์ม ซึ่งออกแบบมาเพื่อกําหนดโครงสร้างของเหตุการณ์และ Conversion ที่เกี่ยวข้องกับการตลาด

ตารางต่อไปนี้แสดงภาพรวมของวิธีที่แอตทริบิวต์และหลักการออกแบบที่สำคัญของ ECAPI เปรียบเทียบกับ Data Manager API

ECAPI Data Manager API
การกรองข้อมูลที่ซ้ำกันออก อิงตาม id (รหัสกิจกรรม) ขึ้นอยู่กับ transaction_id
การกำหนดเส้นทางเหตุการณ์ ปลายทางของข้อมูลจะระบุโดยฟิลด์ data_set_id ในเพย์โหลดของเหตุการณ์ ฟิลด์ destinations ของคำขอจะกำหนด ปลายทางสำหรับเหตุการณ์

นอกจากนี้ Data Manager API ยังรองรับการกำหนดเส้นทางเหตุการณ์ไปยังปลายทางหลายแห่งในคำขอเดียวด้วย

ดูข้อมูลเพิ่มเติมได้ในคู่มือปลายทาง
ฟิลด์ความเป็นส่วนตัวและความยินยอม สตริงความยินยอมของ Global Privacy Platform (GPP) Data Manager API ไม่ยอมรับหรือแยกวิเคราะห์สตริงความยินยอมของ Global Privacy Platform (GPP) ต้องตั้งค่าฟิลด์ความยินยอมในออบเจ็กต์ Consent

คุณตั้งค่าความยินยอมได้ทั้งในระดับคำขอ (ซึ่งใช้กับเหตุการณ์ทั้งหมดในคำขอ) หรือในระดับเหตุการณ์ (ซึ่งช่วยให้คุณระบุการตั้งค่าความยินยอมที่แตกต่างกันสำหรับเหตุการณ์แต่ละรายการได้)

การแมปฟิลด์โครงสร้าง

ตารางการแมปต่อไปนี้จะกำหนดวิธีที่ฟิลด์แต่ละรายการจากข้อกำหนด ECAPI แปลงเป็นฟิลด์ที่ Data Manager API ยอมรับ

การแมปออบเจ็กต์เหตุการณ์

ECAPI (event) Data Manager API (Event) หมายเหตุ
data_set_id
  • destinations[].product_destination_id (ระดับคำขอ)
  • destination_references (ระดับเหตุการณ์)
 กำหนดได้ที่ระดับต่อไปนี้
  • ระดับคำขอ (ต้องระบุ): ระบุรายการ destinations ใน IngestEventsRequest
  • ระดับเหตุการณ์: ใช้ฟิลด์ destination_references ในออบเจ็กต์ Event เพิ่มรายการเพื่อระบุว่าปลายทางใดจากdestinationsรายการควรได้รับเหตุการณ์

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีกำหนดDestination และระบุรหัสปลายทางของผลิตภัณฑ์ได้ที่ กำหนดค่าปลายทางและส่วนหัว
id transaction_id ค่านี้ใช้ในการขจัดเหตุการณ์ Conversion ที่ซ้ำกัน ดูข้อมูลเพิ่มเติม
timestamp event_timestamp ต้องระบุ ECAPI ใช้รูปแบบ Epoch ของ Unix (จำนวนเต็ม) สำหรับการประทับเวลา เมื่อแมปกับ Data Manager API ฟิลด์ event_timestamp ต้อง แปลงเป็นรูปแบบใดรูปแบบหนึ่งต่อไปนี้
  • หากใช้รูปแบบ JSON ให้ตั้งค่าเป็นรูปแบบ RFC 3339
  • หากใช้บัฟเฟอร์โปรโตคอล ให้ใช้ Timestamp และตั้งค่า ฟิลด์ seconds และ (ไม่บังคับ) ฟิลด์ nanoseconds

ดูรายละเอียดได้ที่รูปแบบการประทับเวลา
event_type / custom_event event_name ซึ่งอาจเป็นชื่อเหตุการณ์ที่แนะนํา (เช่น purchase) หรือชื่อเหตุการณ์ที่กําหนดเอง โปรดดูรายละเอียดในหัวข้อชื่อเหตุการณ์มาตรฐาน
user_data user_data แมปกับออบเจ็กต์ UserData ซึ่งยอมรับรายการออบเจ็กต์ UserIdentifier
value conversion_value แมปโดยตรงเป็น Double หรือ Float ที่แสดงมูลค่าทางการเงินของ Conversion
currency_code currency แมปกับรหัสสกุลเงิน 3 ตัวอักษรพิมพ์ใหญ่ (เช่น USD)
source event_source ตั้งค่าเป็นค่าจาก Enum EventSource
properties
  • cart_data
  • custom_variables
  • additional_event_parameters
 คุณเชื่อมโยงสินค้าที่ระดับธุรกรรมกับอาร์เรย์ cart_data.items ในออบเจ็กต์ CartData ได้ Data Manager API รองรับฟิลด์ Merchant Center ที่ไม่บังคับหลายรายการสำหรับผลิตภัณฑ์ ที่มีอยู่ในบัญชี Merchant Center

หากปลายทางเป็นการกระทำที่ถือเป็น Conversion ของ Google Ads คุณยังระบุ พารามิเตอร์ที่กำหนดเองเพิ่มเติมในช่อง custom_variables เป็นรายการออบเจ็กต์ CustomVariable ได้ด้วย

หากปลายทางเป็นสตรีมข้อมูล Google Analytics คุณจะรวมพารามิเตอร์เหตุการณ์เพิ่มเติม ในช่อง additional_event_parameters เป็นรายการออบเจ็กต์ AdditionalEventParameter ได้
ext ไม่มีเวอร์ชันเทียบเท่า

การแมปออบเจ็กต์ข้อมูลผู้ใช้

ใน Data Manager API ฟิลด์ user_data ในออบเจ็กต์ Event ยอมรับออบเจ็กต์ UserData ซึ่งคาดหวังว่าจะเป็นรายการออบเจ็กต์ UserIdentifier ซึ่งอาจมีตัวระบุผู้ใช้แต่ละราย เช่น อีเมล หมายเลขโทรศัพท์ หรือคอมโพเนนต์ที่อยู่

ECAPI (user_data) Data Manager API (Event) หมายเหตุ
customer_identifier user_id (Google Analytics) สําหรับเหตุการณ์ Google Analytics ฟิลด์ user_id จะแสดงถึง User-ID Data Manager API ไม่รองรับฟิลด์รหัสลูกค้าทั่วไปสำหรับปลายทางอื่นๆ
uids ไม่มีเวอร์ชันเทียบเท่า Data Manager API ไม่รองรับอาร์เรย์ uids ที่มีโครงสร้างซึ่งมีประเภทเอเจนต์และโดเมน
customer_segments user_properties แผนที่ไป UserProperties บน Event
email_address user_data.user_identifiers[].email_address ตั้งค่าเป็นอีเมลที่จัดรูปแบบและแฮชแล้ว นอกจากนี้ คุณยังเข้ารหัสอีเมลที่แฮชแล้วได้ด้วย
phone_numbers user_data.user_identifiers[].phone_number ตั้งค่าเป็นหมายเลขโทรศัพท์ที่จัดรูปแบบและแฮชแล้ว คุณยังเข้ารหัสหมายเลขโทรศัพท์ที่แฮชแล้วได้ด้วย
utcoffset ไม่มีเวอร์ชันเทียบเท่า หากใช้รูปแบบ JSON คุณจะระบุออฟเซ็ตเขตเวลาได้โดยตรงในสตริง RFC 3339 event_timestamp
หากใช้บัฟเฟอร์โปรโตคอล คุณจะใช้ฟังก์ชันยูทิลิตี เช่น Timestamps.parse(String) เพื่อจัดการการแปลงเขตเวลาเป็นวินาทีและนาโนได้
ดูรายละเอียดได้ที่รูปแบบการประทับเวลา
address user_data.user_identifiers[].address แมปกับออบเจ็กต์ AddressInfo ดูการแมปออบเจ็กต์ที่อยู่
gpp_string ไม่มีเวอร์ชันเทียบเท่า ต้องแมปความยินยอมกับออบเจ็กต์ Consent ระดับคำขอหรือระดับเหตุการณ์ ดูภาพรวมความเป็นส่วนตัวและความยินยอม
gpp_sid ไม่มีเวอร์ชันเทียบเท่า ต้องแมปความยินยอมกับออบเจ็กต์ Consent ระดับคำขอหรือระดับเหตุการณ์ ดูภาพรวมความเป็นส่วนตัวและความยินยอม
mmt_only ไม่มีเวอร์ชันเทียบเท่า
click_id ad_identifiers.gclid แมปรหัสคลิกของ Google (gclid) ดูรายละเอียดเพิ่มเติมได้ที่ AdIdentifiers
impression_id ad_identifiers.impression_id ดูรายละเอียดเพิ่มเติมได้ที่ AdIdentifiers
event_ip_address event_device_info.ip_address ดูฟิลด์ที่ใช้ได้ใน DeviceInfo
event_user_agent event_device_info.user_agent ดูฟิลด์ที่ใช้ได้ใน DeviceInfo
ifa ad_identifiers.mobile_device_id แมปกับตัวระบุบนมือถือสำหรับผู้ลงโฆษณา (IDFA ใน iOS, AdID ใน Android) ดูรายละเอียดเพิ่มเติมได้ที่ AdIdentifiers
landing_ip_address ad_identifiers.landing_page_device_info.ip_address ดูฟิลด์ที่ใช้ได้ใน DeviceInfo
landing_user_agent ad_identifiers.landing_page_device_info.user_agent ดูฟิลด์ที่ใช้ได้ใน DeviceInfo
age_range ไม่มีเวอร์ชันเทียบเท่า
gender ไม่มีเวอร์ชันเทียบเท่า
ext ไม่มีเวอร์ชันเทียบเท่า

การแมปออบเจ็กต์ที่อยู่

ECAPI (address) Data Manager API (AddressInfo) หมายเหตุ
first_name given_name แมปกับฟิลด์ given_name ใน AddressInfo ปฏิบัติตามหลักเกณฑ์การจัดรูปแบบและการแฮช นอกจากนี้ คุณยังเข้ารหัสแอตทริบิวต์ที่แฮชของที่อยู่ได้ด้วย
last_name family_name แมปกับฟิลด์ family_name ใน AddressInfo ปฏิบัติตามหลักเกณฑ์การจัดรูปแบบและการแฮช นอกจากนี้ คุณยังเข้ารหัสแอตทริบิวต์ที่แฮชของที่อยู่ได้ด้วย
street ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับใน Data Manager API
city ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับใน Data Manager API
state ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับใน Data Manager API
country_code region_code อย่าแฮช แมปกับฟิลด์ region_code ใน AddressInfo ปฏิบัติตามหลักเกณฑ์การจัดรูปแบบ
postal_code postal_code อย่าแฮช แมปกับฟิลด์ postal_code ใน AddressInfo ปฏิบัติตามหลักเกณฑ์การจัดรูปแบบ
address_type ไม่มีเวอร์ชันเทียบเท่า ไม่รองรับใน Data Manager API
ext ไม่มีเวอร์ชันเทียบเท่า

การแมปออบเจ็กต์รายการ

ECAPI (item) Data Manager API (Item) หมายเหตุ
id item_id ต้องระบุสําหรับเหตุการณ์ Google Analytics ตั้งค่าเป็นตัวระบุที่ไม่ซ้ํากันที่เป็นมาตรฐานสําหรับสินค้า
ไม่มีเวอร์ชันเทียบเท่า merchant_product_id ต้องระบุสําหรับ Conversion ของ Floodlight และ Conversion ของ Google Ads ที่มีข้อมูลรถเข็นช็อปปิ้ง ตั้งค่าเป็นรหัสผลิตภัณฑ์ภายในบัญชี Merchant Center
name additional_item_parameters แผนที่เป็น item_name ในรายการ additional_item_parameters
price unit_price
discount additional_item_parameters หรือ custom_variables แมปเป็น discount ใน additional_item_parameters (สําหรับ Google Analytics) หรือเป็นตัวแปรที่กําหนดเองใน custom_variables (สําหรับ Google Ads)
quantity quantity แปลงfloatค่าเป็นจำนวนเต็ม (int64)
brand additional_item_parameters แผนที่เป็น item_brand ในรายการ additional_item_parameters
affiliation additional_item_parameters แผนที่เป็น affiliation ในรายการ additional_item_parameters
category additional_item_parameters แผนที่เป็น item_category ในรายการ additional_item_parameters
cattax ไม่มีเวอร์ชันเทียบเท่า
item_coupon additional_item_parameters แผนที่เป็น coupon ในรายการ additional_item_parameters
item_list_id additional_item_parameters แผนที่เป็น item_list_id ในรายการ additional_item_parameters
item_list_name additional_item_parameters แผนที่เป็น item_list_name ในรายการ additional_item_parameters
item_item_variant additional_item_parameters แผนที่เป็น item_variant ในรายการ additional_item_parameters
item_location_id additional_item_parameters แผนที่ของ location_id ใน additional_item_parameters
ext ไม่มีเวอร์ชันเทียบเท่า

ชื่อเหตุการณ์มาตรฐาน

เหตุการณ์มาตรฐาน ECAPI สอดคล้องกับรูปแบบการตั้งชื่อของ Google Analytics เป็นอย่างมาก

เหตุการณ์มาตรฐาน ECAPI ส่วนใหญ่ (เช่น purchase, add_to_cart, begin_checkout, search และ refund) มีชื่อเหตุการณ์เดียวกันกับเหตุการณ์ที่ Google Analytics แนะนํา อย่างไรก็ตาม มีข้อยกเว้นบางกรณีที่ Google Analytics ใช้กาลปัจจุบันแทนกาลอดีต ดังนี้

  • viewed_item แมปกับ view_item
  • viewed_item_list แมปกับ view_item_list
  • viewed_cart แมปกับ view_cart

ตัวอย่างคำขอ

แท็บต่อไปนี้แสดงการเปรียบเทียบระหว่างเพย์โหลดเหตุการณ์ Conversion ของ ECAPI กับการแสดงเป็น Data Manager API ที่ถูกต้อง IngestEventsRequest

ECAPI

ต่อไปนี้คือตัวอย่างเพย์โหลด JSON ที่เป็นไปตามข้อกำหนด ECAPI

{
  "data_set_id": "123456789",
  "id": "ABC798654321",
  "timestamp": 1781035621,
  "event_type": "purchase",
  "value": 30.03,
  "currency_code": "USD",
  "source": "website",
  "user_data": {
    "customer_identifier": "123456789123456789",
    "customer_segments": ["gold_member"],
    "email_addresses": [
      "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
    ],
    "address": {
      "first_name": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
      "last_name": "db98d2607efffa28aff66975868bf54c075eca7157e35064dce08e20b85b1081",
      "country_code": "US",
      "postal_code": "94045"
    },
    "event_ip_address": "192.0.2.1",
    "event_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  },
  "properties": {
    "items": [
      {
        "id": "SKU_12345",
        "quantity": 3,
        "item_price": 10.01
      }
    ]
  }
}

Data Manager API

นี่คือตัวอย่าง IngestEventsRequest สำหรับ ข้อมูลเหตุการณ์ที่จัดรูปแบบ แฮช และเข้ารหัส ซึ่งใช้สำหรับปลายทาง Google Ads ตามที่ระบุโดยประเภทบัญชี GOOGLE_ADS ใน ปลายทาง

{
  "destinations": [
    {
      "operating_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "login_account": {
        "account_type": "GOOGLE_ADS",
        "account_id": "1234567890"
      },
      "product_destination_id": "123456789"
    }
  ],
  "encoding": "HEX",
  "events": [
    {
      "event_name": "purchase",
      "transaction_id": "ABC798654321",
      "event_timestamp": "2026-06-10T20:07:01Z",
      "event_source": "WEB",
      "user_properties": {
        "additional_user_properties":[
          {
            "property_name": "customer_segment",
            "value": "gold_member"
          }
        ]
      },
      "user_data": {
        "user_identifiers": [
          {
            "email_address": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
          },
          {
            "address": {
              "given_name": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
              "family_name": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
              "region_code": "US",
              "postal_code": "94045"
            }
          }
        ]
      },
      "event_device_info": {
        "ip_address": "192.0.2.1",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      },
      "conversion_value": 30.03,
      "currency": "USD",
      "cart_data": {
        "items": [
          {
            "item_id": "SKU_12345",
            "quantity": 3,
            "unit_price": 10.01
          }
        ]
      }
    }
  ]
}