API Chuyển đổi cho Sự kiện trong ứng dụng

Với API Chuyển đổi, nhà quảng cáo có thể gửi cho Meta các sự kiện trên web, sự kiện trong ứng dụng, sự kiện ở cửa hàng thực và sự kiện nhắn tin kinh doanh thông qua một điểm cuối duy nhất thay vì qua nhiều nguồn. Việc hợp nhất này sẽ tinh giản nhóm công nghệ của nhà quảng cáo và tạo ra chế độ xem toàn diện hơn trong Trình quản lý sự kiện trên Meta dựa trên các tập dữ liệu.

Tài liệu này hướng dẫn tích hợp sự kiện trong ứng dụng với API Chuyển đổi.

Điều kiện tiên quyết

1. Tập dữ liệu

Những sự kiện trong ứng dụng được gửi qua API Chuyển đổi phải được liên kết với một tập dữ liệu.

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.

Bạn có thể thực hiện lệnh gọi GET đến https://graph.facebook.com/v16.0/{ads-pixel-id}/is_consolidated_container để phát hiện xem tập dữ liệu của nhà quảng cáo có được hợp nhất hay không và do đó có đủ điều kiện để chuyển các sự kiện trong ứng dụng qua API Chuyển đổi hay không.

2. Quyền

Để tích hợp trực tiếp làm nhà quảng cáo, hãy làm theo hướng dẫn về quyền và điều kiện tiên quyết tại đây.
Để tích hợp nền tảng đối tác, vui lòng làm theo hướng dẫn về quyền và điều kiện tiên quyết tại đây.

Cấu hình

Gửi sự kiện trong ứng dụng đến API Chuyển đổi

a. Liên kết ID tập dữ liệu và ID ứng dụng

Trong Trình quản lý sự kiện, bạn có thể liên kết ứng dụng của mình với một tập dữ liệu theo 2 cách sau đây:

Chọn tab "Nguồn dữ liệu", tìm tab "Cài đặt" trên ứng dụng của bạn và tiến hành liên kết.
Chọn tab "Nguồn dữ liệu", ở tab "Tổng quan" trên ứng dụng của bạn, hãy sử dụng nút "Liên kết đến tập dữ liệu" trong phần "Tất cả hoạt động".

Sau khi bạn liên kết xong, tập dữ liệu sẽ chứa ứng dụng đã kết nối.

b. Trường bắt buộc

Bạn có thể tham khảo tại đây để biết nhóm thông số hiện tại gửi được qua API Chuyển đổi. Để gửi sự kiện trong ứng dụng, bạn có thể chia sẻ các trường server_event sau đây trong phần tải dữ liệu:

Thông số action_source phải chứa giá trị app cho sự kiện trong ứng dụng.
event_id là bắt buộc đối với trường hợp thiết lập cơ chế bỏ trùng lặp.
Các trường app_data
Các trường user_data
Các trường custom_data

Trường dữ liệu ứng dụng

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.
`windows_attribution_id` string	Optional Attribution token used for Windows 10.

Thông số thông tin khách hàng

Thông số	Mô tả
`anon_id` chuỗi	Không băm. ID lượt cài đặt. Trường này biểu thị phiên bản cài đặt ứng dụng duy nhất.
`madid` chuỗi	Không băm. ID nhà quảng cáo di động, ID quảng cáo từ thiết bị Android hoặc Mã nhận dạng quảng cáo (IDFA) từ thiết bị Apple.

Dữ liệu tùy chỉnh

Thông số	Mô tả
`description` chuỗi	Không bắt buộc. Chuỗi, nội dung mô tả sự kiện, tùy chỉnh.
`level` chuỗi	Không bắt buộc. Chuỗi, Cấp độ của game, tùy chỉnh.
`max_rating_value`	Không bắt buộc. Số nguyên dài, Giới hạn trên của thang xếp hạng (ví dụ: 5 trên thang 5 sao), tùy chỉnh.
`success` boolean	Không bắt buộc. `1` cho có, `0` cho không, tùy chỉnh.

Tóm lại, những sự kiện trong ứng dụng được chia sẻ qua API Chuyển đổi sẽ cần có các thông số dữ liệu sau đây:

action_source: Phải được đặt là "app" (ứng dụng). (Bằng cách sử dụng API Chuyển đổi, bạn đồng ý rằng thông số action_source là chính xác theo hiểu biết của bạn)
event_id: Bắt buộc khi thiết lập cơ chế bỏ trùng lặp, hãy xem chi tiết trong phần "Thiết lập cơ chế bỏ trùng lặp cho nhiều kênh".
advertiser_tracking_enabled
application_tracking_enabled
extinfo

