市场营销 API

互动自定义受众

根据在 Facebook 或 Instagram 上与您内容互动的用户创建自定义受众。目前支持的受众类型包括公共主页、Instagram 业务主页、潜客广告、即时体验广告、购物和增强现实。

本指南以公共主页互动受众为例对此 API 进行说明。Facebook 会持续添加与您公共主页互动的用户，以更新公共主页互动自定义受众。当您首次创建此受众时，Facebook 会在其中预填在指定留存期限内已与您公共主页互动的用户名单。

  • 自 2018 年 9 月起，我们不再为网站和应用的自定义受众、互动自定义受众以及线下转化数据受众提供 subtype 支持。唯一的例外是视频的互动自定义受众，我们将为其提供 subtype 支持。

  • 如果您想要创建来自欧洲的受众或是将目标受众设置在欧洲，请参阅我们于 2020 年 12 月 2 日发布的非版本更改。

创建受众

如要创建互动自定义受众，您的广告账户必须在广告管理工具中接受自定义受众服务条款。

如要根据 page_engaged 事件创建列出曾与公共主页互动用户的受众，请执行以下调用：

curl -X POST \
  -F 'name="My Test Engagement Custom Audience"' \
  -F 'rule={
       "inclusions": {
         "operator": "or",
         "rules": [
           {
             "event_sources": [
               {
                 "id": "<PAGE_ID>",
                 "type": "page"
               }
             ],
             "retention_seconds": 31536000,
             "filter": {
               "operator": "and",
               "filters": [
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "page_engaged"
                 }
               ]
             }
           }
         ]
       }
     }' \
  -F 'prefill=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences

参数

名称描述

name

字符串

必要。
自定义受众的名称。

rule

JSON 对象

必要。
用于定义受众的规则。此规则遵循与网站自定义受众相同的语法。

互动自定义受众是多种类型的自定义受众。如要了解所有可用字段，请参阅自定义受众参考文档。

注意：每个广告账户最多可创建 500 个互动自定义受众。

互动规则

您可以使用受众规则来决定 Facebook 是否将某位用户添加到自定义受众中。

在规则中指定 event_sources 内的 type 和 id 字段，以表明互动对象的 type 和 id。id 字段为单个对象编号或由同类型编号构成的数组。

以下是支持的事件源和对应的互动对象编号：

  • page：Facebook 公共主页编号。
  • lead：潜客信息表单编号。
  • ig_lead_generation：潜客信息表单编号。
  • canvas：全屏广告编号。
  • ig_business：Instagram 业务主页编号。
  • shopping_page：Facebook 店铺公共主页编号。
  • shopping_ig：Instagram 店铺编号。
  • ar_experience：使用 AR 特效的即时体验。
  • ar_effects：您拥有的 Facebook 或 Instagram 特效。这不包括广告中使用的特效。

每条规则都包含一个 object_id 和一个 event_name。

公共主页

将 object_id 设置为您的公共主页编号。在 event_name 下方，使用以下其中一个互动事件：

  • page_engaged：在 Facebook 或 Messenger 上访问您公共主页或与该公共主页的任何内容或广告互动的用户。这是涵盖范围最广的互动类型，包含所有其他类型的互动。
  • page_visited：已访问您公共主页的用户。
  • page_liked：当前为您公共主页点赞的用户。（请参阅“公共主页点赞留存率和规则”部分，了解相关详情。）
  • page_messaged：已向您的公共主页发送消息的用户。
  • page_cta_clicked：已点击您公共主页中任何行动号召按钮的用户（例如，“联系我们”或“去逛逛”）。
  • page_or_post_save：已保存您的公共主页或任何公共主页帖子的用户。
  • page_post_interaction：已与您的任何公共主页帖子互动的用户。互动包括发送心情（即赞、大爱、笑趴、哇、心碎、怒）、分享、评论、点击链接或滑动轮播广告。

潜客广告

将 object_id 设置为 FORM_ID，并设置 rule 以追踪以下其中一个潜客广告事件：

  • lead_generation_submitted：填写并提交表单的所有用户。
  • lead_generation_dropoff：关闭而未提交表单的所有用户。他们可能已填写字段，也可能未填写任何字段。
  • lead_generation_opened：打开过潜客开发广告表单的所有用户（无论他们是否提交该表单）。

即时体验

将 object_id 设置为 "CANVAS_ID"。rule 应追踪下列事件之一：

  • instant_shopping_document_open
  • instant_shopping_document_pause
  • instant_shopping_document_resume
  • instant_shopping_document_close
  • instant_shopping_did_scroll
  • instant_shopping_element_click
  • instant_shopping_element_impression

Instagram 业务主页

object_id 应当为 "INSTAGRAM_BUSINESS_PROFILE_ID"，同时 rule 应当追踪以下 Instagram 业务主页事件之一：

  • ig_business_profile_all：访问您的 Instagram 业务主页或与任何 Instagram 业务主页内容或广告互动的用户。这是涵盖范围最广的互动类型，包含所有其他类型的互动。这是 ig_business_profile_engaged、ig_user_messaged_business 和 ig_user_messaged_business 的组合。
  • ig_business_profile_engaged：与您的 Instagram 业务主页互动或与该 Instagram 业务主页的任何内容或广告互动的用户。
  • ig_user_messaged_business：向您的 Instagram 业务主页发送消息的用户。
  • ig_business_profile_visit：访问您的 Instagram 业务主页的用户。
  • ig_business_profile_ad_saved：已保存您 Instagram 业务主页的自然内容或广告的用户。
  • ig_ad_like
  • ig_ad_comment
  • ig_ad_share
  • ig_ad_save
  • ig_ad_cta_click
  • ig_ad_carousel_swipe
  • ig_organic_like
  • ig_organic_comment
  • ig_organic_share
  • ig_organic_save
  • ig_organic_swipe
  • ig_organic_carousel_swipe

