应用事件 API

通过应用事件，您可以追踪移动应用或网页中发生的操作，例如应用安装和购买事件。通过追踪这些事件，您可以衡量广告效果以及为广告定位构建受众。

有关追踪业务消息相关 API 事件的详情，请参阅 Messenger 开放平台文档中的业务消息的应用事件 API。

运作方式

应用事件有三种类型：

• 自动记录事件 - Facebook SDK 可以自动记录应用安装、应用会话和应用内购买事件。
• 标准事件 - Facebook 为您创建的热门事件。
• 自定义事件 - 您为应用创建的特定事件。

应用事件包含 3 个部分：

1. name - 描述事件的必要字符串。当应用事件发送至分析工具时，此名称会在事件记录中显示。
2. valueToSum - 此为可选值，分析工具会将其添加至名称相同的应用事件的其他求和值中。
3. parameters - 包含在应用事件中的可选值。

不同事件名称的最大数量为 1,000。注意：达到此上限后，系统不会再记录任何新的事件类型，如果您超出此限制，就会在记录时收到 100 Invalid parameter 错误。但您可以停用废弃的事件。如需详细了解事件限制，请参阅常见问题。

前期准备

您需要提供：

• 广告主编号、Android 设备中的广告编号或 Apple 设备中的广告 ID (IDFA)
• 可供 Facebook 验证身份的应用访问口令。请勿将您的应用访问口令存储在客户端。

应用安装

从您的服务器向 /{app-id}/activities 端点发送 POST 请求，并在其中使用 application_tracking_enabled 和 advertiser_tracking_enabled 参数：

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=MOBILE_APP_INSTALL
   &application_tracking_enabled=0      
   &advertiser_tracking_enabled=0       
   &advertiser_id={advertiser-tracking-id}
   &{app-access-token}"

成功后，应用会收到以下响应：

{
  "success": true
}

注意事项

• 对于每个用户，您应该只报告一个安装事件。如有可能，请在编号和用户层级删除重复的编号。

请访问应用程序活动参考指南，获取可用参数列表。

启用广告追踪

advertiser_tracking_enabled 字段指定用户是否已在设备上启用广告追踪功能。若禁用，请将该字段设为 0；若启用，则设为 1。您应获取该数据并将其返回至 Facebook，以确定广告追踪功能是否可用于优化或转化。根据 Meta“数据政策”，Meta 将出于以下目的使用事件数据（合作伙伴提供的有关用户在 Meta 之外的活动数据），包括广告报告、欺诈检测，以及构建和改进产品（包括广告投放产品），但 Meta 也会限制使用该用户的数据，使之仅用于为该用户打造个性化广告。对于运行 iOS 6 之前版本的设备，应默认将此参数设为 1。

请访问 Apple > 广告支持参考文档，获取用户的追踪状态。

以下代码片段说明如何获取已启用追踪的标签的值。

您可以从 Settings.shared.isAdvertiserTrackingEnabled 属性中获取已启用追踪标签的当前设置。

print("isAdvertiserTrackingEnabled: \(Settings.shared.isAdvertiserTrackingEnabled)")

禁用广告追踪

任何应用程序都可以选择添加设置，以便用户在应用中关闭广告追踪功能。Facebook 要求合作伙伴在他们的 SDK 中添加此选项，并将用户的选择连同安装或转化事件一起报告给 Facebook。Facebook 会将安装或转化事件用于广告报告，但不会将其用于广告优化。每次启动应用时显示的用户设置必须保持不变。

转化事件

向 /{app-id}/activities 端点发送 POST 请求，将其中的 event 设置为 CUSTOM_APP_EVENTS，并为各单独事件设置 advertiser_tracking_enabled。advertiser_id 或 attribution 参数为必要项。

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS" 
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
       "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &{app-access-token}" 

成功后，应用会收到以下响应：

{
  "success": true
}

归因分析

attribution 端点会根据 28 天内某则广告上发生的点击操作返回安装和转化事件。广告管理工具会使用 1 天浏览和 28 天点击归因模型，根据展示或点击时间（而非安装或转化时间）显示成效分析。在将您的报告与 Facebook 广告管理工具报告进行比较时，这很重要。除了一般情况下广告点击产生的应用事件的归因确认，您还应该记住下列情况：

• 浏览归因确认 - 如果账户中心账户未在 28 天内点击广告，则设置 consider_views=TRUE 将返回展示广告的 1 天内发生的安装归因数据。返回的响应将是 is_view_through=TRUE，并会用 view_time 替换 click_time。就广告点击归因数据来说，所有其他归因都相同。

• 跨广告系列归因确认 - 广告主能够追踪引发应用事件的所有广告的效果。只要未将广告目标设置为移动应用安装量或移动应用使用率，Facebook 就会为来自广告系列的事件发送归因确认。只有在广告主已将此应用添加到其广告的“移动应用事件追踪”字段后，系统才会显示此数据。

• 用户案例 - 如果您的客户希望追踪由公共主页帖子广告或将用户引导至移动网站的网站点击广告所生成的安装事件，他们可以在广告管理工具中执行此操作，而 Facebook 将确认相关应用安装事件的归因。

• 跨设备归因确认 - 如果广告主在多个平台发布应用，则可以查看通过这些平台的广告实现的应用安装量数据。

• 用例 - 用户在 iPhone 上点击某个应用的广告，然后在其 iPad 上安装同一应用。我们便可以将 iPad 应用安装归因于 iPhone 广告，而这与广告定位无关。

高级匹配

通过高级匹配，您可以将客户数据发送到 Facebook，我们将使用这些数据更准确地确定哪些用户针对您的广告采取了行动。凭借这些数据，Facebook 可以将转化事件与您的客户进行匹配，以优化您的广告并建立更大的再营销受众。

