酒店广告 - 目录和信息库

要在 Facebook 推广酒店库存,必须与 Facebook 分享您的酒店信息。方法是:创建酒店目录,然后填写酒店信息。您可通过以下 2 种方式填写和更新目录:

您可以在电商管理工具中创建和管理酒店目录。

如需使用此 API 管理目录,请按照以下步骤操作:

  1. 创建酒店目录
  2. 根据酒店目录创建商品系列
  3. 将目录与事件源关联

酒店信息库 - 向 Facebook 上传酒店信息库

酒店信息库是一份包含酒店库存的文件。此文件中的每一行或每一个项目均代表一家酒店。您可以使用一个或多个酒店信息库,前提是您的全部酒店库存都包含在这些信息库中。

支持的酒店信息库格式

CSV

CSV 示例 | TSV 示例(平展) | TSV 示例(JSON 格式)

  • 第一行必须按照赋值顺序列出选定的字段名称。然后,后面的每行为每家酒店提供相应的值。
  • 如果字段包含空格或逗号,应使用双引号 "" 将该字段括起来。
  • 嵌套字段或多值字段(如 addressneighborhoodimage)可使用 JSON 编码值表示,也可以通过由 JSON 路径语法标记的一组“平展”纯文本列表示(例如:address.cityneighborhood[0]image[0].urlimage[0].tag[0]image[0].tag[1])。您可以在同一个文件中交替使用这两种惯例做法。

XML

XML 示例

  • 一个根 <listings> XML 节点可包含一组 <listing> 节点,其中的每个节点均代表一个酒店。
  • 文件必须以有效的 <?xml 声明标签开头。

信息库解析器会自动检测 UTF8UTF16UTF32 文本编码,并在遇到陌生字节串时默认使用 LATIN1。您可以使用任何语言添加字段值文本,不过字段名称必须使用英文严格按下方所示填写。

支持的字段 — 酒店广告

以下支持的字段可用于要添加到商品目录中的项目。

有关本地化目录,请参阅酒店广告支持的字段

字段和类型描述

hotel_id

类型:字符串

必要

字符数上限:100

目录中酒店的唯一标识符。这一编号将匹配 content_ids 应用和 Pixel 像素代码事件中提供的任何 hotel提示:为提升广告表现,请避免在该唯一标识符字段中使用空格。请不要使用重复的编号。

示例:FB_hotel_1234

room_id

类型:字符串

如要添加酒店客房信息,则为必要项

输入酒店客房类型的唯一编号。字符数量限制:100 示例FB_hotel_room_1234

name

类型:字符串

必要

酒店最常用的名称。

示例:Facebook Hotel

description

类型:字符串

必要

字符数上限:5,000

酒店简介。

示例:Only 30 minutes away from San Francisco.

checkin_date

类型:字符串

如要添加酒店客房信息,则为必要项

酒店入住日期。自信息库上传之日起,您最多可以添加 180 天的适用期。采用 ISO-8601 标准 (YYYY-MM-DD)。

示例:2017-08-01

length_of_stay

类型:字符串

如要添加酒店客房信息,则为必要项

酒店入住天数。

示例:7

base_price

类型:字符串

如要添加酒店客房信息,则为必要项

酒店客房每晚的基本价格。请务必为价格添加货币类型(例如,USD 代表美元)。将价格的格式设置为价格数值后加 ISO 货币代码,价格数值与货币单位之间应留有一个空格。

示例:199.00 EUR

price

类型:字符串

如要添加酒店客房信息,则为必要项

酒店入住总价格,以 checkin_datelength_of_stay 为依据。将价格的格式设置为价格数值后加 ISO 货币代码,价格数值与货币单位之间应留有一个空格。

示例:1393.00 USD

tax

类型:字符串

如要添加酒店客房信息,则为必要项

客房价格适用的税率。将价格的格式设置为价格数值后加 ISO 货币代码,价格数值与货币单位之间应留有一个空格。

