ส่งกิจกรรม

คุณสามารถดูการเริ่มต้นอย่างรวดเร็วนี้เพื่อทำความคุ้นเคยกับการส่งข้อมูลเหตุการณ์

ใช้ Data Manager API สำหรับสถานการณ์ต่อไปนี้

ส่ง Conversion ของแท็ก Google Ads หรือเหตุการณ์สําคัญของ Google Analytics เป็น แหล่งข้อมูลเพิ่มเติมสําหรับ Conversion ของแท็ก เพื่อเพิ่มสัญญาณการโต้ตอบกับโฆษณา และเสริมความแข็งแกร่งให้กับข้อมูลและประสิทธิภาพโดยรวม

ฟีเจอร์นี้ใช้ได้กับบัญชีที่อยู่ในรายการที่อนุญาตเท่านั้น กรอกแบบฟอร์มหากสนใจเพิ่มบัญชี Google Ads หรือพร็อพเพอร์ตี้ Google Analytics

หมายเหตุ: ข้อมูลจากแหล่งข้อมูลเพิ่มเติมที่คุณเชื่อมต่อจะไม่ถูกส่งต่อไปยัง การเสนอราคา Conversion ในระยะทดลอง 14 วัน ซึ่งไม่มีผลกับแหล่งข้อมูลของแท็ก Google ที่มีอยู่แล้ว
ส่งข้อมูลเหตุการณ์สําหรับ Conversion ออฟไลน์ของ Google Ads หรือ Conversion ที่ปรับปรุงแล้วสําหรับโอกาสในการขาย

เลือกเวอร์ชันของคู่มือที่ต้องการดู

ในการเริ่มต้นอย่างรวดเร็วนี้ คุณจะได้ทำตามขั้นตอนต่อไปนี้

เตรียม Destination เพื่อรับข้อมูลเหตุการณ์
เตรียมข้อมูลเหตุการณ์ที่จะส่ง
สร้างคำขอ IngestionService สำหรับ เหตุการณ์
ส่งคำขอด้วย Google APIs Explorer
ทำความเข้าใจการตอบกลับที่สำเร็จและไม่สำเร็จ

เตรียมปลายทาง

ก่อนที่จะส่งข้อมูลได้ คุณต้องเตรียมDestinationอย่างน้อย 1 รายการสำหรับข้อมูล นี่คือDestinationตัวอย่างที่คุณใช้ได้

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

ฟิลด์ของ Destination มีดังนี้ ดูรายละเอียดและตัวอย่างเพิ่มเติมเกี่ยวกับปลายทางสำหรับสถานการณ์ต่างๆ ได้ที่กำหนดค่า ปลายทาง

operatingAccount

บัญชีที่รับเหตุการณ์

สําหรับเหตุการณ์ที่ส่งเป็นแหล่งข้อมูลเพิ่มเติม บัญชีที่ดําเนินการอาจเป็นบัญชี Google Ads หรือพร็อพเพอร์ตี้ Google Analytics ก็ได้

หาก accountType เป็น GOOGLE_ANALYTICS_PROPERTY ข้อมูลเข้าสู่ระบบของคำขอ ต้องเป็นของผู้ใช้ Google Analytics ที่มีบทบาทผู้แก้ไขหรือผู้ดูแลระบบสำหรับพร็อพเพอร์ตี้

สําหรับ Conversion ออฟไลน์และ Conversion ที่ปรับปรุงแล้วสําหรับโอกาสในการขาย บัญชีปฏิบัติการ ต้องเป็นบัญชี Google Ads

loginAccount: บัญชีที่บัญชี Google สำหรับข้อมูลเข้าสู่ระบบเป็นผู้ใช้

productDestinationId

รหัสของเอนทิตีใน operatingAccount ที่รับเหตุการณ์

สําหรับเหตุการณ์ที่ส่งเป็นแหล่งข้อมูลเพิ่มเติม productDestinationId ต้องเป็นอย่างใดอย่างหนึ่งต่อไปนี้

รหัสของ Conversion ของ Google Ads ที่มี type ตั้งค่าเป็น WEBPAGE ใน UI ของ Google Ads แหล่งที่มาของ Conversion สำหรับ การกระทําที่ถือเป็น Conversion WEBPAGE คือ เว็บไซต์
รหัสการวัดของ สตรีมเว็บ Google Analytics คุณจะส่งเหตุการณ์เป็นแหล่งข้อมูลเพิ่มเติมไปยังสตรีมแอป iOS หรือแอป Android ของ Google Analytics ไม่ได้

