การส่งเหตุการณ์แบบออฟไลน์โดยใช้ API คอนเวอร์ชั่น

API คอนเวอร์ชั่นเป็นวิธีการผสานการทำงานที่ Meta แนะนำในการส่งเหตุการณ์แบบออฟไลน์และเหตุการณ์ที่หน้าร้านไปยัง Meta เพื่อใช้ในการวัดผล การระบุที่มา และการกำหนดเป้าหมายโฆษณา โดยหน้านี้จะให้รายละเอียดเกี่ยวกับวิธีส่งเหตุการณ์แบบออฟไลน์ผ่าน API คอนเวอร์ชั่นโดยตรงหรือผ่านการผสานการทำงานกับพาร์ทเนอร์

ข้อกำหนดเบื้องต้น

ชุดข้อมูล

เหตุการณ์แบบออฟไลน์ที่ส่งผ่าน API คอนเวอร์ชั่นจะต้องเชื่อมโยงกับชุดข้อมูล

Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:

Meta Pixel (website events)
App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))
Offline Conversions API (Meta’s legacy API for offline events)
Messaging Events API (messaging events)

Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.

In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.

คุณสามารถเรียกใช้คำสั่ง GET ไปยัง https://graph.facebook.com/v16.0/{ads-pixel-id}/is_consolidated_container เพื่อตรวจสอบว่าชุดข้อมูลของผู้ลงโฆษณาถูกรวมเข้าด้วยกันและมีสิทธิ์ส่งเหตุการณ์แบบออฟไลน์โดยใช้ API คอนเวอร์ชั่นหรือไม่

สิทธิ์การอนุญาต

หากต้องการใช้การผสานการทำงานโดยตรงในฐานะผู้ลงโฆษณา โปรดปฏิบัติตามคำแนะนำที่นี่เพื่อดูข้อกำหนดเบื้องต้นและสิทธิ์การอนุญาต
หากต้องการใช้การผสานการทำงานกับแพลตฟอร์มของพาร์ทเนอร์ โปรดปฏิบัติตามคำแนะนำที่นี่เพื่อดูข้อกำหนดเบื้องต้นและสิทธิ์การอนุญาต

การกำหนดค่า

1. ตั้งค่าพารามิเตอร์เหตุการณ์แบบออฟไลน์

ผู้ลงโฆษณาสามารถใช้การตั้งค่าที่อธิบายไว้ที่นี่ และดูชุดพารามิเตอร์ปัจจุบันที่สามารถส่งผ่าน API คอนเวอร์ชั่นได้ สำหรับการส่งเหตุการณ์แบบออฟไลน์และเหตุการณ์ในร้านค้า คุณสามารถแชร์ช่องต่อไปนี้ในเพย์โหลดได้

ผู้ลงโฆษณาต้องส่ง action_source เป็น physical_store สำหรับเหตุการณ์แบบออฟไลน์และเหตุการณ์ในร้านค้าทั้งหมด ทั้งนี้ โปรดทราบว่าเหตุการณ์บนเซิร์ฟเวอร์ทุกประเภทจะต้องระบุพารามิเตอร์นี้ เมื่อใช้ API คอนเวอร์ชั่น แสดงว่าคุณยอมรับว่าพารามิเตอร์ action_source นั้นถูกต้องเท่าที่คุณทราบ
คุณต้องระบุช่องเหตุการณ์บนเซิร์ฟเวอร์ทั้งหมดที่จำเป็นสำหรับ API คอนเวอร์ชั่น
พารามิเตอร์ข้อมูลลูกค้า (ดูรายการพารามิเตอร์ที่เหมาะสำหรับเหตุการณ์แบบออฟไลน์และเหตุการณ์ในร้านค้าได้ที่ด้านล่าง)
พารามิเตอร์ข้อมูลที่กำหนดเอง (ดูรายการพารามิเตอร์ที่เหมาะสำหรับเหตุการณ์แบบออฟไลน์และเหตุการณ์ในร้านค้าได้ที่ด้านล่าง)
พารามิเตอร์ที่ระบุหรือไม่ก็ได้: เรายังคงรองรับพารามิเตอร์ upload_tag ในการอัพโหลดเหตุการณ์แบบออฟไลน์สำหรับผู้ลงโฆษณาที่ใช้ API แบบเดิมกับเหตุการณ์แบบออฟไลน์

พารามิเตอร์ข้อมูลลูกค้า

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

