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 呼叫。
欄位 | 類型 | 描述 |
---|---|---|
| setup 物件 | 必填 賣家的 Facebook 設定,如他們的不重複識別碼 ( |
| business_config 物件 | 必填 Facebook Business 擴充功能用於配置 Facebook Business 擴充功能流程的配置物件。請參閱 |
| 布林值 | 必填 將此值設定為 |
使用此物件來定義終端用戶在 Facebook 的狀態設定
欄位 | 說明 |
---|---|
| 此為必要項目。 |
| 此為必要項目。 |
| 此為必要項目。 |
| 此為必要項目。 |
| 此為必要項目。
|
| 此為選用項目。 |
使用此物件為終端用戶配置企業設定。這包括 CTA、服務卡等。每個欄位均有一個「類型」,詳情請見下方相應表格中的連結文字。
欄位 | 說明 |
---|---|
| 此為必要項目。 |
使用此物件來配置企業名稱。
欄位 | 說明 |
---|---|
| 此為必要項目。 |
用戶完成上述 FBE 初始設定流程後,您將會透過 FBE 安裝 API 或 Webhook 通知收到用戶的企業管理平台編號和存取憑證。
用戶可以上載素材至頂層資料夾,或在頂層資料夾下方建立子資料夾。
首先,向 <business_id>/creative_folders
端點(開發中)發出要求,以便查看用戶在執行 CREATE_CONTENT
任務時擁有哪些頂層資料夾的權限。
要求
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} }
您可以向 <folder_id>
或 <subfolder_id>
端點傳送 DELETE
要求,以刪除資料夾和子資料夾。
將用戶的廣告創意素材上載至子資料夾。
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,您可以在單個要求中上載影片,否則可以分為區塊來上載(請參閱下方的下一部分)。執行 API 呼叫以在 graph-video.facebook.com
上載影片,而不是 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>" }
如果是較大型的影片,您可以傳送一個開始要求、一個或多個傳輸要求,以及一個結束要求。
如要發出開始要求並建立影片上載作業階段,請向 /{business-id}/videos
傳送 POST
要求,設定 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 素材資料庫下的資料夾或素材。
如要管理資料夾或查看素材的洞察報告,您可以要求與您分享頂層資料夾。向 {business-creative-folder-id}/agencies
傳送 POST
要求,並將 permitted_tasks
分配至 CREATE_CONTENT
。
備註:如果用戶向您的應用程式授予了 business_creative_insights_share
(開發中),您還可以分配 VIEW_INSIGHTS
許可的任務。
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