FBE Creative 新手入门

通过 Facebook Business 扩展程序 (FBE),您的用户可以通过与全新或现有商务管理平台连接,轻松在 Meta 旗下应用中上传创意素材。通过使用完成此流程后返回的商务管理平台,合作伙伴可以代表其客户将创意素材上传至 Facebook:

本文档概述了 FBE Creative 流程的主要先决条件以及完成该流程所需的步骤。请参阅 Facebook Business 扩展程序指南,了解整个集成的特定详细信息。

示例 — 从合作伙伴界面执行入门流程(业务帐户关联登录)

准备工作

  1. 注册成为 Facebook 开发者,以访问我们的开发者工具和创建 Facebook 应用。

  2. 如果您还没有创建 Meta 应用,请完成此步骤。

  3. 您的 Meta 应用必须归已认证企业的商务管理平台所有。详细了解如何完成公司验证

  4. 创建测试版应用,并将该应用用于执行各种新开发和测试。请务必为测试版应用指定一个不同的商务管理平台。

  5. 私人权限或功能:

  • manage_business_extension — 对 Facebook Business 扩展程序的访问权限。在该功能发布至您的应用后,您便可以在产品下找到 FBE 开发者面板

  • Business_creative_asset_management — 对创意相关素材管理 API 的访问权限。获得此功能的授权后,您便可以使用以下权限:

    • business_creative_insights:访问商用素材成效分析。

    • business_creative_management:允许您的应用在您自己的商务管理平台实体背景下创建、编辑和分享新文件夹,并将素材上传至这些文件夹。

    • business_creative_insights_share(开发中):用于文件夹分享流程的可选权限。如果得到用户授权,您的应用便能够将创意文件夹分享给其他企业,并允许这些企业查看创意素材成效分析。

完成应用审核后

生成合作伙伴访问口令:

  • 遵循此页面的说明,在您的商务管理平台下生成管理员级系统用户访问口令。

  • 确保此口令具有在“可用范围”步骤中选择的 business_creative_insightsbusiness_creative_managementbusiness_management 权限。

实施“将我的设计发送给 Facebook”按钮

该按钮用于将素材从您的应用发送到用户的 Facebook 媒体中心资源库。在此流程中,您的应用需要允许用户选择或创建文件夹,以将素材发送至该文件夹。

建议您通过两种方法完成此操作:

1. (最低要求)用户只具有用于选择或创建顶级文件夹的选项。在选定的商务管理平台背景下,查询用户可以访问的所有顶级文件夹。要求用户选择现有的顶级文件夹或创建新的顶级文件夹。用户可以指定文件夹名称,也可以使用默认文件夹名称 <YourBusinessName>_<UserBusinessName>_<UserName>。将素材上传至选定的或新建的顶级文件夹。此方法所需的用户界面工作量最少,且 API 详细信息可在下方的步骤 3 中找到。

2. (可选)用户拥有完整的文件夹和子文件夹导航控件。在选定的商务管理平台背景下,查询用户可访问的所有顶级文件夹,并询问用户是选择现有顶级文件夹还是新建文件夹。对于新建文件夹,要求用户为文件夹命名或使用默认文件夹名称 <YourBusinessName>_<UserBusinessName>_<UserName>。在选定的顶级文件夹下,用户可以选择导航至现有子文件夹、创建新子文件夹或上传素材。使用此选项,您需要在用户界面中实施文件夹导航。API 集成说明请参阅下方的 步骤 3步骤 4

实施此流程所需执行的具体步骤如下:

  1. 实施 Facebook Business 扩展程序
  2. 获取商务管理平台背景信息
  3. 选择或创建顶级文件夹
  4. 选择或创建子文件夹
  5. 上传图像/视频
  6. 请求与您共享文件夹(可选)
  7. 查看图像/视频成效分析(可选)

1. 实施 Facebook Business 扩展程序