ชื่อพารามิเตอร์	พารามิเตอร์	ต้องแฮชหรือไม่
ที่อยู่อีเมล	`email`	ต้องแฮช
หมายเลขโทรศัพท์มือถือ	`phone`	ต้องแฮช
เพศ	`gen`	ต้องแฮช
วันเกิด	`db`	ต้องแฮช
นามสกุล	`ln`	ต้องแฮช
ชื่อจริง	`fn`	ต้องแฮช
เมือง	`ct`	ต้องแฮช
รัฐในสหรัฐฯ	`st`	ต้องแฮช
รหัสไปรษณีย์	`zip`	ต้องแฮช
ประเทศ	`country`	ต้องแฮช
ตัวระบุโฆษณาของ Apple	`madid`	ต้องแฮช
ID การโฆษณาของ Android	`madid`	ต้องแฮช
ID ผู้ใช้ภายนอก	`external_id`	แนะนำเป็นอย่างยิ่ง
ID ข้อมูลลูกค้าจากโฆษณาแบบกรอกฟอร์ม	`lead_id`	ไม่ต้องแฮช

พารามิเตอร์ข้อมูลที่กำหนดเอง

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

พารามิเตอร์ คำอธิบาย

พารามิเตอร์	คำอธิบาย
`event_time` ประเภท: จำนวนเต็ม	จำเป็นต้องระบุ ประทับเวลา UNIX ของเหตุการณ์คอนเวอร์ชั่น ตัวอย่าง: `'1456870055'`
`event_name` ประเภท: สตริง	จำเป็นต้องระบุ ประเภทเหตุการณ์ ตัวอย่าง: `ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other`
`store_data` ประเภท: พจนานุกรม JSON	ระบุหรือไม่ก็ได้ จัดเก็บข้อมูลตำแหน่งเกี่ยวกับเหตุการณ์คอนเวอร์ชั่น ตัวอย่าง: "store_data": { "store_page_id": 8576093908, // FBID "brand_page_id": 10236898932// FBID }
`currency` ประเภท: สตริง	จำเป็นต้องระบุ รหัสสกุลเงิน ISO จำนวน 3 ตัวอักษรสำหรับเหตุการณ์คอนเวอร์ชั่นนี้ จำเป็นต้องระบุสำหรับเหตุการณ์ `Purchase` ตัวอย่าง: `USD`
`value` ประเภท: ทศนิยม	จำเป็นต้องระบุ ค่าของเหตุการณ์คอนเวอร์ชั่น จำเป็นต้องระบุสำหรับเหตุการณ์ `Purchase` ตัวอย่าง: `16.00`
`content_type` ประเภท: สตริง	ระบุหรือไม่ก็ได้ `content_type` ของแค็ตตาล็อกโฆษณาแค็ตตาล็อก Advantage+ ที่ถูกต้อง ตัวอย่าง: `product`
`contents` ประเภท: อาร์เรย์ JSON	ระบุหรือไม่ก็ได้ จำเป็นต้องระบุ หากคุณผสานโฆษณาของคุณเข้ากับแค็ตตาล็อก จำเป็นต้องระบุ: `id`, `quantity` แนะนำ: `price`, `brand`, `category` จำเป็นต้องระบุ: `[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]` แนะนำ: `[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]`
`custom_data` ประเภท: พจนานุกรม JSON	ระบุหรือไม่ก็ได้ ข้อมูลเกี่ยวกับเหตุการณ์คอนเวอร์ชั่นนี้ ตัวอย่าง: `{category: 'ICECREAM'}`
`order_id` ประเภท: สตริง	ระบุหรือไม่ก็ได้ ตัวระบุที่ไม่ซ้ำกันสำหรับธุรกรรมหรือคำสั่งซื้อแต่ละรายการในชุดเหตุการณ์แบบออฟไลน์ ตัวอย่างเช่น สำหรับการขายปลีกอาจเป็น ID ใบเสร็จ ตัวอย่าง: `ATN10001`, `123456`
`item_number` ประเภท: สตริง	ระบุหรือไม่ก็ได้ ตัวระบุที่ไม่ซ้ำกันเพื่อแยกแยะเหตุการณ์ในคำสั่งซื้อหรือธุรกรรมเดียวกัน ตัวอย่าง: `1`, `a`

event_time

ประเภท: จำนวนเต็ม

จำเป็นต้องระบุ

ประทับเวลา UNIX ของเหตุการณ์คอนเวอร์ชั่น

ตัวอย่าง:
'1456870055'

event_name
ประเภท: สตริง

จำเป็นต้องระบุ

ประเภทเหตุการณ์

ตัวอย่าง:
ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other

store_data
ประเภท: พจนานุกรม JSON

ระบุหรือไม่ก็ได้

จัดเก็บข้อมูลตำแหน่งเกี่ยวกับเหตุการณ์คอนเวอร์ชั่น

ตัวอย่าง:

"store_data":
    {
        "store_page_id": 8576093908, // FBID
        "brand_page_id": 10236898932// FBID
    }

currency
ประเภท: สตริง

จำเป็นต้องระบุ

รหัสสกุลเงิน ISO จำนวน 3 ตัวอักษรสำหรับเหตุการณ์คอนเวอร์ชั่นนี้ จำเป็นต้องระบุสำหรับเหตุการณ์ Purchase

ตัวอย่าง:
USD

value
ประเภท: ทศนิยม

จำเป็นต้องระบุ

ค่าของเหตุการณ์คอนเวอร์ชั่น จำเป็นต้องระบุสำหรับเหตุการณ์ Purchase

ตัวอย่าง:
16.00

content_type ประเภท: สตริง

ระบุหรือไม่ก็ได้

content_type ของแค็ตตาล็อกโฆษณาแค็ตตาล็อก Advantage+ ที่ถูกต้อง

ตัวอย่าง:
product

contents

ประเภท: อาร์เรย์ JSON

ระบุหรือไม่ก็ได้ จำเป็นต้องระบุ หากคุณผสานโฆษณาของคุณเข้ากับแค็ตตาล็อก

จำเป็นต้องระบุ: id, quantity

แนะนำ: price, brand, category

จำเป็นต้องระบุ: [ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]

แนะนำ: [ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]

custom_data

ประเภท: พจนานุกรม JSON

ระบุหรือไม่ก็ได้

ข้อมูลเกี่ยวกับเหตุการณ์คอนเวอร์ชั่นนี้

ตัวอย่าง: {category: 'ICECREAM'}

order_id

ประเภท: สตริง

ระบุหรือไม่ก็ได้

ตัวระบุที่ไม่ซ้ำกันสำหรับธุรกรรมหรือคำสั่งซื้อแต่ละรายการในชุดเหตุการณ์แบบออฟไลน์ ตัวอย่างเช่น สำหรับการขายปลีกอาจเป็น ID ใบเสร็จ

ตัวอย่าง: ATN10001, 123456

item_number

ประเภท: สตริง

ระบุหรือไม่ก็ได้

ตัวระบุที่ไม่ซ้ำกันเพื่อแยกแยะเหตุการณ์ในคำสั่งซื้อหรือธุรกรรมเดียวกัน

ตัวอย่าง: 1, a

2. การส่งเหตุการณ์

หากต้องการส่งเหตุการณ์ใหม่ ให้ส่งคำขอ POST ไปยัง API คอนเวอร์ชั่นจากเส้นทางนี้: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

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

ด้านล่างนี้คือภาพรวมที่แสดงให้เห็นว่าพารามิเตอร์มีการปรับให้เข้ากับสกีมาโดยรวมในเพย์โหลดอย่างไร:

curl -X POST \
  -F 'data=[
       {
  "event_name": "Purchase",
  "event_time": 1674000041,
  "user_data": {
    "em": [
      "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
    ],
    "ph": [
      "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
      "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
    ]
  },
  "custom_data": {
    "currency": "usd",
    "value": 123.45,
    "contents": [{
      "id": "product123",
      "quantity": 1
    }]
  },
  "action_source": "physical_store"
}
]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v15.0/<DATASET_ID>/events