สําหรับ Conversion ออฟไลน์หรือ Conversion ที่ปรับปรุงแล้วสําหรับโอกาสในการขาย productDestinationId ต้องเป็นรหัสของการกระทำที่ถือเป็น Conversion ของ Google Ads ที่มี type ตั้งค่าเป็น UPLOAD_CLICKS ใน UI ของ Google Ads แหล่งที่มาของ Conversion สําหรับการกระทําที่ถือเป็น Conversion UPLOAD_CLICKS คือ เว็บไซต์ (นําเข้าจากการคลิก)

ตัวอย่างในคู่มือนี้แสดงวิธีสร้างคำขอที่ส่งทุกเหตุการณ์ไปยังปลายทางเดียวกัน หากต้องการส่งเหตุการณ์ไปยังปลายทางหลายแห่งในคําขอเดียวกัน โปรดดูส่งเหตุการณ์ไปยังปลายทางหลายแห่ง

เตรียมข้อมูลเหตุการณ์

พิจารณาข้อมูลเหตุการณ์ต่อไปนี้ แต่ละตารางจะสอดคล้องกับเหตุการณ์ Conversion 1 รายการ เหตุการณ์ Conversion แต่ละรายการจะมีแสตมป์เวลาของเหตุการณ์ การกระทำที่ถือเป็น Conversion และมูลค่า Conversion

เหตุการณ์แต่ละรายการอาจมีตัวระบุโฆษณา เช่น gclid หรือตัวระบุผู้ใช้ เช่น อีเมล หมายเลขโทรศัพท์ และข้อมูลที่อยู่ นอกจากนี้ กิจกรรมยังอาจมีสิ่งต่อไปนี้ด้วย

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

ข้อมูลเหตุการณ์มีดังนี้

เหตุการณ์ 1

เหตุการณ์ #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
สินค้าในรถเข็น
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

เหตุการณ์ 2

กิจกรรม #2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
สินค้าในรถเข็น
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

จัดรูปแบบข้อมูล

จัดรูปแบบฟิลด์ตามที่ระบุไว้ในคำแนะนำ การจัดรูปแบบ ข้อมูลเหตุการณ์หลังการจัดรูปแบบมีดังนี้

เหตุการณ์ 1

เหตุการณ์ #1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
สินค้าในรถเข็น
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

เหตุการณ์ 2

กิจกรรม #2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
สินค้าในรถเข็น
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

แฮชและเข้ารหัสข้อมูล

นอกจากนี้ ที่อยู่อีเมล ชื่อจริง และนามสกุลที่จัดรูปแบบแล้วต้อง ได้รับการแฮชโดยใช้อัลกอริทึม SHA-256 และเข้ารหัสโดยใช้การเข้ารหัสฐานสิบหกหรือ Base64 ต่อไปนี้คือข้อมูลเหตุการณ์หลังจากจัดรูปแบบ แฮช และเข้ารหัส โดยใช้การเข้ารหัสฐานสิบหก

เหตุการณ์ 1

เหตุการณ์ #1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
สินค้าในรถเข็น
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

เหตุการณ์ 2

กิจกรรม #2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
สินค้าในรถเข็น
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

แปลงข้อมูลเป็นออบเจ็กต์ `Event`

แปลงข้อมูลที่จัดรูปแบบและแฮชของแต่ละเหตุการณ์เป็น Event กรอกข้อมูลในช่องต่อไปนี้ตามที่ระบุ

ตั้งค่า eventTimestamp เป็นเวลาที่เกิดเหตุการณ์

เหตุการณ์สําหรับ Google Analytics ต้องมี eventTimestamp ภายใน 72 ชั่วโมงที่ผ่านมา

ตั้งค่าช่องที่ต้องกรอกสำหรับกรณีการใช้งาน

