一、集成方案介紹
本文將介紹如何通過Facebook Ads Insight API把Facebook廣告數據拉回至自己的本地服務。本方案支持：
將 Facebook 消耗、點擊、展示和激活等基礎報表指標的聚合數據實時 (按小時) 回傳至本地服務器，並按照 Facebook 中各廣告賬號、廣告計劃、廣告組和素材維度分組。
！注意，拉取 Facebook Ads API 數據需要您的服務器在中國大陸以外的地區配置代理
流程
- 登錄 Meta for Developers 後臺，創建 Business App
- 生成 Access-Token
- 獲取 Access-Token，以及需要拉取數據的廣告賬戶 ID 列表
- 確定數據拉取的維度以及拉取的頻率、拉取頻率以及拉取時間範圍
- 完成數據拉取開發工作
- 搭建看板、報表，並完成數據驗收
二、集成前準備工作
2.1創建業務應用
登錄 Meta for Developers 後臺，點擊「Create App」創建應用
選擇「Business」，並點擊「Next」繼續
接下來配置好項目顯示名，點擊「Create app」完成 App 的創建
2.2 獲取 Access Token
選擇您剛剛創建的應用，在「Dashboard」標籤頁配置 Marketing API
接下來，您需要確認您想要拉取數據的廣告賬號的 Facebook 賬號，是否和當前創建 Business App 的 Facebook 賬號是同一個。請根據您的實際情況，選取對應的創建方式生成 Access Token。
1. 如果廣告賬號和 Business App 同屬於一個 Facebook 賬號
- 登錄 https://business.facebook.com，進入「賬戶」-「應用」，添加一個新的應用。並在「添加資產」中，將需要同步數據的廣告賬號加入到該應用的資產中。另外，如果您已經創建了系統用戶，則可以點擊「添加用戶」，向該系統用戶授權本應用。
- 如果您沒有創建系統用戶，則進入「用戶」-「系統用戶」，添加一個新的系統用戶，並通過「添加資產」，爲該系統用戶添加上一步創建的應用。
- 點擊「生成新口令」，選擇之前創建的應用，並在「可用權限」中勾選 read_insights 與 ads_read 權限，創建口令並生成 access token 。
2. 如果廣告賬號和 Business App 的 Facebook 賬號不同
如果您的廣告賬號的 Facebook 賬號和 Developer 的 Facebook 賬號不是同一個，則您需要按照以上流程獲取 Access Token後，再進行如下配置：
- 使用 Developer 的 Facebook 賬號登錄 https://business.facebook.com，進入「業務設置」-「用戶」-「個人用戶」模塊，確認可看到相應賬戶下資產，即先前創建的應用
- 點擊「業務設置」-「用戶」-「合作伙伴」，點擊「向其申請資產訪問權限的合作伙伴」處的「添加」按鈕，關聯已有廣告賬戶的 Facebook 賬號。登錄廣告賬戶的 Facebook 賬號並完成授權，即可獲取該賬號下的廣告賬戶的訪問權限
- 按照“1. 如果廣告賬號和 Business App 同屬於一個 Facebook 賬號”的方法，創建系統用戶併爲資產中添加剛剛完成授權的廣告賬戶，並將需要拉取的廣告賬號授權給該系統用戶（下圖紅框）。接着，點擊「生成新口令」，創建具有 read_insights 與 ads_read 權限的 access token。
三、數據拉取
| 接口名 | API 類型 | 產品化 | 數據粒度 | 歸因數據 | 成本數據 | 收益數據 | 展示數據 | 點擊數據 | 轉化數據 |
|---|---|---|---|---|---|---|---|---|---|
| 洞察 API | 拉式 | 否 | 聚合數據 | 是 | 是 | 是 | 是 |
Ads Insights API 是獲取 Facebook 廣告數據的 API，可以提供多種粒度的廣告聚合指標數據。
1. 涵蓋字段
以下列舉的是 Ads Insights API 提供的部分字段，如需瞭解全量字段，可以訪問官方文檔：
- 指標字段
| 指標名 | 入庫名 | 含義 | 是否默認 |
|---|---|---|---|
| 花費 | amount_spent_usd | 總花費金額 | 是 |
| 點擊次數 | clicks_all | 總點擊數 | 是 |
| 行動 | 會返回多個字段，包含以下行爲數據： - 移動應用購買 - 移動應用購買轉化價值 - 移動應用安裝 - 移動應用會話 - 移動應用註冊完成 - 移動應用級別已完成 - 移動應用自定義事件 - 3秒視頻播放 - 應用激活 - 達到的水平 - 自定義活動 - 頁面參與度 - 訂婚後 - 鏈接點擊次數 - 帖子保存 - 後反應 - 發表評論 - 發佈股票 | 應用內的行爲與值 | |
| action_values | 會返回多個字段，包含以下行爲數據： - 移動應用購買 - 移動應用購買轉化價值 - 移動應用安裝 - 移動應用會話 - 移動應用註冊完成 - 移動應用級別已完成 - 移動應用自定義事件 - 3秒視頻播放 - 應用激活 - 達到的水平 - 自定義活動 - 頁面參與度 - 訂婚後 - 鏈接點擊次數 - 帖子保存 - 後反應 - 發表評論 - 發佈股票 | 應用內的行爲與值 | |
| 轉化 | 轉化 | 轉化數 | |
| conversion_values | conversion_values | 轉化值 | |
| conversion_rate_ranking | conversion_rate_ranking | 轉化率評級 | |
| converted_product_quantity | converted_product_quantity converted_product_quantity_1d_view converted_product_quantity_7d_click | 購買商品轉化數 購買商品轉化數（1日瀏覽歸因窗口期） 購買商品轉化數（7日點擊歸因窗口期） | |
| converted_product_value | converted_product_value converted_product_value_1d_view converted_product_value_7d_click | 購買商品轉化金額 購買商品轉化金額（1日瀏覽歸因窗口期） 購買商品轉化金額（1日瀏覽歸因窗口期） | |
| 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 cost_per_thruplay_7_days_after_clicking_usd cost_per_thruplay_usd | 每次 Thruplay 播放平均花費（1日瀏覽歸因窗口期） 每次 Thruplay 播放平均花費（7日點擊歸因窗口期） 每次 Thruplay 播放平均花費 | |
| cost_per_unique_click | cost_per_unique_click_all_usd | 每次獨立點擊平均花費 | |
| cost_per_unique_inline_link_click | cost_per_unique_inline_link_click_usd | 每次獨立站內點擊平均花費 |
- 維度字段
| 指標名 | 入庫名 | 含義 | 是否默認 |
|---|---|---|---|
| campaign_id | campaign_id | 競選 ID | 是 |
| campaign_name | campaign_name | Campaign 名稱 | 是 |
| adset_id | ad_set_id | 廣告集 ID | 是 |
| adset_name | ad_set_name | Ad Set 名稱 | 是 |
| ad_id | ad_id | 廣告 ID | 是 |
| ad_name | ad_name | Ad 名稱 | 是 |
| account_id | account_id | 廣告賬號 ID | 是 |
| account_name | account_name | 廣告賬號名 | 是 |
| account_currency | 貨幣 | 貨幣種類 | 是 |
| 客觀 | 客觀 | 投放目的 | |
| optimization_goal | optimization_goal | 優化目標 | |
| attribution_setting | attribution_setting | 歸因設置 | |
| buying_type | buying_type | 廣告支出形式 |
2. 分析粒度
目前支持從以下 5 個粒度拉取數據，請從中選擇您需要接入的數據粒度：
| 粒度名 | 時間粒度 | 分組 | 層級 | 事件名 |
|---|---|---|---|---|
| 小時 | 按小時 | -- | 廣告層級 | facebook_ad_level_data_by_hour |
| 國家 | 按天 | 按國家（地區）聚合 | 廣告層級 | facebook_ad_level_data_by_country |
| 年齡 | 按天 | 按年齡、性別 | 廣告層級 | facebook_ad_level_data_by_age_gender |
| 小時廣告 不建議使用 | 按小時 | -- | 廣告賬號層級 | facebook_account_level_by_hour |
| 平臺 | 按天 | 按版位 | 廣告層級 | facebook_ad_level_data_by_platform |
hourAd 粒度數據的指標字段與 hour 粒度數據一致，但維度字段要更少，即不包含 campaign、ad set 與 ad 維度字段，因此不建議新增接入該粒度數據
3. 接口參數
時間：可以拉取以天爲單位的數據，單次拉取的時段不能超過30天
4. 入庫規則
- 由於 Ads Insights API 返回的是聚合數據，因此我們將使用一個固定值作爲其用戶標識，您可以認爲所有數據掛載在一個虛擬用戶上
- 使用數據中的 date 字段，即數據的日期，設置爲聚合數據的 #event_time
- 數據的事件名由所選的分析粒度決定
- 指標字段將以數值類型入庫，其餘字段將以字符串入庫
四、信息收集模版
数据接口： Facebook Ads Insights API
---------
数据接收地址 push_url: XXX
---------
Facebook Ads 广告账户ID (act_<ACCOUNT_ID>)列表：XXX
Facebook Ads Access Token ：XXX
拉取字段筛选（可选）：XXX（从拉取字段筛选章节筛选字段）
字段映射配置文件（可选）：XXX（CSV文件对入库事件属性名称进行自定义）
---------
历史数据拉取：
第一次拉取，拉取过去 30 天按小时的数据
历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd（仅支持拉取近 90 天的数据）
需要拉取的字段：XXX，XXX
定时拉取：每天 X 点拉取前一天的数据
