API คอนเวอร์ชั่นสำหรับเหตุการณ์ในแอพ

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

เอกสารฉบับนี้จะให้คำแนะนำในการผสานการทำงานเหตุการณ์ในแอพเข้ากับ API คอนเวอร์ชั่น

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

1. ชุดข้อมูล

เหตุการณ์ในแอพที่ส่งผ่าน 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 คอนเวอร์ชั่นหรือไม่

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

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

การกำหนดค่า

การส่งเหตุการณ์ในแอพไปยัง API คอนเวอร์ชั่น

a. การลิงก์ ID ชุดข้อมูลและ ID ของแอพ

ในตัวจัดการเหตุการณ์ จะมีวิธีลิงก์แอพของคุณกับชุดข้อมูลอยู่ 2 วิธีดังนี้

เลือกแท็บ "แหล่งข้อมูล" ค้นหาแท็บ "การตั้งค่า" ของแอพ แล้วทำการลิงก์
ในแท็บ "ภาพรวม" ของแอพ ให้เลือกแท็บ "แหล่งข้อมูล" จากนั้นให้ใช้ปุ่ม "ลิงก์กับชุดข้อมูล" ในส่วน "กิจกรรมทั้งหมด"

เมื่อคุณลิงก์เสร็จแล้ว ชุดข้อมูลจะมีแอพที่เชื่อมต่อด้วย

b. ช่องที่ต้องระบุ

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

พารามิเตอร์ action_source ต้องมีค่า app สำหรับเหตุการณ์ในแอพ
ต้องระบุ event_id สำหรับกรณีการตั้งค่าการลบเหตุการณ์ซ้ำซ้อน
ช่อง app_data
ช่อง user_data
ช่อง custom_data

ช่องข้อมูลแอพ

Parameter	Description
`advertiser_tracking_enabled` boolean	Required for app events Use this field to specify ATT permission on an iOS 14.5+ device. Set to `0` for disabled or `1` for enabled.
`application_tracking_enabled` boolean	Required for app events A person can choose to enable ad tracking on an app level. Your SDK should allow an app developer to put an opt-out setting into their app. Use this field to specify the person's choice. Use `0` for disabled, `1` for enabled. `
`extinfo` object Please use the down arrow to the right to see the list of `extinfo` values.	Required for app events Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using `extinfo`, all values are required and must be in the order indexed below. If a value is missing, fill with an empty string as a placeholder. Note: `version` must be `a2` for Android `version` must be `i2` for iOS
`0` string	Required extinfo version Example: `i2`
`1` string	app package name Example: `com.facebook.sdk.samples.hellofacebook`
`2` string	short version (int or string) Example: `1.0`
`3` string	long version Example: `1.0 long`
`4` string	Required OS version Example: `13.4.1`
`5` string	device model name Example: `iPhone5,1`
`6` string	locale Example: `En_US`
`7` string	timezone abbreviation Example: `PDT`
`8` string	carrier Example: `AT&T`
`9` string	screen width Example: `320`
`10` string	screen height Example: `568`
`11` string	screen density Example: `2`
`12` string	CPU cores Example: `2`
`13` string	external storage size in GB Example: `13`
`14` string	free space on external storage in GB Example: `8`
`15` string	device timezone Example: `USA/New York`
`campaign_ids` string	Optional An encrypted string and non-user metadata appended to the outbound URL (for example, ad_destination_url) or deep link (for App Aggregated Event Manager) when a user clicked on a link from Facebook. Graph API definition: Parameter passed via the deep link for Mobile App Engagement campaigns.
`install_referrer` string	Optional Third party install referrer, currently available for Android only, see here for more.
`installer_package` string	Optional Used internally by the Android SDKs
`url_schemes` array	Optional Used internally by the iOS and Android SDKs.
`vendor_id` string	Optional Vendor ID.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

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