กรณีการใช้งาน	รหัสระบุ	`transactionId`	`eventSource`
Conversion ออฟไลน์หรือ Conversion ที่ปรับปรุงแล้วสำหรับโอกาสในการขาย	ต้องระบุ ตั้งค่าอย่างน้อย 1 รายการต่อไปนี้ `adIdentifiers` โดยตั้งค่า `gclid`, `gbraid` หรือ `wbraid` อย่างน้อย 1 รายการ แอตทริบิวต์เซสชัน `userData`	ไม่บังคับ	ต้องระบุ ตั้งค่าเป็นค่า enum ค่าใดค่าหนึ่งสำหรับ `EventSource`
เหตุการณ์ที่ส่งเป็นแหล่งข้อมูลเพิ่มเติมไปยังปลายทาง Google Ads	ต้องระบุ ตั้งค่าอย่างน้อย 1 รายการต่อไปนี้ `adIdentifiers` โดยตั้งค่า `gclid`, `gbraid` หรือ `wbraid` อย่างน้อย 1 รายการ `userData`	จำเป็น	ไม่บังคับ หากตั้งค่าไว้ ต้องเป็น `WEB`
เหตุการณ์ที่ส่งเป็นแหล่งข้อมูลเพิ่มเติมไปยังปลายทาง Google Analytics	ต้องระบุ ตั้งค่าอย่างน้อย 1 รายการต่อไปนี้ `clientId` `adIdentifiers` โดยตั้งค่า `gclid` `userData`	จำเป็น	ไม่บังคับ หากตั้งค่าไว้ ต้องเป็น `WEB`

ป้อนข้อมูลในช่องอื่นๆ ที่คุณมีค่าสำหรับเหตุการณ์ โปรดดูรายการช่องทั้งหมดที่พร้อมใช้งานในเอกสารอ้างอิงของ Event

หมายเหตุ: Google Ads และ Google Analytics ไม่รองรับการจับคู่ที่อยู่ IP ของผู้ใช้ปลายทาง ในเขตเศรษฐกิจยุโรป (EEA), สหราชอาณาจักร (UK) หรือสวิตเซอร์แลนด์ (CH) เพิ่มตรรกะเพื่อยกเว้นการแชร์ที่อยู่ IP จากผู้ใช้จากภูมิภาคเหล่านี้ตามเงื่อนไข และตรวจสอบว่าคุณได้ให้ข้อมูลที่ชัดเจนและครบถ้วนแก่ผู้ใช้เกี่ยวกับข้อมูลที่คุณรวบรวมในเว็บไซต์ แอป และพร็อพเพอร์ตี้อื่นๆ พร้อมทั้งได้รับความยินยอมในกรณีที่กฎหมายหรือนโยบายที่เกี่ยวข้องของ Google กำหนด ดูรายละเอียดเพิ่มเติมได้ที่หน้าเกี่ยวกับการนำเข้า Conversion ออฟไลน์

เพิ่มแอตทริบิวต์เซสชัน

หากคุณส่ง Conversion ออฟไลน์หรือ Conversion ที่ปรับปรุงแล้วสําหรับโอกาสในการขาย ให้เพิ่มแอตทริบิวต์เซสชันเมื่อตัวระบุโฆษณาอื่นๆ เช่น GCLID หรือ WBRAID ไม่พร้อมใช้งาน นอกจากนี้ คุณยังรวมแอตทริบิวต์เซสชันไว้ใน ตัวระบุโฆษณาอื่นๆ ได้ด้วย

แอตทริบิวต์เซสชันให้บริบทและสัญญาณเพิ่มเติมเกี่ยวกับการโต้ตอบของผู้ใช้กับเว็บไซต์ ซึ่งช่วยเพิ่มความแม่นยำในการวัด Conversion, การรายงาน และการเสนอราคา

ใน Data Manager API คุณสามารถใช้ 2 วิธีต่อไปนี้เพื่อส่งแอตทริบิวต์เซสชัน

แนะนํา: ตั้งค่าฟิลด์ sessionAttributes ของ adIdentifiers เป็นสตริงแอตทริบิวต์เซสชันที่เข้ารหัส Base64 ทําตามวิธีการในวิธีบันทึก session_attributes เพื่อแก้ไขหน้าการส่งแบบฟอร์ม เพื่อบันทึกสตริงที่เข้ารหัส
หากใช้ JavaScript ไม่ได้ ให้บันทึกฟิลด์แอตทริบิวต์เซสชันแต่ละรายการ และเพิ่มแต่ละรายการลงในรายการ experimentalFields เป็น ExperimentalField แยกกัน
- gad_campaignid
- session_start_time_usec
- gad_source
- landing_page_url
- landing_page_referrer
หากมีค่าสำหรับแอตทริบิวต์เซสชัน landing_page_user_agent ให้ส่งค่าในฟิลด์ userAgent ของ adIdentifiers.landingPageDeviceInfo