当用户首次将创意素材发送到 Facebook 时,您需要提示 Facebook Business 扩展程序,以要求用户进行身份呢验证并授予您的应用必要的权限及对素材的访问权限,以访问口令的形式访问用户在 Facebook 上的数据。请参阅“Facebook Business 扩展程序:入门指南”,以在应用中实施 Facebook Business 扩展程序。遵循业务应用指南,使您的应用可以出现在业务应用界面上。

如要提示创意流程:

  • 设置下传递 channel: CREATIVEbusiness_vertical: CREATIVE
  • 使用 business_creative_managementbusiness_creative_insights 权限
    • 对于查询企业编号、创建文件夹以及将创意素材上传到文件夹而言,这些是必要权限
  • (可选)使用 business_creative_insights_share 权限
    • 允许用户与您分享具有 VIEW_INSIGHTS 任务权限的文件夹

使用从该提示返回的用户访问口令,您可以代表用户进行 API 调用。

必要配置

extras 对象

字段类型说明

setup

setup 对象

必填

卖家的 Facebook 设置,例如,他们的唯一身份识别信息 (external_business_id),或者其目录的货币 (currency)。请参阅 setup 对象详情

business_config

business_config 对象

必填

Facebook Business 扩展程序用于配置 Facebook Business 扩展程序流程的配置对象。请参阅 business_config 对象详情

repeat

布尔值

必填

将此值设置为 false

设置

使用该对象来定义最终用户的 Facebook 形象设置

字段描述

external_business_id
类型:字符串

必要。
代表客户企业的唯一企业编号。我们将该编号用作唯一的标识符。例如,如果卖家的公司名为“Fubar”,则其 external_business_id 可以是“fubar-123”。

timezone
类型:字符串

必要。
企业所在时区。请参阅可选的时区值

currency
类型:字符串

必要。
企业目录商品使用的默认货币,格式为以三个字母表示的 ISO 货币代码。请参阅支持的货币代码

business_vertical
类型:枚举

必要。
企业与关联的垂直领域
值:CREATIVE

channel
类型:枚举

必要。
为合作伙伴提供一种途径,使其能向用户表达有关需要额外步骤或约束的功能的意图。值:CREATIVE

  • CREATIVE — 通过此流程,用户可以在合作伙伴平台上创建创意素材,并将该创意素材分享回用户的商务管理平台。

business_manager_id
类型:字符串

可选。
用户现有商务管理平台的商务管理平台编号,合作伙伴可以输入该编号,从而在设置流程中为用户进行预选。

business_config 对象

使用该对象为最终用户配置企业设置。其中包括行动号召 (CTA)、服务彩笺等。每个字段都包含一个链接到下方对应表格的“type”。

字段描述

business
类型:FBEBusinessPropertiesConfigData

必要。
最终用户的企业信息

FBEBusinessPropertiesConfigData

使用该对象来配置企业名称。

字段描述

name
类型:字符串

必要。
企业名称

2. 获取商务管理平台背景信息

用户完成上述 FBE 入门流程后,您将通过 FBE 安装 API 或 Webhooks 通知收到用户的商务管理平台编号和访问口令。

3. 选择或创建顶级文件夹

用户可以上传素材到顶级文件夹,或在顶级文件夹下方创建子文件夹。

首先,通过对 <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}
}

4. 选择或创建子文件夹

如果您想要支持完整的文件夹导航流程,请要求用户选择现有子文件夹,或者通过以下请求在顶级文件夹下创建新的子文件夹:

获取子文件夹

  • 请求 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 请求,可删除文件夹和子文件夹。

5. 将图像和视频上传到子文件夹

将用户的创意素材上传到子文件夹。

  • 请求 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='&#064;&#123;video-path&#125;'' \
    -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 素材库下的文件夹或素材。

6. 请求与您分享文件夹(可选)

