酒店廣告:目錄及摘要

若要在 Facebook 上推廣您的酒店庫存,您必須與 Facebook 分享您的酒店資訊。您可以建立酒店目錄,然後填入酒店即可完成此操作。填寫和更新目錄的方法有兩個:

您可以在商務管理工具中建立和管理您的酒店目錄。

若要使用 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

目錄中酒店的不重複識別碼。此編號將與您的 hotel 應用程式和像素事件所提供的任何 content_ids 配對。秘訣:為提高成效,請避免在此不重複識別碼欄位使用空格。請勿使用重複的編號。

範例:FB_hotel_1234

room_id

類型:字串

若要加入酒店客房資訊,此為必要項目

為酒店房型輸入不重複編號。字元上限:100 範例FB_hotel_room_1234

name

類型:字串

此為必要項目。

酒店最常用的名稱。

範例:Facebook Hotel

description

類型:字串

此為必要項目。

大小上限:5000

酒店的簡短描述。

範例: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 物件參數

image[0].tag

類型:物件

請參閱 Image 物件參數

brand

類型:字串

此為必要項目。

連鎖酒店的品牌名稱。

範例:Hilton

address

類型:物件

請參閱 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 Rating 物件參數

guest_ratings.rating_system

類型:物件

請參閱 Guest Rating 物件參數

star_rating

類型:浮點

請參閱 Guest Rating 物件參數

loyalty_program

類型:字串

此為選用項目。

在酒店住宿時用以賺取積分的會員計劃。

範例:Premium program

margin_level

類型:整數

此為選用項目。

酒店盈利能力的指標,數值介乎 1 至 10。

範例:9

phone

類型:字串

此為選用項目。

酒店的主要電話號碼。

範例:+61 296027455

applink

類型:物件

此為選用項目。

使用應用程式連結的深層連結,可直達您流動應用程式中的酒店詳情頁面。您可以指定深層連結(由高至低的優先順序):

  1. 廣告級別使用 template_url_spec
  2. 在此摘要中使用 Applink 物件
  3. 在您的網站加入應用程式連結中繼標籤

進一步了解商品深層連結

priority

類型:整數

此為選用項目。

酒店優先順序的指標,數值介乎 0(最低)至 5(最高)。範例:5

category

類型:字串

此為選用項目。

物業類型。此類別可為所需的任何類型內部說明。範例:ResortDay Room

number_of_rooms

類型:整數

此為選用項目。

此酒店資訊中的房間/單位總數。

範例:150

status

類型:字串

控制某商品在您目錄中的狀態為「銷售中」還是「已封存」。用戶在您的廣告、商店或任何其他渠道中只會看到處於「銷售中」狀態的商品。支援的值:activearchived。在預設情況下,商品均會處於「銷售中」狀態。進一步了解如何封存商品


範例:active


備註:某些合作夥伴平台(例如 Shopify)可能會將商品同步到您的目錄,並將此等商品的狀態設為「預覽」,其效果與 archived 相同。

此欄位的舊稱為 visibility。雖然我們仍支援此欄位的舊稱,但建議您使用新的名稱。

custom_label_0
custom_label_1
custom_label_2
custom_label_3
custom_label_4

類型:字串

字元上限:100

其他資訊的自訂欄位,最多 5 個,可供您在建立商品組合時篩選商品。舉例來說,您可使用自訂欄位來指明所有屬於夏季特價促銷的客房,然後將這些商品篩選為單一商品組合。此欄位支援任何文字值,包括數字。


範例: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

Image 物件參數


欄位名稱與類型說明

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 物件參數

address 等巢狀或多重值欄位可使用 JSON 編碼值表示,或由一組使用 JSON 路徑語法標記的「扁平化」純文字直欄表示,例如 address.region。您可以在同一個檔案中交替使用這兩種慣常做法。


欄位名稱與類型說明

addr1address.addr1

類型:物件

此為必要項目。

酒店的主要街道地址。

範例:1600 Pennsylvania Avenue

address.addr2

類型:物件

此為選用項目。

酒店的次要街道地址。

範例:Apartment 1

address.addr3

類型:物件

此為選用項目。

酒店的三級街道地址。

範例:Downstairs

address.city_idcity_id

類型:字串

此為選用項目。

用於廣告創意深層連結網址 template_url 的值。

範例:12345

address.citycity

類型:字串

此為必要項目。

酒店所在城市。

範例:New York

address.regionregion

類型:字串

此為必要項目。

酒店所在的州份、縣或省份。

範例:California

address.countrycountry

類型:字串

此為必要項目。

酒店所在的國家/地區。

範例:United States

address.postal_codepostal_code

類型:字串

若國家/地區使用郵遞區號系統,此為必要項目

酒店的郵遞區號。

範例:94125NW1 3FG

Guest Rating 物件參數


欄位名稱與類型說明

guest_ratings.scorescore

類型:物件

此為選用項目。

評論過您酒店的總人數。若指定此欄位,您必須同時提供 scoremax_scorenumber_of_reviewersrating_system

範例:9.0/10

guest_ratings.number_of_reviewersnumber_of_reviewers)類型:整數

此為選用項目。

已為此酒店評分的總人數。

範例:5287

guest_ratings.rating_systemrating_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 的倍數。