通过 Facebook Business 扩展程序 (FBE),您的用户可以通过与全新或现有商务管理平台连接,轻松在 Meta 旗下应用中上传创意素材。通过使用完成此流程后返回的商务管理平台,合作伙伴可以代表其客户将创意素材上传至 Facebook:
本文档概述了 FBE Creative 流程的主要先决条件以及完成该流程所需的步骤。请参阅 Facebook Business 扩展程序指南,了解整个集成的特定详细信息。
示例 — 从合作伙伴界面执行入门流程(业务帐户关联登录)
注册成为 Facebook 开发者,以访问我们的开发者工具和创建 Facebook 应用。
如果您还没有创建 Meta 应用,请完成此步骤。
创建测试版应用,并将该应用用于执行各种新开发和测试。请务必为测试版应用指定一个不同的商务管理平台。
私人权限或功能:
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)、服务彩笺等。每个字段都包含一个链接到下方对应表格的“type”。
字段 | 描述 |
---|---|
| 必要。 |
使用该对象来配置企业名称。
字段 | 描述 |
---|---|
| 必要。 |
用户完成上述 FBE 入门流程后,您将通过 FBE 安装 API 或 Webhooks 通知收到用户的商务管理平台编号和访问口令。
用户可以上传素材到顶级文件夹,或在顶级文件夹下方创建子文件夹。
首先,通过对 <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 素材库下的文件夹或素材。
如要管理文件夹或查看素材的成效分析,则可以请求与您分享顶级文件夹。发送 POST
请求到:{business-creative-folder-id}/agencies
,并将 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
响应将为 2 种类型中的一种,具体取决于用户在企业组织中的身份:
该 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