พารามิเตอร์	คำอธิบาย
`anon_id` สตริง	ไม่ต้องแฮช ID การติดตั้งของคุณ ช่องนี้แสดงถึงอินสแตนซ์การติดตั้งแอพพลิเคชั่นที่ไม่ซ้ำกัน
`madid` สตริง	ไม่ต้องแฮช ID ผู้ลงโฆษณาบนมือถือของคุณ, ID การโฆษณาจากอุปกรณ์ Android หรือตัวระบุการโฆษณา (IDFA) จากอุปกรณ์ Apple

ข้อมูลแบบกำหนดเอง

พารามิเตอร์	คำอธิบาย
`description` สตริง	ระบุหรือไม่ก็ได้ สตริง, คำอธิบายเหตุการณ์, กำหนดเอง
`level` สตริง	ระบุหรือไม่ก็ได้ สตริง, เลเวลของเกม, กำหนดเอง
`max_rating_value`	ระบุหรือไม่ก็ได้ ยาว, ระดับการให้คะแนนสูงสุด เช่น 5 ดาวจากคะแนนเต็ม 5 ดาว, กำหนดเอง
`success` บูลีน	ระบุหรือไม่ก็ได้ `1` หมายถึง "ใช่", `0` หมายถึง "ไม่", กำหนดเอง

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

action_source: ต้องตั้งเป็น "แอพ" (เมื่อคุณใช้ API คอนเวอร์ชั่น แสดงว่าคุณยอมรับว่าพารามิเตอร์ action_source นั้นถูกต้องตามขอบเขตความเข้าใจสูงสุดที่คุณมี)
event_id: จำเป็นต้องระบุสำหรับการตั้งค่าการลบเหตุการณ์ซ้ำซ้อน โปรดดูรายละเอียดในส่วน "ตั้งค่าการลบเหตุการณ์ซ้ำซ้อนสำหรับหลายช่องทาง"
advertiser_tracking_enabled
application_tracking_enabled
extinfo

ด้านล่างนี้คือตัวอย่างของ extinfo ตรวจสอบให้แน่ใจว่าได้กรอกพารามิเตอร์ย่อยทั้งหมดด้านล่างและเรียงตามลำดับ หากมีพารามิเตอร์ใดหายไป ให้ใช้สตริงเปล่าเป็นตัวยึดตำแหน่ง

ชื่อพารามิเตอร์ย่อย	จำเป็นต้องระบุหรือไม่	ประเภทของข้อมูล	ตัวอย่าง
เวอร์ชั่นของ extinfo	ใช่	สตริง	`i2` (ต้องเป็นเวอร์ชั่น a2 สำหรับ Android และเป็นเวอร์ชั่น i2 สำหรับ iOS)
ชื่อแพ็คเกจแอพ	ไม่ใช่	สตริง	`com.facebook.sdk.samples.hellofacebook`
แบบสั้น	ไม่ใช่	สตริง	`1.0`
แบบยาว	ไม่ใช่	สตริง	`1.0 long`
เวอร์ชั่นของระบบปฏิบัติการ	ใช่	สตริง	`13.4.1`
ชื่อรุ่นของอุปกรณ์	ไม่ใช่	สตริง	`iPhone5,1`
ภาษา	ไม่ใช่	สตริง	`En_US`
ตัวย่อเขตเวลา	ไม่ใช่	สตริง	`PDT`
ผู้ให้บริการ	ไม่ใช่	สตริง	`AT&T`
ความกว้างของหน้าจอ	ไม่ใช่	สตริง	`320`
ความสูงของหน้าจอ	ไม่ใช่	สตริง	`568`
ความหนาแน่นของหน้าจอ	ไม่ใช่	สตริง	`2`
จำนวน Core ของ CPU	ไม่ใช่	สตริง	`2`
ขนาดของพื้นที่เก็บข้อมูลภายนอก	ไม่ใช่	สตริง	`13`
พื้นที่ว่างในขนาดของพื้นที่เก็บข้อมูลภายนอก	ไม่ใช่	สตริง	`8`
โซนเวลาของอุปกรณ์	ไม่ใช่	สตริง	`USA/New York`

