即时体验

即时体验是用户点击后的全屏广告目标位置，几乎可以立即从动态中的广告中加载出来。

此 API 中任何提及 canvas 的地方都是指即时体验。全屏广告是这一格式的旧称。

前期准备

要创建和管理即时体验，您需要满足以下条件：

限制

您只能更新未发布的的即时体验。
即时体验 API 仅限部分 Instagram 功能使用。
Facebook 快拍不支持使用即时体验的广告。

创建

要创建即时体验，您需要 Facebook 公共主页的编号 (PAGE-ID) 和希望包含在您的体验中的任何元素，例如照片、按钮和文本。

curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<PAGE_ID>/canvases

元素

名称	描述
按钮	即时体验中的按钮。`button_style` 字段为必要字段。
轮播广告	即时体验的轮播广告。
页脚	即时体验的页脚。
标题	即时体验的标题。
照片	即时体验中的照片。您应该提供已上传到 Facebook 公共主页的照片的 `PHOTO-ID`。
商品列表	即时体验的商品列表。
商品系列	即时体验中显示的进阶赋能型目录广告商品目录中的一系列商品。
店铺定位工具	即时体验中的店铺定位工具。
文本	即时体验中显示的文本及其样式。
视频	即时体验中的视频。您应该提供已上传到 Facebook 公共主页的视频的 `VIDEO-ID`。

删除元素

要删除元素，请发送包含您要删除元素的编号的 DELETE 请求。

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CANVAS_ELEMENT_ID>

获取现有即时体验

要获取有关现有即时体验的信息，您需要即时体验的编号 (CANVAS-ID)。

curl -G \
  --data-urlencode 'fields=[ 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CANVAS_ID>

获取公共主页的所有即时体验

要获取有关 Facebook 公共主页的所有现有即时体验的信息，您需要公共主页的编号 (PAGE-ID)。

curl -G \
  --data-urlencode 'fields=[ 
    "background_color", 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "last_editor", 
    "name", 
    "owner", 
    "update_time" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<PAGE_ID>/canvases

更新即时体验

要更新即时体验，该体验必须未发布，并且您需要即时体验的编号 (CANVAS-ID) 和要更新的任何元素编号。

curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CANVAS_ID>

使用模板

您可以使用模板针对特定的业务目标快速创建即时体验。虽然每个模板的布局是固定的，但您可以将默认内容替换为自己的图片、视频、商品、文本和链接。

API 模板名称	模板编号	描述
获取新客户	`133471657203838`	打造具有行动号召力的移动落地页，提升转化量。广告管理工具中的“争取新客户”模板。
展示您的业务	`1063217037112304`	利用精彩广告体验赢得受众关注，让他们探索您的品牌、商品或服务。广告管理工具中的“品牌故事”模板。
销售商品（不含目录）	`424787857903852`	通过上传您的商品信息而不是使用目录来打造移动购物体验。广告管理工具中的“销售商品（不含目录）”模板。
销售商品：生活方式布局	`1369752616394017`	通过在照片中展示您的商品，让用户在行动中探索这些商品。广告管理工具中的“造型秀”模板。
销售商品：网格布局	`1932289657009030`	使用您的商品目录来打造体验，让用户可以直接在移动设备上购物。广告管理工具中的“店面”模板。
AR 体验		“AR 体验”模板只能通过广告管理工具使用。

获取模板的元素类型

第 1 步：获取模板的文档信息

发送 GET 请求来确定特定模板需要哪些元素，以下示例中为获取新客户。

curl -i -X GET \
 "https://graph.facebook.com/VERSION/133471657203838?fields=document&access_token=ACCESS-TOKEN"

响应示例

{
  "document": {
    "name": "Get New Customers",
    "id": "397246414010297"
  },
  "id": "133471657203838"
}

第 2 步：获取元素类型

使用 document 字段的编号来获取可用于特定模板的具体元素。

curl -i -X GET \
 "https://graph.facebook.com/VERSION/397246414010297?fields=body_elements&access_token=ACCESS-TOKEN"

返回的列表显示了可在争取新客户模板中使用的显示元素类型。

    {
  "body_elements": [
    {
      "name": "Cover Image or Video",
      "element_type": "PHOTO",
      "id": "397271930674412"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271920674413"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271910674414"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271914007747"
    },
    {
      "name": "Carousel",
      "element_type": "CAROUSEL",
      "id": "397271940674411"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271917341080"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271924007746"
    }
  ],
  "id": "397246414010297"
}

发布

要发布您的即时体验广告，请向您的即时体验编号 (CANVAS-ID) 发送 POST 请求，并将 is_published 字段设置为 true。

curl \
  -F 'is_published=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CANVAS_ID>

创建广告创意

使用现有即时体验的链接 (CANVAS-LINK) 创建广告创意。