เราขอแนะนำให้อัพโหลดแบบเรียลไทม์หรืออัพโหลดเป็นประจำทุกวันเพื่อให้ได้ผลการปรับให้เหมาะสมที่ดีที่สุด ซึ่งจะช่วยให้ระบบสามารถเปรียบเทียบข้อมูลแบบออฟไลน์กับประสิทธิภาพของโฆษณาที่คุณกำลังเผยแพร่ได้อย่างมีประสิทธิภาพ

event_time สามารถเกิดขึ้นก่อนที่คุณจะส่งเหตุการณ์ไปยัง Meta ได้สูงสุด 7 วัน หาก event_time ใน data ผ่านมาแล้วมากกว่า 7 วัน เราจะส่งคืนข้อผิดพลาดสำหรับคำขอทั้งหมด และจะไม่ประมวลผลเหตุการณ์ สำหรับเหตุการณ์ออฟไลน์และเหตุการณ์ที่หน้าร้านซึ่งมี physical_store เป็น action_source คุณควรอัพโหลดการดำเนินการภายใน 62 วันนับจากการสนทนา

ข้อมูลที่คุณอัพโหลดจะถูกประมวลผลแบบเรียลไทม์เพื่อให้คุณสามารถดูผลลัพธ์ได้ทันทีที่คุณเพิ่มข้อมูล คุณสามารถดูเอกสารจากศูนย์ช่วยเหลือเกี่ยวกับหลักปฏิบัติที่ดีที่สุดสำหรับข้อมูลเหตุการณ์แบบออฟไลน์ได้