c. ตั้งค่าการลบเหตุการณ์ซ้ำซ้อนสำหรับหลายช่องทาง

จะต้องมีกลไกการลบเหตุการณ์ซ้ำซ้อนเพื่อลบการรับส่งข้อมูลเหตุการณ์ที่ซ้ำกันระหว่างการผสานการทำงาน API คอนเวอร์ชั่นและการผสานการทำงานอื่นๆ ที่มีอยู่ทั้งหมดที่คุณมีกับเหตุการณ์ในแอพ ซึ่งประกอบด้วย SDK, MMP และ API เหตุการณ์ในแอพ

สำหรับเหตุการณ์ในแอพ เราใช้ฟังก์ชั่นการลบเหตุการณ์ซ้ำซ้อนแบบเดียวกับที่มีอยู่สำหรับเหตุการณ์บนเว็บ ตรรกะจะใช้ประโยชน์จากช่อง event_id และ event_name ตามการลบเหตุการณ์ซ้ำซ้อน (เหตุการณ์ API คอนเวอร์ชั่นและ SDK / API เหตุการณ์ในแอพที่มี event_id เดียวกัน) พารามิเตอร์ event_id คือตัวระบุที่สามารถแยกความแตกต่างระหว่างเหตุการณ์ที่คล้ายกันได้โดยไม่ซ้ำกัน ID เหตุการณ์ที่ไม่ถูกต้องอาจทำให้คอนเวอร์ชั่นของคุณมีการลบเหตุการณ์ซ้ำซ้อนอย่างไม่ถูกต้อง ซึ่งส่งผลต่อการรายงานคอนเวอร์ชั่นและประสิทธิภาพของแคมเปญ

คุณสามารถดูเอกสารสำหรับผู้พัฒนาต่อไปนี้เพื่อนำการตั้งค่าการลบเหตุการณ์ซ้ำซ้อนไปใช้

นี่คือตัวอย่างวิธีลงบันทึกเหตุการณ์ที่กำหนดเอง โดยมีวิธีคือ ให้ส่งชื่อของเหตุการณ์เป็น AppEvents.Name ใน SDK สำหรับ iOS:

AppEvents.shared.logEvent(.achievedLevel, parameters: [AppEvents.ParameterName(rawValue: "event_id"): "123"])

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

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

หากต้องการส่งเหตุการณ์ใหม่ ให้ส่งคำขอ POST ไปยัง API คอนเวอร์ชั่นจากเส้นทางนี้: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN} เมื่อคุณโพสต์ไปยังจุดเชื่อมโยงนี้ Meta จะสร้างเหตุการณ์บนเซิร์ฟเวอร์แอพใหม่ โปรดดูรายละเอียดเพิ่มเติมที่เอกสารสำหรับผู้พัฒนาต่อไปนี้

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

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": 1684389752,
            "action_source": "app",
            "user_data": {
                "em": [
                    "30a79640dfd8293d4f4965ec11821f640ca77979ca0a6b365f06372f81a3f602"
                ],
                "ph": [
                    "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
                    "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b"
                ],
                "madid": "bbbbbbbbbbbb",
      "anon_id": "cccccccc"
            },
            "custom_data": {
                "currency": "USD",
                "value": "142.52"
            },
            "app_data": {
                "advertiser_tracking_enabled": "True",
                "application_tracking_enabled": "True",
                "campaign_ids": "aaaaaaaaa",
                "extinfo": [
                    "a2",
                    "com.some.app",
                    "771",
                    "Version 7.7.1",
                    "10.1.1",
                    "OnePlus6",
                    "en_US",
                    "GMT-1",
                    "TMobile",
                    "1920",
                    "1080",
                    "2.00",
                    "2",
                    "128",
                    "8",
                    "USA/New York"
                ]
            }
        }
    ]
}

การแก้ไขปัญหา

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

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

ใช้เครื่องมือทดสอบเหตุการณ์ในตัวจัดการเหตุการณ์สำหรับการทดสอบ