如要管理文件夹或查看素材的成效分析,则可以请求与您分享顶级文件夹。发送 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 种类型中的一种,具体取决于用户在企业组织中的身份:

1) 如果客户端口令代表商务管理平台管理员:

该 API 将在用户商务管理平台和客户商务管理平台之间建立合作协议。

响应

如果用户企业与您的企业之间建立了合作协议(用户企业与您分享了文件夹,并且您之前接受了共享请求),系统将返回以下响应:

{ 
    "success": true
}

如果您尚未接受用户企业的任何共享请求,系统将返回以下响应:

{
    "success": true,
    "share_status": "In Progress"
}

在这种情况下,您的企业需要先接受共享请求,然后才能访问通过分享提供的所有功能(查看、创建等)。

要列出所有待批准的合作协议,请使用您的合作伙伴访问口令将请求发送到 {business-id}/received_sharing_agreements,并将 request_status 设置为 IN_PROGRESS。您需要 business_creative_managementbusiness_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}"

您可以通过发送 POSTbusiness_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
}

或者,您可以在商务管理平台用户界面审核待处理的共享请求。如要在商务管理平台中查看待处理的请求,请前往设置 > 请求 > 已接收的请求,您可以在其中查看有关该请求的更多信息。


2) 如果客户端口令代表商务管理平台工作人员:

该 API 会触发通知流程,以向商务管理平台管理员发送电子邮件通知以审批该请求。

响应

{
   "success": true,
   "share_status": "Pending"
}

为响应此状态,您的应用应通知用户以下情况:

  • 已通过电子邮件向其商务管理平台管理员发起了一个请求,以批准共享请求
  • 关于该请求的另一封电子邮件已发送给用户

要列出用户商务管理平台中已发起的所有待处理协议,请将请求发送到 {business-id}/attempted_sharing_agreements 并将 request_status 设置为 IN_PROGRESS,将 requesting_business_id 设置为用户的商务管理平台编号。您需要 business_creative_managementbusiness_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 或在商务管理平台用户界面中接受这些协议。

7. 查看图像/视频成效分析(可选)

当用户与您分享具有 VIEW_INSIGHTS 任务权限的文件夹时,您可以通过在 <business_asset_id>/insights 端点上发起 GET 请求,阅读共享文件夹下对商务管理平台图像和视频的成效分析。

商用素材成效分析

  • 需要 business_creative_managementbusiness_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 任务权限,您的应用可以使用该权限来查看存储在该文件夹中的任何素材资源的成效分析。

1. 查看父级文件夹权限

调用 <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 任务权限任务是查询共享文件夹下图像或视频创意素材成效分析的必要条件

2. 在父级文件夹下创建子文件夹

通过父级文件夹的 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}
}

3. 将图像和视频上传到子文件夹

步骤 5 中列出的相同步骤操作。使用合作伙伴口令将图像和视频上传到子文件夹。

跟踪图像/视频 Facebook 素材编号

当您的应用将图片或视频上传到 Facebook 的素材库时,Facebook 的 API将返回该素材的编号。

为促进持久的连续性,您的应用需要根据在您应用中生成此图像/视频的项目/工作区来跟踪素材编号。

这将简化“编辑”和“更新”用例,而这些用例未来将获得支持,例如:

  • 应用中的用户在将素材发布到 Facebook 并在广告中使用后,决定继续对其进行编辑。如果您的应用在上传图像/视频的更新版本时发送了原始素材编号,则用户会收到关于简化的“更新”或“运行拆分测试”流程的提示。
  • Facebook 广告成效分析面板中的用户可以“编辑”自己的素材,包括编辑图像/视频(会将用户发送至应用),并传递素材编号。对此,您的应用将能够打开已创建该素材的项目,从而使用户能够从上次停止的地方继续工作。

提供指向素材的深度链接网址并创建广告和发布操作

素材的深度链接网址

  • 查询已上传的图像/视频素材的 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

后续步骤