3. ตั้งค่าการลบข้อมูลซ้ำ

คุณสามารถลบได้เฉพาะข้อมูลเหตุการณ์แบบออฟไลน์ที่ซ้ำกับเหตุการณ์แบบออฟไลน์อื่นๆ เท่านั้น ซึ่งต่างจากการตั้งค่าการลบข้อมูลซ้ำระหว่างเหตุการณ์ API คอนเวอร์ชั่นและเหตุการณ์พิกเซลของ Meta โดยเรารองรับวิธีการลบข้อมูลซ้ำ 2 วิธี ได้แก่ การลบข้อมูลซ้ำตาม order_id หรือตาม user ซึ่งการลบข้อมูลซ้ำจะใช้ช่องต่างๆ รวมกัน ได้แก่ dataset_id, event_time, event_name, item_number และช่องคีย์ตามวิธีการในเพย์โหลดของเหตุการณ์นั้นๆ

การลบข้อมูลซ้ำโดยค่าเริ่มต้นจะใช้ order_id พร้อมด้วยช่องต่างๆ ที่อธิบายไว้ข้างต้นรวมกัน แต่หากไม่มี order_id ในเพย์โหลด ระบบจะใช้ตรรกะการลบข้อมูลซ้ำตาม user

ตัวอย่างเช่น หากมีคำสั่งซื้อ 2 รายการที่มี event_time, event_name เหมือนกัน และมี order_id เดียวกันหรือมีชุดพารามิเตอร์ข้อมูลลูกค้าที่ไม่มี order_id เหมือนกัน เราจะถือว่าเหตุการณ์เหล่านี้เป็นเหตุการณ์ซ้ำและจะใช้ข้อมูลจากเหตุการณ์แรก ซึ่งการลบข้อมูลซ้ำตาม user จะใช้ได้กับช่องพารามิเตอร์ข้อมูลลูกค้าใน 2 เพย์โหลดนี้เท่านั้น

การลบข้อมูลซ้ำจะมีกรอบเวลาสูงสุดอยู่ที่ 7 วัน

4. การแก้ไขปัญหาเหตุการณ์

คุณสามารถใช้เครื่องมือช่วยเหลือเพย์โหลดเพื่อสร้างข้อมูลเพย์โหลด โดยมีวิธีดังนี้

เลือกแหล่งที่มาของการดำเนินการ app หากมี เมื่อใช้ API คอนเวอร์ชั่น แสดงว่าคุณยอมรับว่าพารามิเตอร์ action_source นั้นถูกต้องเท่าที่คุณทราบ
กรอกข้อมูลเหตุการณ์ที่จะถูกส่งไปยัง Meta
การดำเนินการนี้จะสร้างเพย์โหลดเหตุการณ์ ซึ่งสามารถใช้เป็นเทมเพลตสำหรับการผสานการทำงาน API คอนเวอร์ชั่นของคุณได้

ใช้เครื่องมือทดสอบเหตุการณ์ในตัวจัดการเหตุการณ์สำหรับการทดสอบ ทั้งนี้ โปรดทราบว่าเครื่องมือทดสอบเหตุการณ์รองรับเฉพาะเหตุการณ์บนเว็บและเหตุการณ์ในแอพเท่านั้น

การส่งเหตุการณ์แบบออฟไลน์โดยใช้ API คอนเวอร์ชั่น

ข้อกำหนดเบื้องต้น

ชุดข้อมูล

สิทธิ์การอนุญาต

การกำหนดค่า

1. ตั้งค่าพารามิเตอร์เหตุการณ์แบบออฟไลน์

พารามิเตอร์ข้อมูลลูกค้า

พารามิเตอร์ข้อมูลที่กำหนดเอง

2. การส่งเหตุการณ์

3. ตั้งค่าการลบข้อมูลซ้ำ

4. การแก้ไขปัญหาเหตุการณ์

ดูเพิ่มเติม

บทความของศูนย์ช่วยเหลือทางธุรกิจ