向 /{app-id}/activities 端点发送 POST 请求，将其中的 ud 参数设置为有助于追踪客户（例如客户邮箱或手机号）的参数。所有客户数据必须经过哈希处理，否则 Facebook 将忽略相关数据。请务必为各单独事件设置 advertiser_tracking_enabled。

curl -i -X POST "https://graph.facebook.com/{app-id}/activities
   ?event=CUSTOM_APP_EVENTS
   &advertiser_id={advertiser-tracking-id}
   &advertiser_tracking_enabled=1 
   &application_tracking_enabled=1
   &custom_events=[
      {"_eventName":"fb_mobile_purchase",
      "event_id":"123456",
       "fb_content":"[
            {"id": "1234", "quantity": 2,}, 
            {"id": "5678", "quantity": 1,}
        ]",
       "fb_content_type":"product",
       "_valueToSum":21.97,
       "fb_currency":"GBP",
      }
    ]
   &ud[em]={sha256-hashed-email}
   &{app-access-token}"

成功后，应用会收到以下响应：

{
  "success": true
}

所有用户数据都必须先经过 SHA256 哈希处理，然后您才能将其发送给 Facebook。Facebook 将忽略未经哈希处理的数据。

删除重复事件

对应用事件，我们会为其应用现用于网站事件的删除重复事件功能。其逻辑利用基于 event_id 和 event_name 字段的删除重复事件功能。event_id 参数是唯一识别符，因此可以区分相似事件。如果事件编号不准确，这可能会导致系统错误地对您的转化事件执行重复事件删除，进而影响转化报告和广告系列表现。

扩展设备信息

在应用事件调用中使用 /{app-id}/activities?extinfo 发送设备信息，例如屏幕宽度和高度。不同值之间用逗号分隔，并且必须采用 /application/activites 参考指南中说明的索引顺序。当使用 extinfo 时，所有值均为必要项。

• 对于 Android，version 必须为 a2
• 对于 iOS，version 必须为 i2

参考文档

• 应用程序活动参数
• Android 开发者文档 - 显示屏指标
• Android 开发者文档 - 外部存储空间
• Apple 开发者文档 - 显示屏指标
• Apple 开发者文档 - 外部存储空间
• Apple 开发者文档 - 屏幕尺寸

获取移动 Cookie

我们建议您关联应用事件与 advertiser_id。但对于 Android 设备和系统低于 iOS 6 的 iOS 设备而言，您还可以使用已设置为设备移动 Cookie 的 attribution 参数。

注意：移动 Cookie 并非通过任何用户或设备属性检索而来。这些 Cookie 并非恒久不变，而是会时常更新。请勿为再营销广告使用移动 Cookie。

Android

Cookie 是包含 22 个字母数字字符的随机字符串。

使用 ContentProvider 获取 Facebook 归因分析编号：

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

您还应该获取自己 Android 应用的广告编号。

iOS

移动 Cookie 由 iOS 版 Facebook 应用使用 CFUUIDCreateString 创建，并以 128 位 UUID 字符串表示。

获取 Cookie 编号和 IDFA，并将二者作为身份识别信息发送给 Facebook：

ASIdentifierManager *manager = [ASIdentifierManager sharedManager];
NSString *advertiserID = [[manager advertisingIdentifier] UUIDString];

if (advertiserID) {
  // do stuff
}

X-Forwarded-For HTTP 标头

如果 POST 请求是通过中心位置（服务器或代理）发起（即服务器到服务器调用），则必须使用 X-Forwarded-For HTTP 标头来确保位置和设备信息准确。通过您发送的每个应用事件请求中的 X-Forwarded-For HTTP 标头参数发送设备的 IP 地址，格式为 IPv4 或 IPv6。通过这种方法，我们可以将 advertiser_id 配对到正确的 IP 地址，然后可将此地址用在我们的平台中。

IPv6 示例

curl ...
  -H "X-Forwarded-For: fd45:f238:3b40:23b1:ffff:ffff:ffff:abcd" \
  https://graph.facebook.com/<APP_ID>/activities/

IPv4 示例

curl ...
  -H "X-Forwarded-For: 192.168.0.99" \
  https://graph.facebook.com/<APP_ID>/activities

测试

1. 前往事件管理工具。
2. 点击页面左侧的“数据源”图标。
3. 选择数据名称和编号。
4. 点击“测试事件”，并选择“应用”作为渠道。
5. 使用图谱 API 探索工具发送 AE-API 请求。
6. 您的互动很快就会出现在“测试事件”选项卡中。

差异

如果客户对比移动应用成效衡量合作伙伴的报告与 Facebook 报告并发现存在差异，以下是要检查的一些项目：

如果 Facebook 报告的安装次数少于 MMP：

• 是否正确整合了 Facebook SDK？
• 客户是否正在使用错误的应用编号？

如果 Facebook 报告的安装次数多于 MMP：

• 归因分析时间范围是否相同？一般而言，Facebook 的归因分析时间范围比大多数移动成效衡量合作伙伴更长。
• 是否正确集成了 MMP SDK？
• 客户使用的应用编号是否正确？
• 差异是否仅限于 iOS7？MMP 是否正在从设备上接收 Apple 的广告 ID (IDFA) 并将其正确地传递给 Facebook？

参考文档

应用程序活动扩展信息

如需详细了解应用扩展信息，请访问 /application/activites 参考指南。

用户数据参数

标准事件名称

标准事件参数

另请参阅

• 应用事件
• 应用事件最佳实践
• 处理错误
• 通用数据保护条例合规要求
• Facebook 广告管理工具
• Facebook 应用面板