แนวทางปฏิบัติแนะนำเมื่อส่งคู่คีย์-ค่าแต่ละคู่มีดังนี้
- ส่ง gad_campaignid และ session_start_time_usec อย่างสม่ำเสมอ ฟิลด์เหล่านี้มีความสำคัญอย่างยิ่งต่อการระบุแหล่งที่มาที่ถูกต้อง
- อย่าระบุค่า landing_page_url ที่ไม่ถูกต้องหรือบางส่วน เช่น สตริงตัวยึดตำแหน่ง เส้นทางแอปพลิเคชันภายใน หรือ URL ที่ไม่สมบูรณ์ ละเว้น landing_page_url หากคุณไม่มี URL ที่ถูกต้องและครบถ้วน
ต่อไปนี้คือส่วนหนึ่งของเหตุการณ์ตัวอย่างที่มีรายการใน experimentalFields สำหรับ gad_campaignid และ session_start_time_usec รวมถึง User Agent ในช่อง landingPageDeviceInfo
```
{
  ...,
  "experimentalFields": [
    {
      "field": "gad_campaignid",
      "value": "21288051566"
    },
    {
      "field": "session_start_time_usec",
      "value": "1767711548052000"
    }
  ],
  "adIdentifiers": {
    "landingPageDeviceInfo": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
    }
  }
}
```

เพิ่มข้อมูล Google Analytics

หากปลายทางของเหตุการณ์ที่ส่งเป็นแหล่งข้อมูลเพิ่มเติมมีพร็อพเพอร์ตี้ Google Analytics ให้ป้อนข้อมูลในช่องต่อไปนี้ตามที่ระบุ

eventName

ต้องระบุ ชื่อเหตุการณ์ Google Analytics

transactionId

ต้องระบุ ตัวระบุที่ไม่ซ้ำกันสำหรับเหตุการณ์

ตัวระบุอย่างน้อย 1 รายการ

ต้องตั้งค่าในช่องต่อไปนี้อย่างน้อย 1 ช่อง

clientId: ตัวระบุที่ไม่ซ้ำกันสำหรับอินสแตนซ์ผู้ใช้ของเว็บไคลเอ็นต์ ดูส่งเหตุการณ์ไปยัง Measurement Protocol
adIdentifiers.gclid: Google Click ID
userData: ตัวระบุสำหรับผู้ใช้ เช่น อีเมล หมายเลขโทรศัพท์ หรือข้อมูลที่อยู่

destinationReferences

ต้องระบุหากรายการ destinations ระดับคำขอมี Google Analytics Destination มากกว่า 1 รายการ เพิ่มรายการไปยัง destinationReferences เพื่อระบุ ปลายทาง Google Analytics ที่ควรรับเหตุการณ์ ดูข้อมูลเพิ่มเติมเกี่ยวกับ การอ้างอิงปลายทางได้ที่หัวข้อส่งเหตุการณ์ไปยัง ปลายทางหลายแห่ง

หากไม่ได้ตั้งค่า destinationReferences หรือมีหลายรายการที่อ้างอิงถึง ปลายทาง Google Analytics API ของ Data Manager จะปฏิเสธเหตุการณ์โดยมีข้อผิดพลาด MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT

userId

ไม่บังคับ User-ID สำหรับผู้ใช้

additionalEventParameters

ไม่บังคับ แต่แนะนำ สร้างรายการนี้ด้วยพารามิเตอร์เหตุการณ์ Google Analytics ที่ไม่ได้บันทึกไว้ในช่อง Event อื่นๆ พารามิเตอร์ อาจรวมพารามิเตอร์เพิ่มเติมที่แนะนําจากpurchase เหตุการณ์ หรือพารามิเตอร์อื่นๆ ที่คุณต้องการบันทึก ใช้ชื่อพารามิเตอร์ Google Analytics สําหรับ parameterName ของ EventParameter

เช่น หากคุณมีภาษีที่เชื่อมโยงกับธุรกรรม ให้เพิ่มรายการลงใน additionalEventParameters โดยตั้งค่า parameterName เป็น tax และตั้งค่า value เป็นค่าภาษี

เราไม่แนะนําให้เพิ่มรายการสําหรับพารามิเตอร์เหตุการณ์ transactionId, currency หรือ value ของ Google Analytics แต่ให้ระบุ transactionId, currency และ conversionValue ของ Event แทน ซึ่งจะมีลำดับความสำคัญเหนือกว่า รายการใดๆ ใน additionalEventParameters

