市场营销 API

店铺客流量目标

为帮助您应对新冠疫情，我们对店铺客流量目标的运作方式做了一些临时调整。了解详情。

您可以使用店铺客流量目标创建 Facebook 广告系列，从而提升实体店客流量并提高销量。如果您拥有多家业务店铺并且已经将您的店铺网点添加到 Facebook，则可以为您的广告系列选择店铺客流量目标。

详情请参阅广告帮助中心的“店铺客流量目标”部分。

版位

适用于桌面版和移动版 Facebook（动态、快拍和 Marketplace）以及 Instagram（动态和快拍）。

投放优化

  • 覆盖人数优化：能使用此 API 的所有广告主均可使用。如果使用这一优化方式，系统将针对单日独立覆盖人数进行优化，同时广告管理工具中的报告将默认显示“展示次数”指标。

创建进阶赋能型目录广告

如需创建使用此目标的进阶赋能型目录广告，您的公共主页必须使用 Facebook 网点。

要求

  • 广告系列的 objective 必须设置为 STORE_VISITS。
  • 广告系列的 promoted_object 必须设置为相应的 <PARENT_PAGE_ID>。
  • 广告组的 promoted_object 和 targeting 必须包含设置为 <PAGE_SET_ID> 的 place_page_set_id
  • 广告组的 optimization_goal 必须设置为 REACH
  • 广告组的 billing_event 应设为 IMPRESSIONS

第 1 步：创建 PageSet

Facebook 会使用 PageSet 来为广告定位受众，并将其用作广告的推广对象。

要创建 PageSet，请按以下步骤操作：

  1. 收集店铺网点，即每个店铺网点和主要业务的分店的 Facebook 公共主页。主要业务称为品牌公共主页。
  2. 创建网点 JSON 结构，以表示所有网点。
  3. 使用网点 JSON 结构创建 PageSet。

收集所有店铺网点

<PARENT_PAGE_ID> 是包含您所有店铺网点的品牌公共主页的公共主页编号。此调用会检索品牌公共主页的所有店铺公共主页和网点，并返回每个网点的经纬度：

curl -X GET \
  -d 'fields="location{latitude,longitude},is_permanently_closed"' \
  -d 'limit=30000' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/{page-id}/locations

示例输出

{
    "data": [
        {
            "location": {
                "latitude": 29.173384,
                "longitude": 48.098807
            },
            "is_permanently_closed": false,
            "id": "1788030244802584"
        },
        {
            "location": {
                "latitude": 29.303635,
                "longitude": 47.937725
            },
            "is_permanently_closed": false,
            "id": "261533444245300"
        },
        {
            "location": {
                "latitude": 29.302303,
                "longitude": 47.933178
            },
            "is_permanently_closed": false,
            "id": "179435399132774"
        },
        {
            "location": {
                "latitude": 29.302591,
                "longitude": 47.931801
            },
            "is_permanently_closed": false,
            "id": "1790317704582144"
        }
    ],
    "paging": {
        "cursors": {
            "before": "MTc4ODAzMDI0NDgwMjU4NAZDZD",
            "after": "MTA4MTU4NjU5NjA5MDA4"
        }
    }
}

创建网点 JSON 结构

循环访问所返回结果中的每个条目，并检查 is_permanently_closed 字段以了解每个网点是否都在营业中。

通过两次 GET 请求获取大致的半径，借此获取 radius 和 distance_unit 参数。或者，您也可以批量调用 API，生成如下所示的值。

单个请求

您应该使用从公共主页返回的 JSON 结果中每个店铺主页的纬度和经度坐标来发出此请求。这会返回每个网点的大致半径。

curl -X GET \
  -d 'type="adradiussuggestion"' \
  -d 'latitude=51.5152253' \
  -d 'longitude=-0.1423029' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v20.0/search/

批量请求

您也可以将多个请求批量处理为单个请求。

curl \
  -F "access_token=<ACCESS_TOKEN>" \
  -F "include_headers=false" \
  -F "batch=[
    {
      \"method\": \"GET\",
      \"relative_url\": \"/<API_VERSION>/search?type=adradiussuggestion&amp;latitude=29.173384&amp;longitude=48.098807\"
    },
    {
      \"method\": \"GET\",
      \"relative_url\": \"/<API_VERSION>/search?type=adradiussuggestion&amp;latitude=29.303635&amp;longitude=47.937725\"
    }
  ]" \
  "https://graph.facebook.com"
