Meta（Facebook）Ads 集成方案
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
概要
接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Insights API | API | 聚合指标 | ✅ | ✅ | ✅ | ✅ |
Meta（即 Facebook）提供了广告数据拉取接口 Facebook Ads Insights API，该接口支持获取您在 Meta 上投放广告的消耗、点击、展示和激活等基础报表指标情况
集成流程
- 登录 Meta for Developers 后台，创建 Business App
- 生成 Access-Token
- 登录 AE 后台，进入三方集成模块，新增 Meta (Facebook) Insights API 方案，并完成相关配置
- 查看 AE 系统是否成功接收数据，并完成报表搭建
注意，拉取 Facebook Ads API 数据需要您的服务器在海外或配置代理。
一、创建应用并获得授权信息
1.1 创建 Business App
首先，您需要登录 Meta for Developers 后台，点击「Create App」创建应用
接着，在 Create an app 页面输入应用名称以及联系邮箱后，点击「Next」继续
在 Use case 页，选择「Other」，并点击「Next」继续
在 Select an app type 页，选择「Business」，并点击「Next」继续
接下来最终确认应用的配置信息后，点击「Create app」完成 App 的创建
1.2 获取 Access Token
完成应用创建后，接下来您需要获取 Access Token。选择您刚刚创建的应用，在「Dashboard」标签页配置 Marketing API
接下来，您需要确认您想要拉取数据的广告账号的 Facebook 账号，是否和当前创建 Business App 的 Facebook 账号是同一个。请根据您的实际情况，选取对应的创建方式生成 Access Token。
1.2.1 如果广告账号和 Business App 同属于一个 Facebook 账号
- 登录 https://business.facebook.com，进入「账户」-「应用」，添加一个新的应用。并在「添加资产」中，将需要同步数据的广告账号加入到该应用的资产中。另外，如果您已经创建了系统用户，则可以点击「添加用户」，向该系统用户授权本应用。
- 如果您没有创建系统用户，则进入「用户」-「系统用户」，添加一个新的系统用户，并通过「添加资产」，为该系统用户添加上一步创建的应用。
- 点击「生成新口令」，选择之前创建的应用，并在「可用权限」中勾选 read_insights 与 ads_read 权限，创建口令即 access token
1.2.2 如果广告账号和 Business App 的 Facebook 账号不同
如果您的广告账号的 Facebook 账号和 Developer 的 Facebook 账号不是同一个，则您需要按照以上流程获取 Access Token后，再进行如下配置：
- 使用 Developer 的 Facebook 账号登录 https://business.facebook.com，进入「业务设置」-「用户」-「个人用户」模块，确认可看到相应账户下资产，即先前创建的应用
- 点击「业务设置」-「用户」-「合作伙伴」，点击「向其申请资产访问权限的合作伙伴」处的「添加」按钮，关联已有广告账户的 Facebook 账号。登录广告账户的 Facebook 账号并完成授权，即可获取该账号下的广告账户的访问权限
- 按照 1.2.1 的方法，创建系统用户并为资产中添加刚刚完成授权的广告账户，并将需要拉取的广告账号授权给该系统用户（下图红框）。接着，点击「生成新口令」，创建具有 read_insights 与 ads_read 权限的 access token
二、方案配置
当您完成了 Meta 平台的准备工作后，您可以登录 AE 系统，在「三方集成」模块中完成新方案的配置。下图是 Meta（Facebook）Insights API 的配置界面，请您按照本章节内容完成方案的创建
2.1 授权信息配置
点击「授权信息」下的「配置授权信息」按钮，在弹出框内填写您在上一步中获得的信息：
其中：
- Ads account ID List：您需要拉取数据的广告账号 ID，一般以 act_ 开头，多个账号之间用逗号','分割
- Access Token：您在上一节中获得的 Access Token
2.2 定时拉取
您可以在「定时拉取」模块设置 AE 系统定时拉取 Meta Insights API 数据的策略，可以选择在每天的某时拉取一段时间的数据，单次最多拉取 31 天。由于拉取的数据也会计入数据量，建议不要定时拉取太长时间的数据
2.3 入库设置
您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。
2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的时间聚合粒度、拉取的指标字段与维度、入库后的事件名，以及自定义 reportType 和 Facebook breakdown、自定义 reportType 和 报表事件的映射关系等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping | 入库后的事件名，可以自定义，JSON 类型。Key 对应 source.report_types，Value 为该类型数据的入库事件名 （有自定义 report_type 时，还需要配置自定义 report_type 和事件的映射关系） |
| source | report_types | 拉取的数据类型，列表类型。但只建议您填入一个元素，即一次只拉取一个报表的数据。内置支持 country、hour、hourAd、age、platform。 如需扩展其他 Facebook breakdown 维度，可在 extra_params.report_breakdown_map 中配置自定义 reportType，并在此处填入对应 key。 |
| metrics | 数据中的指标，列表类型，不同的数据类型支持不同的 metrics，填写时需要注意 | |
| group_by | 数据中的分组维度，列表类型，不同的数据类型支持不同的 group_by，填写时需要注意 | |
| transfer | double_columns | 会被转成数值类型的字段，一般对应指标字段的入库字段名 |
| extra_params | report_breakdown_map | 自定义 reportType 与 Facebook API 参数的映射关系。Key 为 reportType，Value 包含 level 和 breakdowns。 |
如果需要调整，则建议您先确定 source.report_types，即拉取数据的类型
目前 AE 系统支持以下 5 种数据类型，不同的数据类型的粒度不同，分析维度也不同：
| 数据类型 | 默认 | 时间粒度 | 分组 | 最细广告层级 |
|---|---|---|---|---|
| hour | 按小时 | - | 广告层级 | |
| country | 按天 | 按国家（地区）聚合 | 广告层级 | |
| age | 按天 | 按年龄、性别 | 广告层级 | |
不建议使用 | 按小时 | - | 广告账号层级 | |
| platform | 是 | 按天 | 按版位 | 广告层级 |
hourAd 粒度数据的指标字段与 hour 粒度数据一致，但维度字段要更少，即不包含 campaign、ad set 与 ad 维度字段，因此不建议新增接入该粒度数据
除以上内置数据类型外，也支持通过 extra_params.report_breakdown_map 扩展自定义 reportType。
- 指标字段
指标字段对应配置中的 source.metrics，默认情况下我们只会拉取部分常用指标，以下列举的是 Ads Insights API 提供的部分字段，如需了解全量字段，可以访问官方文档。如需调整请将需要指标的指标名写入 source.metrics 中
| 指标名 | 入库名 | 含义 | 是否默认 |
|---|---|---|---|
| spend | amount_spent_usd | 总花费金额 | 是 |
| clicks | clicks_all | 总点击数 | 是 |
actions | 会返回多个字段，包含以下行为数据：
| 应用内的行为与值 | 是 |
action_values | |||
| conversion_values | conversion_values | 转化值 | 是 |
| conversion_rate_ranking | conversion_rate_ranking | 转化率评级 | |
converted_product_quantity | converted_product_quantity | 购买商品转化数 | |
| converted_product_quantity_1d_view | 购买商品转化数（1日浏览归因窗口期） | ||
| converted_product_quantity_7d_click | 购买商品转化数（7日点击归因窗口期） | ||
converted_product_value | converted_product_value | 购买商品转化金额 | |
| converted_product_value_1d_view | 购买商品转化金额（1日浏览归因窗口期） | ||
| converted_product_value_7d_click | 购买商品转化金额（7日点击归因窗口期） | ||
| cpp | cost_per_1_000_people_reached_usd | 千人触达平均花费 | 是 |
| cost_per_estimated_ad_recallers | cost_per_estimated_ad_recall_lift_people_usd | 每次广告回想平均花费 | |
| cost_per_inline_link_click | cost_per_inline_link_click_usd | 每次站内点击平均花费 *注：站内意为点击后用户仍在 Facebook 旗下产品中，下同 | |
cost_per_inline_post_engagement | cost_per_inline_post_engagement_usd | 每次贴文互动（Post Engagement）平均花费 | |
| cost_per_outbound_click | cost_per_outbound_click_usd | 每次站外点击平均花费 *注：站外意为点击后用户跳转到 Facebook 旗下产品外，下同 | |
cost_per_thruplay | cost_per_thruplay_1_day_after_viewing_usd | 每次 Thruplay 播放平均花费（1日浏览归因窗口期） | |
| cost_per_thruplay_7_days_after_clicking_usd | 每次 Thruplay 播放平均花费（7日点击归因窗口期） | ||
| cost_per_thruplay_usd | 每次 Thruplay 播放平均花费 | ||
| cost_per_unique_click | cost_per_unique_click_all_usd | 每次独立点击平均花费 | |
| cost_per_unique_inline_link_click | cost_per_unique_inline_link_click_usd | 每次独立站内点击平均花费 | |
| cost_per_unique_outbound_click | cost_per_unique_outbound_click_usd | 每次独立站外点击平均花费 | |
| cpc | cpc_all_usd | CPC | 是 |
| cpm | cpm_cost_per_1_000_impressions_usd | CPM | 是 |
| ctr | ctr_all | 总点击率 | 是 |
| ctr_link_click_through_rate | 链接点击率 | 是 | |
| engagement_rate_ranking | engagement_rate_ranking | 活动情况评级 | |
| estimated_ad_recallers | estimated_ad_recall_lift_people | 预估广告回想人数 | |
| estimated_ad_recall_rate | estimated_ad_recall_lift_rate | 预估广告回想率 | |
| frequency | frequency | 平均观看次数 | 是 |
| impressions | impressions | 曝光数 | 是 |
| inline_link_clicks | inline_link_clicks_in_ad | 站内点击数 | |
| inline_link_click_ctr | inline_link_ctr_usd | 站内点击率 | |
| inline_post_engagement | inline_post_engagement_in_ad | 贴文互动次数 | |
| instant_experience_clicks_to_open | instant_experience_clicks_to_open | 即时体验广告的点击数 | |
| instant_experience_clicks_to_start | instant_experience_clicks_to_start | 即时体验广告的启动数 | |
| canvas_avg_view_percent | instant_experience_view_percentage | 即时体验广告的曝光率 | |
| canvas_avg_view_time | instant_experience_view_time | 即时体验广告的平均体验时长 | |
| outbound_clicks | outbound_clicks | 站外点击数 | |
| outbound_clicks_ctr | outbound_ctr_click_through_rate | 站外点击率 | |
| quality_ranking | quality_ranking | 质量评级 | |
| reach | reach | 触达数 | 是 |
video_avg_time_watched_actions | video_average_play_time | 视频平均播放时长 | |
| video_average_play_time_1_day_after_viewing | 视频平均播放时长（1日浏览归因窗口期） | ||
| video_average_play_time_7_days_after_clicking | 视频平均播放时长（7日点击归因窗口期） | ||
| video_average_play_time_on_ad | 视频平均播放时长（仅广告） | ||
| video_play_curve_actions | video_play_curve_actions | 视频播放时长曲线分区 | |
video_play_actions | video_plays | 视频播放数 | |
| video_plays_1_day_after_viewing | 视频播放数（1日浏览归因窗口期） | ||
| video_plays_7_days_after_clicking | 视频播放数（7日点击归因窗口期） | ||
| video_p100_watched_actions | video_plays_at_100 | 视频完播率 | |
| video_p25_watched_actions | video_plays_at_25 | 视频25%播放率 | |
| video_p50_watched_actions | video_plays_at_50 | 视频50%播放率 | |
| video_p75_watched_actions | video_plays_at_75 | 视频75%播放率 | |
| video_p95_watched_actions | video_plays_at_95 | 视频95%播放率 | |
| website_ctr | website_ctr | 网页点击率 |
- 维度字段
维度字段对应配置中的 source.group_by，但需要注意，数据报表类型即 source.report_types 决定了计算时的分析粒度，而维度字段只能决定这些字段是否展示，所以部分维度在一些数据报表类型下不可用。如需调整，请将需要维度的维度名写入 source.group_by 中
| 维度名 | 入库名 | 含义 | 是否默认 |
|---|---|---|---|
| campaign_id | campaign_id | Campaign ID | 是 |
| campaign_name | campaign_name | Campaign 名称 | 是 |
| adset_id | ad_set_id | Ad Set ID | 是 |
| adset_name | ad_set_name | Ad Set 名称 | 是 |
| ad_id | ad_id | Ad ID | 是 |
| ad_name | ad_name | Ad 名称 | 是 |
| account_id | account_id | 广告账号 ID | 是 |
| account_name | account_name | 广告账号名 | 是 |
| account_currency | currency | 货币种类 | 是 |
| objective | objective | 投放目的 | |
| optimization_goal | optimization_goal | 优化目标 | |
| attribution_setting | attribution_setting | 归因设置 | |
| buying_type | buying_type | 广告支出形式 |
2.5 事件入库规则
-
使用数据中的 date 字段，即数据的日期，设置为聚合数据的 #event_time
-
不同数据报表类型的事件名分别为：
- country： facebook_ad_level_data_by_country
- hour：facebook_ad_level_data_by_hour
- hourAd：facebook_account_level_by_hour
- age：facebook_ad_level_data_by_age_gender
- platform：facebook_ad_level_data_by_platform
-
指标字段将以数值类型入库，其余字段将以字符串入库
如果使用自定义 reportType，则事件名由 sink_event.event_mapping 中对应 reportType 的配置决定。例如 device 可配置为 facebook_ad_level_data_by_device。
2.6 标准化字段
| 原始字段 | 标准化字段 | 含义 |
|---|---|---|
| account_id | te_ads_object.ad_account_id | 广告账号 ID |
| campaign_name | te_ads_object.campaign_name | 广告计划名 |
| campaign_id | te_ads_object.campaign_id | 广告计划 ID |
| adset_name | te_ads_object.ad_group_name | 广告组名 |
| adset_id | te_ads_object.ad_group_id | 广告组 ID |
| ad_name | te_ads_object.ad_name | 广告名 |
| ad_id | te_ads_object.ad_id | 广告 ID |
| account_currency | te_ads_object.currency | 成本或收益的币种 |
| impressions | te_ads_object.impressions | 曝光量 |
| clicks_all | te_ads_object.clicks | 点击量 |
| amount_spent_usd | te_ads_object.cost | 买量成本 |