应用事件专用转化 API

广告主可以使用转化 API 通过单个端点（而非多个来源）向 Meta 发送网站、应用和实体店这三类事件以及业务消息事件。应用事件与转化 API 的合并将简化广告主的技术堆栈，并将在 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.

您可以向 https://graph.facebook.com/v16.0/{ads-pixel-id}/is_consolidated_container 发出 GET 调用，以检测广告主的数据集是否经过整合，并因此符合通过转化 API 传递应用事件的条件。

2. 权限

如要以广告主的身份实现直接集成，请按照此处说明操作，了解各项前提条件和权限。
如要在合作伙伴平台实现集成，请按照此处说明操作，了解各项前提条件和权限。

配置

将应用事件发送到转化 API

a. 将数据集编号与应用编号绑定

在事件管理工具中，可使用两种方法绑定您的应用与数据集：

选择“数据源”选项卡，找到应用的“设置”选项卡并执行绑定。
在应用的“概览”选项卡中，选择“数据源”选项卡，然后使用“所有活动”部分中的“绑定数据集”按钮。

完成绑定后，数据集中将包含已绑定的应用。

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

客户信息参数

参数	描述
`anon_id` string	无需进行哈希处理。您的安装编号。此字段表示唯一的应用程序安装实例。
`madid` string	无需进行哈希处理。您的移动广告客户编号、Android 设备中的广告编号或 Apple 设备中的广告 ID (IDFA)。

自定义数据

参数	描述
`description` string	可选。自定义字符串，表示对某一事件的描述。
`level` string	可选。自定义字符串，表示游戏关卡。
`max_rating_value`	可选。类型为 long，可自定义，表示评分区间的上限，例如：5 星区间的上限为 5 星。
`success` 布尔值	可选。可自定义。`1` 表示“是”，`0` 表示“否”。

总之，使用转化 API 分享的应用事件将需要以下数据参数：

action_source：必须设为“应用”。（使用转化 API，即表示您同意：据您所知，action_source 参数准确无误）
event_id：在设置去重情况下是必填项，详情请参阅“设置多渠道去重”部分。
advertiser_tracking_enabled
application_tracking_enabled
extinfo

以下是 extinfo 的示例。确保已填写以下所有子参数并按顺序对其进行排列。如有内容缺失，需使用空字符串作为占位符。

子参数名称	是否必要	数据类型	示例
extinfo version	是	string	`i2`（对于 Android 设备，版本必须为 a2；对于 iOS 设备，版本必须为 i2）
app package name	否	string	`com.facebook.sdk.samples.hellofacebook`
short version	否	string	`1.0`
long version	否	string	`1.0 long`
os version	是	string	`13.4.1`
device model name	否	string	`iPhone5,1`
locale	否	string	`En_US`
timezone abbr	否	string	`PDT`
carrier	否	string	`AT&T`
screen width	否	string	`320`
screen height	否	string	`568`
screen density	否	string	`2`
cpu core	否	string	`2`
external storage size	否	string	`13`
free space in external storage size	否	string	`8`
device time zone	否	string	`USA/New York`

c. 设置多渠道去重

需要使用去重机制来删除转化 API 集成与应用事件的所有其他现有集成（包括 SDK、MMP 和应用事件 API）之间的重复事件流量。

对应用事件，我们会应用现用于网站事件的去重功能。该功能会利用字段 event_id 和 event_name 实现去重（具有同一 event_id 的转化 API 和 SDK/应用事件 API 事件）。event_id 参数是唯一可区分相似事件的标识符。如果事件编号不准确，这可能会导致系统错误地对您的转化事件进行去重处理，进而影响转化报告和广告系列表现。

您可以参阅以下开发者文档来实现去重设置：

以下示例展示了如何记录自定义事件。如要记录此类事件，在 iOS SDK 中，请以 AppEvents.Name 的形式传递事件名称：

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

对于应用安装事件，已建立一个去重机制，来确保在过去 90 天的期限内仅为一个安装事件执行归因操作。我们会保留第一个事件，而弃用后续事件，无论后续事件来自哪个操作来源都是如此。对与安装事件相关的应用事件而言，不要求进行去重处理。

d. 发送事件

如要发送新事件，请通过以下路径向转化 API 发出 POST 请求：https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}。向此连线发出该请求时，Meta 会新建应用服务器事件。详情请参阅此处的开发者文档。

下图简要介绍了各参数如何融入负载的整体架构中：

**疑难解决**

您可以使用有效负载设置助手工具来生成有效负载数据：

在适用情况下，选择 app 操作来源
为将发送到 Meta 的事件填写相关信息
这将生成事件有效负载，该有效负载可用作用于与转化 API 集成的模板

使用事件管理工具中的“测试事件”工具进行测试。