Dưới đây là ví dụ về extinfo. Đảm bảo rằng tất cả thông số phụ bên dưới đều được điền giá trị và theo tuần tự. Nếu thiếu giá trị nào, hãy dùng một chuỗi trống làm phần giữ chỗ.

Tên thông số phụ	Bắt buộc	Loại dữ liệu	Ví dụ
phiên bản extinfo	Có	chuỗi	`i2` (phiên bản phải là a2 đối với Android, i2 đối với iOS)
tên gói ứng dụng	Không	chuỗi	`com.facebook.sdk.samples.hellofacebook`
phiên bản ngắn	Không	chuỗi	`1.0`
phiên bản dài	Không	chuỗi	`1.0 long`
phiên bản hệ điều hành	Có	chuỗi	`13.4.1`
tên kiểu thiết bị	Không	chuỗi	`iPhone5,1`
ngôn ngữ	Không	chuỗi	`En_US`
chữ viết tắt múi giờ	Không	chuỗi	`PDT`
nhà mạng	Không	chuỗi	`AT&T`
chiều rộng màn hình	Không	chuỗi	`320`
chiều cao màn hình	Không	chuỗi	`568`
độ phân giải của màn hình	Không	chuỗi	`2`
lõi cpu	Không	chuỗi	`2`
kích thước bộ nhớ ngoài	Không	chuỗi	`13`
dung lượng trống trong kích thước bộ nhớ ngoài	Không	chuỗi	`8`
múi giờ của thiết bị	Không	chuỗi	`USA/New York`

c. Thiết lập cơ chế bỏ trùng lặp cho nhiều kênh

Bạn sẽ cần có cơ chế bỏ trùng lặp để loại bỏ lưu lượng truy cập sự kiện trùng lặp giữa quá trình tích hợp API Chuyển đổi và mọi quá trình tích hợp hiện có khác mà bạn có sự kiện trong ứng dụng, bao gồm cả SDK, MMP và API Sự kiện trong ứng dụng.

Đối với sự kiện trong ứng dụng, chúng tôi áp dụng chức năng bỏ trùng lặp tương tự như đối với sự kiện trên web. Logic này tận dụng chức năng bỏ trùng lặp dựa trên trường event_id và event_name (sự kiện API Chuyển đổi và SDK/API Sự kiện trong ứng dụng có cùng một event_id). Thông số event_id là thông tin nhận dạng có thể phân biệt rõ giữa các sự kiện tương tự nhau. ID sự kiện không chính xác có thể khiến hệ thống loại bỏ trùng lặp nhầm lượt chuyển đổi, do đó ảnh hưởng đến báo cáo lượt chuyển đổi và hiệu quả chiến dịch.

Bạn có thể tham khảo tài liệu dành cho nhà phát triển dưới đây để triển khai cách thiết lập cơ chế bỏ trùng lặp:

Dưới đây là ví dụ về cách ghi sự kiện tùy chỉnh. Để làm như vậy, hãy chuyển tên của sự kiện dưới dạng AppEvents.Name vào iOS SDK:

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

Đối với sự kiện cài đặt ứng dụng, hiện đã có cơ chế bỏ trùng lặp để đảm bảo rằng chỉ ghi nhận 1 lượt cài đặt trong khoảng thời gian 90 ngày qua. Chúng tôi giữ lại sự kiện đầu tiên và bỏ các sự kiện sau này, bất kể sự kiện đến từ nguồn hành động nào. Không có yêu cầu khi triển khai cơ chế bỏ trùng lặp cho các sự kiện trong ứng dụng liên quan đến sự kiện cài đặt.

d. Gửi sự kiện

Để gửi sự kiện mới, hãy gửi yêu cầu POST đến API Chuyển đổi từ đường dẫn sau: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}. Khi bạn gửi đến cạnh này, Meta sẽ tạo sự kiện mới trên máy chủ ứng dụng. Để biết thêm chi tiết, hãy tham khảo tài liệu dành cho nhà phát triển dưới đây.

Sau đây là thông tin tổng quan về cách sắp xếp thông số theo lược đồ chung trong phần tải dữ liệu:

** Khắc phục sự cố**

Bạn có thể dùng công cụ Trình trợ giúp phần tải dữ liệu để tạo dữ liệu cho phần tải dữ liệu:

Chọn nguồn hành động app, nếu có
Điền thông tin cho các sự kiện sẽ được gửi đến Meta
Thao tác này sẽ tạo phần tải dữ liệu sự kiện mà bạn có thể dùng làm mẫu để tích hợp API Chuyển đổi

Sử dụng công cụ Thử nghiệm sự kiện trong Trình quản lý sự kiện để thử nghiệm.