curl -X POST \
  -F 'image_hash="<IMAGE_HASH>"' \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "link_data": {
         "image_hash": "<IMAGE_HASH>",
         "link": "<CANVAS_LINK>",
         "name": "Creative message",
         "call_to_action": {
           "type": "LEARN_MORE"
         }
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adcreatives

广告创意准备好后，您就可以继续创建广告版本库、广告组和广告系列。

即时体验广告对话框

您可以使用即时体验广告对话框在网站中提供 Facebook 即时体验广告创建用户界面。如需详细了解用户界面组件，请参阅对话框。

设置 Javascript 版 Facebook SDK，请参阅：

JavaScript SDK 要求已登录的用户具备必要权限，才能创建即时体验。如果用户不具备为广告提供页面和公司创建即时体验的必要权限，则对话框会显示错误。为确保不会出错，用户必须为公司的一员，且需具备公共主页的“创建广告”权限。

然后触发对话框：

FB.ui({         
  display: 'popup',
  method: 'instant_experiences_builder',
  business_id: '<BUSINESS_ID>',
  page_id: '<PAGE_ID>'
}, function(response) {
  // callback
});

您可以为插件提供以下设置：

名称	是否必要	描述
`display`	是	此为必要参数，且设定值为 `popup`
`method`	是	此为必要参数，且设定值为 `instant_experiences_builder`
`business_id`	是	您的公司编号
`page_id`	是	您想将即时体验与之关联的公共主页编号
`canvas_id`	否	您想编辑的即时体验的编号

canvas_id 参数为可选项，旨在允许用户编辑或预览现有的即时体验。即时体验创建完毕后，您无法再进行编辑。要预览即时体验，建议您使用即时体验预览对话框。

操作成功后，此插件会提供如下响应：

{
  "success": true,
  "id": "CANVAS-ID"
}

返回的编号为已发布的即时体验。现在您可以将其用于广告系列。如果无响应或返回 undefined 响应，则表示查看者在即时体验创建完毕之前已关闭对话框。用户可能已保存即时体验，但并未创建完毕。您可以使用图谱 API 拉取属于某个公共主页的所有即时体验，以查看是否有任何尚未创建完毕的体验。

预览即时体验

iframe 预览 API

您可以通过调用此预览 API 来生成即时体验预览。与广告预览 API 相似，此 API 会返回一个 iframe：

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v18.0/<CANVAS_ID>/preview
  
Open In Graph API Explorer

API 返回的响应如下图所示，通过在 HTML 中嵌入返回的 iframe 元素可查看具体响应结果：

{
"data": [
    {
      "body": "<iframe src=\"https://www.facebook.com/ads/canvas/preview?d=AQKELApdJxoVp2f3PHl8-pRtYuAh4-_eDupMDbh-pS9zde_EFxckhYQCXu7NYUi4PhhBA7uskIo2Ys3IjIVNGZiS&t=AQKGOPqGI-NWcv1YKbA\" width=\"405\" height=\"720\" scrolling=\"yes\" style=\"border: none;\"></iframe>"
    }
  ],
  "__www_request_id__": "AQnyr47Qp2r5M-ISqSiMgrw"
}

Facebook SDK

您可以使用此对话框提供即时体验预览，以便在您的网站上查看用户在 Facebook 上看到的效果。如需详细了解此用户界面组件，请参阅对话框。

设置 Javascript 版 Facebook SDK，请参阅：

JavaScript SDK 要求已登录的用户具备必要权限，才能创建即时体验。如果用户不具备查看即时体验的必要权限，则对话框会显示错误。

然后触发预览对话框：

FB.ui({         
  display: 'popup',
  method: 'instant_experiences_preview',
  canvas_id: 'CANVAS-ID'
});

您可以为插件提供以下设置：

名称	是否必要	描述
`display`	是	此为必要参数，且设定值为 `popup`
`method`	是	此为必要参数，且设定值为 `instant_experiences_preview`
`canvas_id`	是	您想预览的即时体验的编号

创建即时体验受众

要创建互动受众（与即时体验互动的受众），请在您的 POST /act_AD-ACCOUNT/customaudiences 调用中将 rule 字段的 object_id 参数设置为即时体验编号 (CANVAS-ID)。

打开即时体验的用户

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who opened this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_document_open"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \  
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences
Open In Graph API Explorer

点击即时体验中任意链接的用户

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who clicked any links in this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_element_click"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \  
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences
Open In Graph API Explorer

如需详细了解自定义受众，请参阅参考资料的“自定义受众”部分。

即时体验与 Instagram 广告

在 Instagram 投放即时体验需要发起与在 Facebook 投放即时体验相同的 API 调用。在使用 Instagram 和即时体验时，请注意下列限制：

版位 - 适用于 Instagram 动态和 Instagram 快拍。如果您选择 Instagram 快拍，则应选择此版位作为唯一广告版位。
即时体验元素 - 完全支持页眉和商品系列。

Instagram 仅部分支持这些即时体验元素：

页脚 - 在客户端中没有 swipe to open，而是显示为 Tap to open。
轮播广告 - 照片不能链接到其他即时体验；在客户端中显示为不可点击的链接。对于照片和视频，不支持适应屏幕高度、适应屏幕宽度或倾斜查看；在客户端显示为适应屏幕宽度。
按钮 - 无法链接至其他即时体验或 App Store。
文本 - 不支持从右向左的语言。
视频 - 不支持 360 度全景视频。
店铺定位工具 - 不支持。

广告成效分析

请参阅广告成效分析，了解可用指标的概述及其说明。

另请参阅

Facebook 广告指南：即时体验规范
Business 帮助中心：了解即时体验