创建视频互动自定义受众目前不支持 Instagram 媒体创作者类型。

购物

购物互动规则应当追踪下列事件之一：

  • VIEW_CONTENT：在您产品详情页面浏览过的用户。此选项面向全球的消费者。
  • ADD_TO_CART：将您的产品添加至购物车的用户。仅面向美国的消费者，且仅限启用结账功能的企业。
  • PURCHASE：购买过您产品的用户。仅面向美国的消费者，且仅限启用结账功能的企业。

如要创建规则以添加浏览过您产品的用户，请执行以下调用：

curl -i -X POST
-F 'name="test_api"'\
-F 'rule= {
	"inclusions": {
		"operator": "or",
		"rules": [
			{
				"event_sources": [
					{
						"id": "<ID>",
						"type": "shopping_ig"
					}
				]
				"retention_seconds": <RETENTION_SECONDS>,
				"filter": {
					"operator": "and",
					"filters": [
						{
						"field":"event",
						"operator":"eq",
						"value": "VIEW_CONTENT"
						}
					]
				}
			}
		]
	}
}
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences

受新隐私规则的影响，欧洲地区可能无法使用 page_messaged 和 ig_user_messaged_business 参数。

增强现实

增强现实互动自定义受众可包含 2 个部分：AR 体验和 AR 特效。

  • 对于 AR 体验互动自定义受众，需将 object_id 设置为 AR 广告的数据容器编号，并对 event_name 字段使用 ar_camera_open 或 camera_cta_click。
  • 对于 AR 特效互动自定义受众，需将 object_id 设置为 AR 特效编号，并对 event_name 字段使用 ar_effect_open。

最长留存天数

根据法律和隐私要求，我们允许每种事件源类型有不同的最长留存天数：

  • 潜客开发广告：90 天
  • Instagram 业务主页：730 天
  • 公共主页：730 天
  • 即时体验（原全屏广告）：730 天
  • 购物：365 天。此数据自 2020 年 4 月起可用。
  • 增强现实：365 天

具有排除部分的互动规则

互动受众规则与网站自定义受众规则兼容。因此，互动受众可以有多条包含和排除规则。系统会将匹配至少其中一条规则的用户添加到受众中。

在以下示例中，我们将创建包含访问您公共主页或与您公共主页互动的用户的受众，但排除点击行动号召的用户：

curl -X POST \
  -F 'name="My Test Engagement Custom Audience"' \
  -F 'rule={
       "inclusions": {
         "operator": "or",
         "rules": [
           {
             "event_sources": [
               {
                 "id": "<PAGE_ID>",
                 "type": "page"
               }
             ],
             "retention_seconds": 31536000,
             "filter": {
               "operator": "and",
               "filters": [
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "page_engaged"
                 }
               ]
             }
           }
         ]
       },
       "exclusions": {
         "operator": "or",
         "rules": [
           {
             "event_sources": [
               {
                 "id": "<PAGE_ID>",
                 "type": "page"
               }
             ],
             "retention_seconds": 31536000,
             "filter": {
               "operator": "and",
               "filters": [
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "page_cta_clicked"
                 }
               ]
             }
           }
         ]
       }
     }' \
  -F 'prefill=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences

详情请参阅网站自定义受众。

多条规则

互动受众可以有多条规则，并且将向受众中添加至少与一条规则匹配的用户。示例：创建包含已向您的页面发送消息或点击行动号召的用户的受众：

curl -X POST \
  -F 'name="My Test Engagement Custom Audience"' \
  -F 'rule={
       "inclusions": {
         "operator": "or",
         "rules": [
           {
             "event_sources": [
               {
                 "id": "<PAGE_ID>",
                 "type": "page"
               }
             ],
             "retention_seconds": 31536000,
             "filter": {
               "operator": "and",
               "filters": [
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "page_engaged"
                 },
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "page_engaged"
                 }
               ]
             }
           }
         ]
       }
     }' \
  -F 'prefill=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences

多个页面

规则不限于单个公共主页。每条规则都可用于不同页面，只要用户与其中至少一个页面互动，我们便会将他们包含在受众之中。

以下为包含至少访问过三个页面之一的所有用户的受众的示例：

curl -X POST \
  -F 'name="My Test Engagement Custom Audience"' \
  -F 'rule={
       "inclusions": {
         "operator": "or",
         "rules": [
           {
             "event_sources": [
               {
                 "id": "<PAGE_ID>",
                 "type": "page"
               },
               {
                 "id": "<PAGE_ID>",
                 "type": "page"
               }
             ],
             "retention_seconds": 31536000,
             "filter": {
               "operator": "and",
               "filters": [
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "page_engaged"
                 }
               ]
             }
           }
         ]
       }
     }' \
  -F 'prefill=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences

如要了解自定义受众的详情，请参阅自定义受众参考资料。

页面点赞留存率和规则

为公共主页点赞的受众不具备留存率 (retention_seconds=0)。同样，公共主页点赞规则无法应用于其他公共主页事件。

以下为创建为公共主页点赞的受众示例：

curl -X POST \
  -F 'name="Page Likes Audience Name"' \
  -F 'rule={
       "inclusions": {
         "operator": "or",
         "rules": [
           {
             "event_sources": [
               {
                 "id": "<PAGE_ID>",
                 "type": "page"
               }
             ],
             "retention_seconds": 0,
             "filter": {
               "operator": "and",
               "filters": [
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "page_liked"
                 }
               ]
             }
           }
         ]
       }
     }' \
  -F 'prefill=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences