Facebook Business 擴充功能(FBE)幫助您的用戶輕鬆上傳廣告創意素材,只要連上新的或既有的企業管理平台,就能在整個 Meta 系列應用程式使用上傳功能。合作夥伴使用完成這項流程後傳回的企業管理平台,就能代表顧客將廣告創意素材傳送到 Facebook:
本文件概述 FBE 廣告創意流程的主要先決條件,並大致介紹完成這項流程的必經步驟。請參閱 Facebook Business 擴充功能指南,瞭解關於整個整合功能的具體詳細資訊。
範例 — 使用合作夥伴介面(商家登入)的啟用流程
註冊成為 Facebook 開發人員,以利使用我們的開發人員工具以及建立 Facebook 應用程式。
若您尚未建立 Meta 應用程式,請先行建立。
您的 Meta 應用程式必須屬於通過驗證之商家的企業管理平台。深入瞭解如何驗證商家。
建立一個測試版應用程式,再以這個應用程式執行所有新的開發與測試。請務必為測試應用程式指派其他企業管理平台。
不公開權限/功能:
manage_business_extension
- Facebook Business 擴充功能存取權限。待我們開放您的應用程式使用這項功能後,您可以在產品之下找到 FBE 開發人員面板。
Business_creative_asset_management
- 廣告創意相關素材管理 API 存取權限。獲得此功能授權後,您可以存取下列權限:
business_creative_insights
:閱覽使用企業創意廣告素材洞察報告。
business_creative_management
:允許您的應用程式建立、編輯與分享新資料夾,以及上傳素材到這些內容中,在您自己的事業體範圍內運用。
business_creative_insights_share
(開發中):適用於資料夾分享流程的非必要權限。如用戶同意授權,您的應用程式就能將廣告創意資料夾分享給其他商家,也能開放這些商家查看廣告創意素材洞察報告。
產生合作夥伴存取權杖:
按照這些操作說明,在您的企業管理平台之下產生管理員系統用戶存取權杖。
一定要在「適用範圍」中選擇這個權杖的 business_creative_insights
、business_creative_management
以及 business_management
權限。
這個按鈕的用途是在您的應用程式傳送素材到用戶的 Facebook 媒體中心資料庫。進行這項流程時,您的應用程式需允許用戶選擇要將素材傳送到哪一個資料夾,或者允許用戶建立一個這樣的資料夾。
我們建議以下兩種方法:
1. (最低限度)用戶只有選擇或建立最上層資料夾這個選項。按照選定的商家背景資料,查詢用戶有權存取的所有最上層資料夾。請用戶選擇一個既有的上層資料夾,或者建立一個新資料夾。用戶可以指定資料夾名稱,也可以使用預設資料夾名稱 <YourBusinessName>_<UserBusinessName>_<UserName>
。將素材上傳到選定的或新的最上層資料夾。這個方法需要盡量減少用戶介面工作和 API,詳情請參閱下方步驟 3。
2. (非必要)用戶可以掌握完整的資料夾及子資料夾導覽控制權。按照選定的商家背景資料,查詢用戶有權存取的所有最上層資料夾,並且請用戶選擇一個既有的上層資料夾,或者建立一個新資料夾。若是新資料夾,可以請用戶替資料夾命名,或者使用預設名稱 <YourBusinessName>_<UserBusinessName>_<UserName>
。在所選的最上層資料夾之下,用戶可以選擇瀏覽既有的子資料夾、建立新的子資料夾,或者是上傳素材。若選擇這個選項,需在您的用戶介面中實作資料夾導覽功能。如需 API 整合操作說明,請參閱下方步驟 3 及步驟 4。
實作這項流程的具體步驟如下所示:
用戶第一次傳送廣告創意素材到 Facebook 時,您需以存取權杖的形式提示 Facebook Business 擴充功能,要求用戶進行驗證並同意將必要權限授予您的應用程式,才能存取用戶在 Facebook 的素材。請參閱 Facebook Business 擴充功能:新手指南,在您的應用程式中實作 Facebook Business 擴充功能。按照企業應用程式指南中的教學,啟用應用程式在企業應用程式中的介面。
提示啟用廣告創意流程:
business_creative_management
和 business_creative_insights
權限
business_creative_insights_share
權限
VIEW_INSIGHTS
任務權限只要您使用這項提示傳回的用戶存取權杖,就能代表用戶發出 API 呼叫。
欄位 | 類型 | 說明 |
---|---|---|
| 設定 | 必填 賣家的 Facebook 設定,例如其不重複的識別資料( |
| business_config | 必填 Facebook Business 擴充功能用於設定 Facebook Business 擴充功能工作流程的設定物件。請參閱 |
| 布林值 | 必填 將這個值設為 |
使用這個物件定義一般用戶的 Facebook 身分設定
欄位 | 說明 |
---|---|
| 必填。 |
| 必填。 |
| 必填。 |
| 必填。 |
| 必填。
|
| 選填。 |
使用這個物件設定一般用戶的商家設定。包括 CTA、服務小卡片等等。每個欄位各包含一個連結至以下各表格的「類型」。
欄位 | 說明 |
---|---|
| 必填。 |
使用這個物件設定商家名稱。
欄位 | 說明 |
---|---|
| 必填。 |
用戶完成上述的 FBE 啟用流程後,您會收到該用戶的企業管理平台編號及存取權杖,發出來源會是 FBE 安裝 API 或 Webhook 通知其中之一。
用戶可以上傳素材到最上層資料夾,也可以在最上層資料夾之下建立子資料夾。
首先確認用戶有哪些最上層資料夾的權限,可以用於 CREATE_CONTENT
任務,確認方法是對 <business_id>/creative_folders
端點(開發中)發出一項要求。
要求
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<user_business_id>/creative_folders?filtering=[{field:"permitted_tasks", operator: "EQUAL", value:"create_content"}]
回應
{ "id": "<folder_id>" }
請用戶按照其企業管理平台的背景資料選擇一個既有的最上層資料夾,或者建立一個新的最上層資料夾。若是新的上層資料夾,可以請用戶替資料夾命名,或者使用預設的 <YourBusinessName>_<UserBusinessName>_<UserName>
。若用戶將該資料夾分享給您,則您的商家和用戶的商家都能在 Facebook 素材資料庫中看見該資料夾。
備註:要取得用戶的商家名稱,可以對 {business-id}
端點發出一項 GET
要求,其中的 {business-id}
是用戶的商家編號。
要求
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>
回應
{ "id": {business-id} "name": {user-business-name} }
要求
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
回應
{ "id": {top-level-folder-id} }
若要支援完整的資料夾導覽流程,可以請用戶在最上層資料夾之下選擇一個既有的子資料夾,或者建立一個新的子資料夾,此時可以使用的要求如下:
business_creative_management
權限要求
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<parent_folder_id>/subfolders?fields=name
回應
{ "data": [ { "name": "<subfolder_name>", "id": "<subfolder_id>" } ] }
business_creative_management
權限要求
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F "parent_folder_id={parent-folder-id}" -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
回應
{ "id": {sub-folder-id} }
若要刪除資料夾和子資料夾,請傳送一項 DELETE
要求至 <folder_id>
或 <subfolder_id>
端點。
上傳用戶的廣告創意素材到子資料夾。
business_creative_management
權限要求
curl -X POST \ -F 'bytes={image-content-in-bytes-format}' \ -F 'name={image-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ https://graph.facebook.com/{version}/{business-id}/images
回應
{ "images":{ "{image-name}":{ "id":"{business-creative-image-id}", "hash":"{hash}", "url":"{image-url}" } } }
若影片大小不超過數 MB,請使用單一要求上傳影片,否則請分段上傳(請見下方的次節內容)。請在 graph-video.facebook.com
發出上傳影片的 API 呼叫,而不要在 graph.facebook.com
發出。
範例 — 傳送 POST
到 {business-id}/video
,並且註明影片的名稱、出處以及子資料夾編號。
要求
curl -X POST \ -F 'name={video-name}' \ -F 'source='@{video-path}'' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ https://graph-video.facebook.com/{version}/{business-id}/videos
回應
{ "success": true, "business_video_id": "<business_video_id>" }
若影片較大,請傳送一項開始要求、一項或多項傳輸要求,以及一項結束要求。
要發出開始要求並建立一個影片上傳連線階段,請傳送一項 POST
要求到 /{business-id}/videos
、將 upload_phase
欄位設為開始,再以位元組為單位指定 file_size
要求
curl -X POST \ -F 'title={video-name}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'access_token={user-access-token}' \ -F 'upload_phase=start' \ -F 'file_size={video_file_size_in_bytes}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
回應
{ "upload_session_id": "{session-id}", "video_id": "{video-id}", "start_offset": "0", "end_offset": "52428800" }
要上傳影片的 [0, 52428800],請按照開始和結束位移點將檔案分段,然後使用傳輸要求傳送這些片段。每一個片段,我們會分別傳送一個新的位移點給您 -- 請使用這些新位移點上傳每個片段。
範例:傳送第一個片段
要求
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'upload_phase=transfer' \ -F 'upload_session_id={session-id}' \ -F 'start_offset=0' \ -F 'video_file_chunk=@{binary-chunk-filename}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
回應
成功之後,我們會發出回應,也就是下一個片段的位移點
{ "start_offset": "52428800", //Start byte position of the next file chunk "end_offset": "104857601" //End byte position of the next file chunk }
按照 [52428800, 104857601] 這個範圍,從檔案中剪出並上傳第二個片段,並且傳送片段:
要求
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'upload_phase=transfer' \ -F 'start_offset=52428801' \ -F 'upload_session_id={your-upload-sesson-id}' \ -F 'video_file_chunk={binary-chunk-filename}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
回應
傳送所有其他片段,一直到 start_offset
等於 end_offset
為止:
{ "start_offset": "152043520", "end_offset": "152043520" }
以上回應表示您已經上傳了整個檔案。現在您需要發佈這個檔案,並且關閉上傳聯線階段。
要求
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={business-creative-folder-id}' \ -F 'upload_phase=finish' \ -F 'upload_session_id={session-id}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
如果上傳過程中出現錯誤,您可以重試上傳該片段。錯誤通常是回應問題所造成。請試著重新上傳無法上傳的片段。如需錯誤的詳細資訊,請參閱:
您的應用程式應會向用戶發出上傳成功通知,並且在「到我的 Facebook 素材資料庫查看廣告創意」行動呼籲中嵌入一個這項廣告創意的深層連結。資料夾或素材的深層連結是:
https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id}
(開發中)
若用戶有多個企業管理平台,這個連結會將用戶導向商家選擇頁。要避免容易混淆商家的問題,可以在網址中提供商家背景資料,如下所示:
https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id}&business_id={client_business_id}
要取得深層連結網址,也可以在端點上發出 GET
要求:
curl -X GET \ /<folder_id or asset_id> ?fields=['media_library_url'] &access_token=<user_access_token>
這個連結可以讓用戶直接從 Facebook 素材資料庫中找到資料夾或素材。
如果您想要管理最上層資料夾或查看素材洞察報告,可以要求與您分享最上層資料夾。請傳送一項 POST
要求到:{business-creative-folder-id}/agencies
,並且替 CREATE_CONTENT
指派 permitted_tasks
。
備註:您也可以指派 VIEW_INSIGHTS
允許的任務,前提是用戶同意將 business_creative_insights_share
授予您的應用程式(開發中)。
business_creative_management
權限要求
curl -X POST \ -F 'permitted_tasks=['CREATE_CONTENT','VIEW_INSIGHTS']' \ -F 'business={partner-business-id} ' \ -F 'access_token={user-access-token}' https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/agencies
回應分為兩種,取決於用戶在其商家組織中的角色:
API 會在用戶商家和顧客商家之間建立一項合作協議。
回應
若用戶商家和貴公司已有合作協議(用戶商家與您分享了一個資料夾,且您曾經接受過分享要求):
{ "success": true }
如果您未曾接受過用戶商家提出的任何分享要求:
{ "success": true, "share_status": "In Progress" }
在此情況下,貴公司需先接受分享要求,才能存取分享後能夠支援的所有功能(查看、建立等等)。
要列出所有待核准的合作協議,請使用您的合作夥伴存取權杖傳送一項要求到 {business-id}/received_sharing_agreements
,並將 request_status
設為 IN_PROGRESS
。您需要有 business_creative_management
和 business_management
權限才能執行這項操作。
列出所有合作協議
要求
curl -i -X GET https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/received_sharing_agreements ?request_status=IN_PROGRESS &access_token={partner-access-token}"
傳送 POST
到 business_sharing_agreement_request_id
並將 request_status
設為 APPROVE
,即可接受分享要求。您只需要在第一次有人與貴公司分享資料夾時執行這項操作。您需要有 business_management
權限才能執行這項操作:
接受合作協議
要求
curl -X POST \ -F 'request_status=APPROVE' \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_SHARING_AGREEMENT_REQUEST_ID>
回應
{ "success": true }
或者,您可以在企業管理平台用戶介面中核准處理中的分享要求。要在企業管理平台中查看處理中的要求,請進入設定 > 要求 > 收到的要求,您可以在這裡看見與該項要求相關的詳細資訊。
API 會觸發一項通知工作流程,傳送一封電子郵件通知給企業管理平台管理員,請對方核准要求。
回應
{ "success": true, "share_status": "Pending" }
回應這個狀態時,您的應用程式應會通知用戶以下情形:
要列出用戶商家中已經發出且正在處理中的所有協議,請傳送一項要求到 {business-id}/attempted_sharing_agreements
並將 request_status
設為 IN_PROGRESS
、將 requesting_business_id
設為該用戶的企業管理平台編號。您需要有 business_creative_management
和 business_management
權限才能執行這項操作。
列出所有處理中的資料夾分享協議
要求
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/attempted_sharing_agreements ?request_status=IN_PROGRESS &requesting_business_id=<user_business_id> &access_token={partner-access-token}
使用要求編號列出所有處理中的資料夾分享協議
或者,如果您有要求編號,也可以傳送一項要求到 {request_id}
,直接取得狀態。
business_creative_management
權限要求
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<REQUEST_ID>?fields=status
企業管理平台管理員核准要求後,狀態會變更為 APPROVE
,若該用戶的商家和貴公司已經建立了分享協議關係(用戶商家與您分享了一個資料夾,且您曾經接受過分享要求),您的企業管理平台就可以共用這個資料夾。否則,share_status
會更新為 IN_PROGRESS
。您可以列出所有狀態是 IN_PROGRESS
的合作協議,並且透過企業管理平台用戶介面中的 API 接受這些協議。
當用戶使用 VIEW_INSIGHTS
任務的權限與您分享資料夾時,您只要在 <business_asset_id>/insights
端點上發出一項 GET
要求,就能讀取共用資料夾中的商家圖像和影片洞察報告。
business_creative_management
和 business_creative_insights
權限。要求
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ASSET_ID>/insights ?breakdowns=["age","gender"] &fields=impressions,inline_link_clicks,age,gender,date_start, &time_range={"since":"2019-08-01","until":"2019-08-22"} &access_token={partner-access-token}"
回應
{ "data": [ { "impressions": 99, "inline_link_clicks": 1, "age": "18-24", "gender": "female", "date_start": "2019-08-01", "date_end": "2019-08-22" }, { "impressions": 198, "inline_link_clicks": 2, "age": "18-24", "gender": "male", "date_start": "2019-08-01", "date_end": "2019-08-22" }, { "impressions": 464, "inline_link_clicks": 2, "age": "25-34", "gender": "female", "date_start": "2019-08-01", "date_end": "2019-08-22" }, ] }
若要進行資料解析,可以這麼做:
gender
age
country
publisher_platform
platform_position
device_platform
ad_id
objective
optimization_goal
time_range
(必須要有日期,日期格式必須是「YYYY-MM-DD」,表示從當天午夜開始。)若是合約服務合作夥伴,您可以使用合作夥伴存取權杖管理最上層資料夾,只要與您分享的該資料夾已得到適當許可的任務,並且授予您以下權限:
CREATE_CONTENT
任務權限,允許您的應用程式建立子資料夾,以及上傳圖像及影片到該資料夾。VIEW_INSIGHTS
任務權限,您的應用程式可以使用這項權限,查看儲存在這個資料夾中的任何廣告創意素材的效能洞察報告。呼叫 <business_id>/creative_folders
端點,取得用戶商家分享給您的所有上層資料夾。
business_creative_management
權限取得用戶商家提供的資料夾
要求
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<partner_business_id>/creative_folders?filtering=[{field:"owner_business_id", operator:"EQUAL", value:"user_business_id"}]
回應
{ "data": [ { "id": "<shared_folder_id>" } ] }
取得您有權對該資料夾執行的任務
要求
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<folder_id>/agencies
回應
{ "data": [ { "id": "<partner_business_id>", "name": "<partner business name>", "permitted_tasks": [ "VIEW_INSIGHTS", "VIEW_CONTENT", "CREATE_CONTENT", "MANAGE_CONTENT", "MANAGE_PERMISSIONS"] } ], }
CREATE_CONTENT
任務權限任務,才能上傳圖像及影片到共用資料夾VIEW_INSIGHTS
任務權限任務,才能查詢共用資料夾中圖像或影片的廣告創意洞察報告只要您有上層資料夾的 CREATE_CONTENT
任務權限,就能在共用資料夾中建立子資料夾。
business_creative_management
權限建立子資料夾
要求
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F "parent_folder_id={parent-folder-id}" -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
回應
{ "id": {subfolder-id} }
請按照步驟 5 所列的步驟操作。使用合作夥伴權杖,將圖像及影片上傳到子資料夾。
當您的應用程式上傳圖像或影片到 Facebook 的素材資料庫時,Facebook 的 API 會傳回該素材的編號。
為方便後續作業,您的應用程式需根據在您的應用程式中產生這個圖像/影片的專案/工作空間追蹤素材的編號。
這樣能夠讓未來會支援的「編輯」和「更新」用途更加流暢,例如:
media_library_url
欄位要求
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<asset_id>?fields=media_library_url
&action=CREATE_AD
或 &action=CREATE_POST
。範例:
https://business.facebook.com/asset_library/business_creatives/?object_id=2838437832929622&action=CREATE_AD