最终的网点 JSON 结构

使用之前调用返回的结果中的 radius 和 distance_unit 参数，并使用每个网点的 <CHILD_LOCATION_ID> 作为 page_id 来创建最终的网点 JSON 结构。

[
    {
      "page_id": 1788030244802584,
      "radius": 1,
      "distance_unit": "mile"
    },
    {
      "page_id": 261533444245300,
      "radius": 1,
      "distance_unit": "mile"
    }
]

使用网点 JSON 结构创建 Pageset

PageSet 端点目前仅供白名单中的合作伙伴使用。请联系您的 Facebook 代表，申请访问权限。

现在，您可以使用网点 JSON 结构中的信息创建 PageSet。

PageSet 中的网点数量最多为 10,000 个。

异步请求

您可以通过发出异步请求来创建 PageSet。通过这种方法，您可以创建较大的 PageSets，其中包含超过 1,000 个网点，并且不会出现超时问题。凡是创建包含 50 个网点以上的 Pageset，我们都建议您使用异步请求。

请求

curl -X POST \
  -d 'name=test_2' \
  -d 'parent_page=ID_1' \
  -d 'pages=[{\'page_id':ID_2}]' \
  -d 'metadata={"audience":{"size":5000}}' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets_async/

注意：您可以将 /ad_place_page_sets 用于 同步请求；然而，当网点数量超过 50 个时应使用异步请求。

参数的格式与用于同步请求的参数格式相同。

在 PageSet 中，您可以使用 metadata 字段为各网点指定固定的广告投放半径，或覆盖特定大小的受众规模。如果您选择后者，Facebook 将自动计算要覆盖相应数量帐户管理中心帐户所需的各网点半径。

在此示例中，metadata 字段已设置为所需的 audience 规模（详见下文）。请参阅半径的 metadata。这将返回 ad_place_page_set_async_request 编号。

{
  "id": "405738580111111"
}

稍后，您可以借助ads_read 权限查询该编号，以获取 PageSet 编号。

curl -i -X GET \
 "https://graph.facebook.com/<API_VERSION>/405738580111111?access_token=ACCESS_TOKEN"

响应

{
  "id": "405738580111111", 
  "place_page_set": {
    "id": "555555791481678",
    "name": "test_2"
  },
  "progress": 1
}

其中，progress 介于 0.0 到 1之间，1 表示我们已完成您的请求，创建了 PageSet。

使用半径的 metadata

Facebook 可通过 metadata 字段得知，您希望针对网点使用固定半径，或者您希望 Facebook 根据给定受众规模自动计算每个网点所需的半径。

示例

使用同步请求指定固定半径：

curl -X POST \
  -d 'name=test_2' \
  -d 'parent_page=238219010666666' \
  -d 'pages=[{\'page_id':405936056444444}]' \
  -d 'metadata={"fixed_radius":{"value":5,"distance_unit":"mile"}}' \
  -d 'access_token=ACCESS_TOKEN' \
  "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets/"

这意味着您希望 Facebook 向 PageSet 中所有网点 5 英里半径范围内的受众投放广告。

响应

 {
  "id": "1618547271777777"
}

注意：metadata 字段应设置为 fixed_radius 或 audience。

如果您使用的是 fixed_radius，还需要提供distance_unit 和 value：

{
  "fixed_radius": {
     "distance_unit": "<distance_unit>"
     "value": <distance>
  }
}

如果您使用的是 audience，请提供 size，也可以选择性提供 max_radius：

 {
  "audience": {
     "size": <audience size>
     "max_radius": { // optional
       "distance_unit": "<distance_unit>"
       "value": <distance>
     }
  }
}

metadata 的最佳实践

  • 您还必须提供 locations；不过，切勿在其中指定半径。或者，如果您使用 locations 参数并提供半径，则不要同时在 metadata 中提供该参数。
  • distance_unit 必须为 mile 或 kilometer。为 mile 时，value 必须介于 0.7 和 50 之间；为 kilometer 时，value 必须介于 1 和 80 之间。
  • 如果半径的长度在 1 到 80 公里之间，audience 中的 size 参数是半径范围覆盖的帐户管理中心帐户的数量。如果您提供 max_radius，则我们计算的实际半径将介于 1 到 max_radius 之间。
  • 如果您指定了 metadata 中的 audience，则必须使用异步端点发出请求 (ad_account_ID/ad_place_page_set_async)。

同步请求

您还可以使用同步请求创建 PageSet。

curl -X POST \
  -d "name=My Grand Pageset" \
  -d "parent_page=<PARENT_PAGE_ID>" \
  -d "pages=<LOCATIONS_JSON_STRUCTURE>" \
  -d "access_token=<ACCESS_TOKEN>" \
 https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets

此代码将返回 PageSet 编号，供您在后续步骤中使用。

{
  "id": <PAGE_SET_ID>
}

如果公共主页数量太多，无法执行 cURL 调用，您可以创建一个包含网点 JSON 结构的文本文件，并使用以下标记将其传递到 pages 属性中：-F "pages=&lt;locations_json_structure.txt"。

第 2 步：创建广告系列

创建广告系列，并将目标设置为 STORE_VISITS，将品牌公共主页编号设置为推广对象。

请参阅参考资料的“广告系列”部分。

第 3 步：创建广告组

创建广告组，以便在其中创建广告。请参阅参考资料的“广告组”部分、参考资料的“定位参数”部分以及参考资料的“公共主页网点”部分。

如果广告定位的地点与最近的公共主页网点（也称为“本地公共主页”）之间的距离超过 50 英里，则 Facebook 会在投放广告时让这类广告失效。

curl \
  -F 'name=Store Visits Ad Set' \
  -F 'promoted_object={"place_page_set_id":"<PAGE_SET_ID>"}' \
  -F 'optimization_goal=STORE_VISITS' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'is_autobid=true' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F "targeting={
    'place_page_set_ids': ['<PAGE_SET_ID>'],
    'device_platforms': ['mobile','desktop'],
    'facebook_positions': ['feed']
   }" \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

地理位置定位

在店铺访问量广告系列中，您还可以按照 geo_locations 定位受众。

注意： 对于这一目标，您只能在广告组定位条件中使用 geo_locations或place_page_set_ids。

在高级定位和版位中，我们支持所有类型的 geo_location 定位，包括按照国家/地区、城市和邮编定位。您还可以选择 location_types，例如 recent、home 或 travel_in。

您仍然应该在 promoted_object 中提供 place_page_set_id。此 PageSet公共主页集不得包含任何明确的网点集。请参阅使用网点 JSON 结构创建公共主页集，了解如何创建此 PageSet。然而，在这种情况下，切勿传递 pages 参数。

首先，创建稍后要在推广对象中提供的 PageSet：

curl -X POST \
  -d "name=My geo targeting page set" \
  -d "parent_page=<PARENT_PAGE_ID>" \
  -d "access_token=<ACCESS_TOKEN>" \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ad_place_page_sets/

注意：您无需像往常一样提供 pages 参数。

然后，创建一个以店铺客流量为目标的广告组，受众为 geo_locations：

curl \
  -F 'name=Store Traffic Ad Set' \
  -F 'promoted_object={"place_page_set_id":"<PAGE_SET_ID>"}' \
  -F 'optimization_goal=STORE_VISITS' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'is_autobid=true' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F "targeting={
    'geo_locations': {"countries":["US"],"location_types": ["home"]}, 
    'device_platforms': ['mobile','desktop'],
    'facebook_positions': ['feed']
  }" \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

我们会自动向查看广告的用户投放距离用户最近的店铺的广告。

第 4 步：提供广告创意

您可以根据受众所在的位置动态插入创意。您可以使用一组模板占位符来定制创意，然后 Facebook 会在投放广告时使用距离受众最近的公共主页网点的数据替换占位符。

可使用的占位符：

  • {{page.hours.today}}
  • {{page.location.city}}
  • {{page.location.region}}
  • {{page.location.postcode}}
  • {{page.location.street_address}}
  • {{page.name}}
  • {{page.phone_number}}

您可以借助 dynamic_ad_voice 字段控制广告的口吻：

  • 在将 dynamic_ad_voice 设置为 DYNAMIC 时，广告帖子中的公共主页名称和头像来自距离最近的公共主页网点。
  • 在将 dynamic_ad_voice 设置为 STORY_OWNER 时，广告帖子中的公共主页名称和头像来自品牌公共主页网点。

行动号召

您还可以根据受众所在的位置动态插入行动号召按钮 (CTA)：

  • 使用 GET_DIRECTIONS 或 CALL_NOW 时，行动号召 (CTA) 的 value 字段为非必填字段。系统会自动将用户定向至最近的网点或提示用户拨打距离最近的网点的电话号码。
  • 只有将 dynamic_ad_voice 设置为 STORY_OWNER 时，才允许使用 MESSAGE_PAGE。系统会将消息发送给品牌公共主页。
  • 非必填字段。如果没有分别为各个广告指定行动号召按钮，系统将展示 Like Page 按钮。

如需更多信息，请参阅“参考文档”>“广告创意”

dynamic_ad_voice 类型 call_to_action 类型

DYNAMIC

CALL_NOW


GET_DIRECTIONS

STORY_OWNER

CALL_NOW


GET_DIRECTIONS


LEARN_MORE


MESSAGE_PAGE


ORDER_NOW


SHOP_NOW

示例

提供使用动态公共主页名称和城市的广告创意：

curl \
  -F 'dynamic_ad_voice=DYNAMIC' \
  -F 'object_story_spec={ 
    "page_id": "<PARENT_PAGE_ID>", 
    "template_data": { 
      "description": "Ad Description", 
      "link": "<URL>", 
      "message": "Ad Message for {{page.location.city}}", 
      "name": "{{page.name}}", 
      "picture": "<IMAGE_URL>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

包含地图图卡的广告创意

如要使用地图图卡，请在广告创意的 child_attachments 字段中将 place_data 结构作为附件添加。

在本示例中，包含 Facebook 店铺定位工具链接的地图是 child_attachments 数组中的第二项。除了地图图卡以外，您还必需至少提供一个项目。

curl \
  -F 'dynamic_ad_voice=DYNAMIC' \
  -F 'object_story_spec={ 
    "page_id": "<PARENT_PAGE_ID>", 
    "template_data": { 
      "description": "Ad Description", 
      "link": "<URL>", 
      "message": "Ad Message for {{page.location.city}}", 
      "name": "{{page.name}}", 
      "child_attachments":[
        {
          "description": "Come visit us!",
          "link": "http://yourweburl.com",
          "name": "{{page.location.street_address}} - {{page.location.city}}",
          "call_to_action": {
            "type":"GET_DIRECTIONS"
          },
        },
        {
          "link": "https://fb.com/store_locator",
          "name": "Check out our stores.",
          "place_data": {
            "type":"DYNAMIC"
          },
        }
      ]
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

将店铺定位工具用作链接目标页

创建广告时，如果您将 link 设置为“https://fb.com/store_locator”，则广告会显示店铺定位工具，并将其作为链接目标页。

第 5 步：创建广告

使用如下代码创建广告：

curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads

如需创建店铺客流量广告，您的公共主页和广告帐户必须通过审核，能够使用店铺访问量成效衡量。否则，将出现类似于 Reach estimate isn't available because 'store_visits' isn't a valid action type 的错误。

店铺访问量成效衡量

店铺访问量是一个预估的指标，将根据启用定位服务的用户提供的数据得出。Facebook 最终会提供店铺访问量成效衡量和针对店铺客流量目标的优化。店铺访问量成效衡量仅适用于使用店铺客流量目标的广告系列。

在衡量店铺访问量时，将依据使用店铺客流量目标的广告的点击量和查看量。这是一个预估指标，根据帐户管理中心帐户查看或点击每个店铺广告的情况预估广告主的店铺访问数量。您可以配置统计时间窗；您可以根据 1 天、7 天或 28 天点击量或查看量对其进行自定义。如果您未自定义相关配置，系统将应用广告帐户的默认统计时间窗。请参阅成效分析 API 下的“统计时间窗”部分。

这些功能与下列指标的报告有关：

  • 店铺访问量——广告为您的店铺带来的预估访问量。
  • 单次店铺访问费用——广告为您的店铺带来的每次访问的大致平均花费。

使用广告管理工具

查看 ENGAGEMENT: ACTIONS 下显示的数据。即可了解店铺访问量和单次店铺访问费用。

注意：店铺访问量数据仅适用于 Facebook 团队确认可以衡量其广告系列的店。

利用成效分析 API

您可以通过成效分析 API 获取有关店铺访问量的数据。我们在常规成效分析 API 调用中提供两个额外的字段：cost_per_store_visit_action 和 store_visit_actions。请参阅参考资料的“成效分析”部分。

参数

字段说明
point_estimate
int32

The point prediction of the value

默认