เพิ่มข้อมูลรถเข็นช็อปปิ้งสําหรับเหตุการณ์การซื้อ

สร้างช่อง cartData ของ Event ด้วยข้อมูลเกี่ยวกับสินค้าที่ซื้อ สําหรับสินค้าแต่ละรายการที่ซื้อ ให้เพิ่มออบเจ็กต์ Item ลงในรายการ items ของ CartData และป้อนข้อมูลในช่องต่อไปนี้ตามที่ระบุ

itemId

ต้องระบุ ตัวระบุที่ไม่ซ้ำกันสำหรับสินค้า

unitPrice

ต้องระบุ ราคาต่อหน่วยไม่รวมภาษี ค่าจัดส่ง และส่วนลดระดับเหตุการณ์ (ระดับธุรกรรม)

หากสินค้ามีส่วนลดระดับสินค้า ให้ใช้ราคาต่อหน่วยที่ลดแล้ว เช่น หากสินค้ามีราคาต่อหน่วยเป็น 27.67 และส่วนลดต่อหน่วยเป็น 6.66 ให้ตั้งค่า unitPrice เป็น 21.01

quantity

ต้องระบุ จํานวนหน่วยที่ซื้อสําหรับสินค้ารายการนี้

additionalItemParameters

สร้างรายการนี้ด้วยพารามิเตอร์ระดับสินค้าที่ไม่ได้บันทึกไว้ในฟิลด์ Item อื่นๆ ใช้ชื่อพารามิเตอร์รายการ Google Analytics สําหรับ parameterName ของ ItemParameter

เช่น หากคุณมีแบรนด์และหมวดหมู่ของสินค้า ให้เพิ่มรายการลงใน additionalItemParameters ของสินค้าโดยตั้งค่า parameterName เป็น item_brand และตั้งค่า value เป็นชื่อแบรนด์ และเพิ่มอีกรายการโดยตั้งค่า parameterName เป็น item_category และตั้งค่า value เป็นหมวดหมู่ของสินค้า

เราไม่แนะนําให้เพิ่มรายการสําหรับพารามิเตอร์รายการ quantity, price หรือ item_id Google Analytics แต่ให้ระบุ itemId, unitPrice และ quantity ของ Item แทน ซึ่งจะมีลำดับความสำคัญเหนือกว่ารายการใดๆ ใน additionalItemParameters

นี่คือตัวอย่าง Event สําหรับข้อมูลที่จัดรูปแบบ แฮช และเข้ารหัสจากเหตุการณ์ที่ 2 พร้อมข้อมูลเพิ่มเติมสําหรับ Google Analytics

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

สร้างเนื้อหาคำขอ

รวม Destination และ Events สำหรับเนื้อหาคำขอ

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

อัปเดตตัวยึดตำแหน่งในเนื้อหา เช่น OPERATING_ACCOUNT_ID และ PRODUCT_DESTINATION_ID ด้วยค่าสำหรับบัญชี และปลายทาง
ตั้งค่า validateOnly เป็น true เพื่อตรวจสอบคำขอโดยไม่ต้องใช้การเปลี่ยนแปลง เมื่อพร้อมที่จะใช้การเปลี่ยนแปลงแล้ว ให้ตั้งค่า validateOnly เป็น false
โปรดทราบว่าตัวอย่างนี้ไม่ได้ใช้การเข้ารหัส

ส่งคำขอ

คัดลอกเนื้อหาคำขอโดยใช้ปุ่มคัดลอกที่ด้านขวาบนของตัวอย่าง
คลิกปุ่ม API ในแถบเครื่องมือ
วางเนื้อหาคำขอที่คัดลอกลงในช่องเนื้อหาคำขอ
คลิกปุ่มดำเนินการ ทำตามข้อความแจ้งการให้สิทธิ์ และตรวจสอบ คำตอบ

การตอบกลับที่สำเร็จ

คำขอที่สำเร็จจะแสดงการตอบกลับพร้อมออบเจ็กต์ที่มี requestId

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

บันทึก requestId ที่ส่งกลับเพื่อให้คุณเรียกข้อมูลการวินิจฉัย ได้เมื่อมีการประมวลผลปลายทางแต่ละแห่งในคำขอ

การตอบกลับที่ล้มเหลว

คำขอที่ไม่สำเร็จจะส่งผลให้รหัสสถานะการตอบกลับข้อผิดพลาด เช่น 400 Bad Request และการตอบกลับที่มีรายละเอียดข้อผิดพลาด

ตัวอย่างเช่น emailAddress ที่มีสตริงข้อความธรรมดาแทนค่าที่เข้ารหัสฐาน 16 จะสร้างการตอบกลับต่อไปนี้

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

emailAddress ที่ไม่ได้แฮชและเข้ารหัสฐาน 16 เท่านั้นจะสร้างการตอบกลับต่อไปนี้

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

ส่งเหตุการณ์ไปยังปลายทางหลายแห่ง

หากข้อมูลมีเหตุการณ์สําหรับปลายทางต่างๆ คุณจะส่งเหตุการณ์เหล่านั้นในคําขอเดียวกันได้โดยใช้การอ้างอิงปลายทาง

เช่น หากคุณมีเหตุการณ์สําหรับรหัสการกระทําที่ถือเป็น Conversion 123456789 และ อีกเหตุการณ์สําหรับรหัสการกระทําที่ถือเป็น Conversion 777111122 ให้ส่งทั้ง 2 เหตุการณ์ในคําขอเดียว โดยตั้งค่า reference ของแต่ละ Destination reference ผู้ใช้กำหนด ข้อกำหนดอย่างเดียวคือ Destination แต่ละรายการต้องมี reference ที่ไม่ซ้ำกัน รายการ destinations ที่แก้ไขสำหรับคำขอมีดังนี้

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

ตั้งค่า destinationReferences ของ Event แต่ละรายการเพื่อส่งไปยังปลายทางที่เฉพาะเจาะจงอย่างน้อย 1 แห่ง ตัวอย่างเช่น Event ต่อไปนี้มีไว้สำหรับ Destination รายการแรกเท่านั้น Destination ดังนั้นลิสต์ destinationReferences จึงมีเฉพาะ reference ของ Destination รายการแรก

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

ฟิลด์ destinationReferences เป็นรายการ คุณจึงระบุปลายทางหลายรายการสำหรับเหตุการณ์ได้ หากคุณไม่ได้ตั้งค่า destinationReferences ของ Event Data Manager API จะส่งเหตุการณ์ไปยังปลายทางทั้งหมดในคำขอ

หากเหตุการณ์มีปลายทางหลายแห่ง Data Manager API จะส่งฟิลด์ที่เกี่ยวข้องไปยัง แต่ละปลายทาง เช่น หากเหตุการณ์มีปลายทาง Google Ads และปลายทาง Google Analytics API จะรวมฟิลด์ Google Analytics เช่น clientId หรือ eventName เมื่อส่งเหตุการณ์ไปยังปลายทาง Google Analytics และรวมฟิลด์ Google Ads เช่น customVariables เมื่อส่งเหตุการณ์ไปยังปลายทาง Google Ads

ขั้นตอนถัดไป

กำหนดค่า การตรวจสอบสิทธิ์และตั้งค่าสภาพแวดล้อมด้วยไลบรารีของไคลเอ็นต์
ดูข้อกำหนดด้านการจัดรูปแบบ การแฮช และการเข้ารหัสสำหรับข้อมูลแต่ละประเภท
ดูวิธีเข้ารหัสข้อมูลผู้ใช้
ดูวิธีดึงข้อมูลการวินิจฉัยสำหรับคำขอ
ดูข้อมูลเกี่ยวกับแนวทางปฏิบัติแนะนำ
ดูข้อมูลเกี่ยวกับขีดจำกัดและโควต้า

ภาพรวมกิจกรรม

เตรียมปลายทาง

เตรียมข้อมูลเหตุการณ์

เหตุการณ์ 1

เหตุการณ์ 2

จัดรูปแบบข้อมูล

เหตุการณ์ 1

เหตุการณ์ 2

แฮชและเข้ารหัสข้อมูล

เหตุการณ์ 1

เหตุการณ์ 2

แปลงข้อมูลเป็นออบเจ็กต์ Event

เพิ่มแอตทริบิวต์เซสชัน

เพิ่มข้อมูล Google Analytics

เพิ่มข้อมูลรถเข็นช็อปปิ้งสําหรับเหตุการณ์การซื้อ

สร้างเนื้อหาคำขอ

ส่งคำขอ

การตอบกลับที่สำเร็จ

การตอบกลับที่ล้มเหลว

ส่งเหตุการณ์ไปยังปลายทางหลายแห่ง

ขั้นตอนถัดไป

แปลงข้อมูลเป็นออบเจ็กต์ `Event`