示例:14.00 USD

fees

类型:字符串

如要添加酒店客房信息,则为必要项

客房价格适用的费用。将价格的格式设置为价格数值后加 ISO 货币代码,价格数值与货币单位之间应留有一个空格。

示例:253.00 USD

url

类型:字符串

必要

外部网站客房预订页面的链接。您也可以使用 template_url_spec广告层级指定网址。广告层级的网址优先于信息库中的网址。

示例:https://www.facebook.com/hotel

image[0].url

类型:对象

请参阅图片对象参数

image[0].tag

类型:对象

请参阅图片对象参数

brand

类型:字符串

必要

连锁酒店的品牌名称。

示例:Hilton

address

类型:对象

请参阅地址对象参数

neighborhood[0]

类型:字符串

必要

社区数量限制:20

酒店所在的社区。如果不止一个社区,则应为各个社区添加额外的栏,并在各个栏名称中使用 JSON 路径语法标明社区编号。

示例:Belle Haven

latitude

类型:浮点数

必要

酒店所在地的纬度。

示例:37.484100

longitude

类型:浮点数

必要

酒店所在地的经度。

示例:-122.148252

sale_price

类型:字符串

非必要

酒店入住每晚的优惠价格,以 checkin_datelength_of_stay 为依据。当您想要宣传酒店的折扣价(区别于正常价格)时,使用此字段。确保为价格添加货币类型(例如,USD 代表美元)。确保酒店的 sale_price 低于其 base_price。将价格的格式设置为价格数值后加 ISO 货币代码,价格数值与货币单位之间应留有一个空格。

示例:149.00 USD

guest_ratings.score

类型:对象

请参阅客人评分对象参数

guest_ratings.rating_system

类型:对象

请参阅客人评分对象参数

star_rating

类型:浮点数

请参阅客户评级对象参数

loyalty_program

类型:字符串

非必要

入住此酒店可获得积分的忠诚度计划。

示例:Premium program

margin_level

类型:整数

非必要

酒店盈利能力指标,其值介于 1 - 10 之间。

示例:9

phone

类型:字符串

非必要

酒店的主要电话号码。

示例:+61 296027455

applink

类型:对象

非必要

使用应用链接可直接定向至移动应用中酒店详情页面的深度链接。您可以使用下列方法之一指定深度链接(按降序从高到低):

  1. 广告层级使用 template_url_spec
  2. 在信息库中使用应用链接对象
  3. 为网站添加应用链接元标签

详细了解商品深度链接

priority

类型:整数

非必要

酒店优先级指标,其值范围为 0 - 5(从最低优先级到最高优先级)。示例:5

category

类型:字符串

非必要

房产类型。可以是内部描述所需的任何类型。示例:ResortDay Room

number_of_rooms

类型:整数

非必要

此酒店清单中的客房或套房总数。

示例:150

status

类型:字符串

控制目录中的商品是在展示中还是已归档。仅展示中的商品可对您的广告受众以及店铺或其他任何渠道的用户显示。支持的值:activearchived。默认情况下,商品处于“在售”状态。详细了解如何归档商品


示例:active


注意:部分合作伙伴平台(如 Shopify)将商品同步到您的目录时可能附带 staging 状态,其作用与 archived 相同。

此字段之前被称为 visibility。虽然之前的字段名称仍受支持,但建议您使用新名称。

custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4

类型:字符串

字符数上限:100

最多五个自定义字段,用于在创建商品系列时输入所需的任何附加信息,以作为商品筛选依据。例如,您可以使用一个自定义字段来表示构成某次夏季促销一部分的所有客房,然后将这些商品筛选到一个系列中。此字段支持输入任何文本值,包括数字。


示例:Summer Sale

补充信息库支持此字段。

custom_number_0
custom_number_1
custom_number_2
custom_number_3
custom_number_4

类型:整数

此自定义字段包含任何数字相关附加信息,您最多可添加 5 个此类字段;在创建商品系列时,您可将这些字段的信息作为商品筛选依据。通过此字段,您可以在创建商品系列时按数字大小范围(大于小于)进行筛选。例如,您可以使用此字段来表示一个酒店的开业年份,然后将特定年份范围内的商品筛选到一个系列中。


此字段支持 0 到 4294967295 之间的整数,不支持负数(例如:-2)、小数(例如:5.5)或逗号形式(例如:10,000)。


示例:2022

图片对象参数


字段名称和类型描述

url

类型:字符串

必要

项目数量上限:20。

广告商品图片的网址链接。请遵循以下图片规格:

  • 所有图片必须为 JPG、GIF 或 PNG 格式。

  • 对于轮播广告和精品栏广告:以正方形 (1:1) 格式显示图片。图片大小不得低于 500 x 500 像素。我们推荐使用 1024 x 1024 像素,以展现最佳效果。

  • 对于单张图片广告:以 1.91:1 宽高比格式显示图片。图片大小不得低于 500 x 500 像素。我们推荐使用 1200 x 628 像素,以展现最佳效果。

  • 如果您使用的图片不止一张,则应为每张图片添加额外的栏,并在各个栏名称中使用 JSON 路径语法标明图片编号。

示例:image[0].url; image[1].url

示例:https://www.facebook.com/facebook_hotel.jpg

tag

类型:字符串

非必要

附加到图片上的标签,用于说明图片内容。一张图像可以关联多个标签。

示例:Fitness CenterSwimming Poolsuite

INSTAGRAM_STANDARD_PREFERRED - 让广告主将信息库中的特定图片标记为 Instagram 默认图片。此标签区分大小写。


地址对象参数

嵌套字段或多值字段(如 address)可使用 JSON 编码值表示,也可以通过由 JSON 路径语法标记的一组“平展”纯文本列表示,如 address.region。您可以在同一个文件中交替使用这两种惯例做法。


字段名称和类型描述

addr1 (address.addr1)

类型:对象

必要

酒店的主要街道地址。

示例:1600 Pennsylvania Avenue

address.addr2

类型:对象

非必要

酒店的二级街道地址。

示例:Apartment 1

address.addr3

类型:对象

非必要

酒店的三级街道地址。

示例:Downstairs

address.city_id (city_id)

类型:字符串

非必要

在广告创意中为深度链接网址 template_url 使用的值。

示例:12345

address.city (city)

类型:字符串

必要

酒店所在的城市。

示例:New York

address.region (region)

类型:字符串

必要

酒店所在的州、县、省。

示例:California

address.country (country)

类型:字符串

必要

酒店所在的国家/地区。

示例:United States

address.postal_code (postal_code)

类型:字符串

有邮编系统的国家/地区必需提供

酒店的邮编。

示例:94125NW1 3FG

客人评分对象参数


字段名称和类型描述

guest_ratings.score (score)

类型:对象

非必要

评论过您酒店的总人数。如果已指定,您还必须提供 scoremax_scorenumber_of_reviewersrating_system

示例:9.0/10

guest_ratings.number_of_reviewers (number_of_reviewers) 类型:整数

非必要

为此酒店评分的用户总数。

示例:5287

guest_ratings.rating_system (rating_system)

类型:字符串

非必要

客户评分系统。

示例:ExpediaTripAdvisor

max_score

类型:整数

必要

酒店评分的最大值。必须大于或等于 0,同时小于或等于 100。

示例:10

酒店 API - 直接创建和管理酒店

您可以在目录中使用酒店 API 直接添加、修改和删除酒店。如需详细了解如何使用 API 管理酒店,请参阅酒店 API 参考文档

以下部分仅适用于使用此 API 管理目录的情况。

使用 API 创建酒店目录

酒店目录是一份包含酒店库存的文件。如要使用目录 API,请确保您拥有适当的市场营销 API 访问权限级别,并已通过在商务管理平台中创建首个目录接受服务条款

如需为酒店广告创建酒店目录,请将 vertical 设置为 hotels

curl -X POST \
  -F 'name="Test Hotel Catalog"' \
  -F 'vertical="hotels"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v10.0/BUSINESS_ID/owned_product_catalogs

通过 API 上传酒店信息库

目录创建完成后,您必须将酒店信息库上传到 Facebook。使用 API 为要上传的每个信息库创建一个信息库对象。我们支持定时上传和直接上传。

使用酒店目录筛选出酒店系列

酒店系列属于目录的子集。您需要拥有酒店系列才能设置酒店广告。因此您需要至少创建一个酒店系列。

酒店系列由应用于酒店目录的筛选条件来定义。例如,您可以将 star_rating 高于 3 的所有酒店创建为一个酒店系列。注意:不使用任何筛选条件,您也可以创建酒店系列。在这种情况下,酒店系列将包含目录中所有的酒店。

如要将包含 brand 字段中提到的“示例品牌”的所有酒店创建为一个酒店系列:

curl -X POST \ -F 'name="Test Hotel Set"' \ -F 'filter={ "brand": { "i_contains": "sample brand" } }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v21.0/<PRODUCT_CATALOG_ID>/product_sets
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const ProductCatalog = bizSdk.ProductCatalog; const ProductSet = bizSdk.ProductSet; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<PRODUCT_CATALOG_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Test Hotel Set', 'filter' : {'brand':{'i_contains':'sample brand'}}, }; const product_sets = (new ProductCatalog(id)).createProductSet( fields, params ); logApiCallResult('product_sets api call complete.', product_sets);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\ProductCatalog; use FacebookAds\Object\ProductSet; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<PRODUCT_CATALOG_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Test Hotel Set', 'filter' => array('brand' => array('i_contains' => 'sample brand')), ); echo json_encode((new ProductCatalog($id))->createProductSet( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.productcatalog import ProductCatalog from facebook_business.adobjects.productset import ProductSet from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<PRODUCT_CATALOG_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Test Hotel Set', 'filter': {'brand':{'i_contains':'sample brand'}}, } print ProductCatalog(id).create_product_set( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<PRODUCT_CATALOG_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new ProductCatalog(id, context).createProductSet() .setName(\"Test Hotel Set\") .setFilter(\"{\\"brand\\":{\\"i_contains\\":\\"sample brand\\"}}\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<PRODUCT_CATALOG_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end product_catalog = FacebookAds::ProductCatalog.get(id) product_sets = product_catalog.product_sets.create({ name: 'Test Hotel Set', filter: {'brand':{'i_contains':'sample brand'}}, })

filter 参数由以下运算符与数据组成:

运算符筛选的类型

i_contains

包含子字符串。运算符不分大小写。

i_not_contains

不包含子字符串。运算符不分大小写。

contains

包含子字符串。运算符不分大小写。

not_contains

不包含子字符串。运算符不分大小写。

eq

等于。运算符不分大小写。

neq

不等于。运算符不分大小写。

lt

小于。仅限数字型字段。

lte

小于或等于。仅限数字型字段。

gt

大于。仅限数字型字段。

gte

大于或等于。仅限数字型字段。

数据筛选的数据。

hotel_id

目录中酒店的唯一标识符。

brand

连锁酒店的品牌。

base_price_amount

此酒店每晚的基础价格。价格以美分为单位(4999 表示 49.99 美元)。

sale_price_amount

此酒店每晚的优惠价。价格以美分为单位(4999 表示 49.99 美元)。

currency

货币

city

酒店所在的城市。

country

酒店所在的国家/地区。

name

酒店最常用的名称。

star_rating

酒店星级评定。有效值为 1 - 5,且必须为 0.5 的倍数。