变量和条件

酒店广告和免费预订链接均包含指向用户可预订客房的着陆页的链接。您可以定义 Google 构建链接的方式,以包含有关用户及其行程的所有额外信息。例如,您可以在网址中添加酒店 ID、语言、货币代码和入住日期等信息。

概览

您可以在着陆页文件中定义着陆页网址。当展示广告或免费预订链接时,网址中的动态信息会替换为实际值。要向着陆页网址添加动态值,请使用以下语法:

<URL>https://partner_url?param_id=(variable_name)</URL>

以下示例显示的网址使用 Google 的变量名称,而不是实际的酒店 ID 和行程:

<URL>https://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID)
  &amp;checkinDay=(CHECKINDAY)&amp;checkinMonth=(CHECKINMONTH)
  &amp;checkinYear=(CHECKINYEAR)&amp;nights=(LENGTH)
</URL>

为搜索结果页构建着陆页链接时,Google 会将变量替换为实际值,以确保网址包含动态信息。例如,如果用户从 2023 年 5 月 23 日开始为 42 号酒店预订了 6 晚的客房,Google 会将先前的链接呈现如下:

https://www.partnerdomain.com?hotelID=42&checkinDay=23&checkinMonth=05&checkinYear=2023&nights=6

Google 为查询字符串中的变量分配的值取决于酒店价格 Feed、酒店列表 Feed 和用户设置中的相应数据。

例如,LENGTH 变量的值会分配给相关行程的价格 Feed 中的 <Nights> 元素。同样,PARTNER-HOTEL-ID 变量的值在酒店列表 Feed 中与用户搜索条件匹配的 <id> 元素中定义。

部分变量是价格 Feed 元素的子集。例如,CHECKINDAYCHECKINMONTHCHECKINYEAR 变量是从价格 Feed 中的单个 <Checkin> 元素中提取的。其他变量则根据用户的语言区域和其他客户端设置计算得出。

如需详细了解变量值的来源,请参阅价格概览酒店列表

网址变量

下表介绍了可用于构建着陆页网址的变量:

变量 推荐/可选 说明
ADVANCE-BOOKING-WINDOW Optional 距离入住日期提前多少天(以预订时酒店所在的时区为准)。例如 36
ALTERNATE-HOTEL-ID Recommended (if you have separate IDs to identify properties versus booking engines) 房源的备用标识符。此属性名称在您的酒店列表 Feed 中指定。如果您需要一个房源标识符用于 Feed 信息,而另一个房源标识符用于预订引擎,则使用单独的 ID 会非常有用。
CAMPAIGN-ID Recommended 要与该网址关联的 Google Ads 广告系列的 ID。如果点击未与 Google Ads 广告系列相关联,则此处为空。
CHECKINDAY Recommended 酒店价格 Feed 的 <Checkin> 元素中定义的两位数日期。例如 20
CHECKINDAY-OF-WEEK Optional 星期几(入住时间:MondaySunday,酒店所在时区)。例如:Tuesday
CHECKINMONTH Recommended 酒店价格 Feed 的 <Checkin> 元素中定义的两位数月份。例如 05
CHECKINYEAR Recommended 酒店价格 Feed 的 <Checkin> 元素中定义的四位数年份。例如 2023
CHECKOUTDAY Recommended 根据酒店价格 Feed 的 <Nights><Checkin> 元素计算得出的两位数日期。例如 26
CHECKOUTMONTH Recommended 根据酒店价格 Feed 的 <Nights><Checkin> 元素计算得出的两位数月份。例如 05
CHECKOUTYEAR Recommended 根据酒店价格 Feed 的 <Nights><Checkin> 元素计算得出的四位数年份。例如 2023
CHILD-AGE Recommended (must be provided for child occupancy pricing) 价格 Feed 的 <Child "age"> 元素中指定的每个子项的最长存在时间。 此变量必须与 FOR-EACH-CHILD-AGE 条件块结合使用。
CHILD-INDEX Optional 从 0 开始计数的循环变量,表示行程中指定的每个儿童乘员和每个儿童年龄的计数器。虽然并非强制性要求,但此变量只能与 FOR-EACH-CHILD-AGE 条件块结合使用。
CLICK-TYPE Optional 指明用户点击的是标准酒店房价还是客房套餐。可能的值如下:
  • hotel:用户点击了标准房价的列表。
  • room:用户点击了 Room 软件包的列表。
CLOSE-RATE-RULE-IDS Optional (only applies if you are using conditional or private rates) 以逗号分隔的费率规则 ID 列表,用于列出不可用但用户执行过小操作时可用的费率。请注意,当向用户显示相应的界面处理方式时,不公开费率的费率规则 ID 始终必须在此处填充。
CUSTOM[1-5] Optional <Result> 元素中定义的自定义字段的值,每个自定义字段的字符数上限为 200。如需了解详情,请参阅事务消息概览。使用 ARI 时,自定义字段不可用。
DATE-TYPE Optional 指明用户选择了默认日期还是搜索中提供的特定日期。可能的值如下:
  • default:用户点击了使用默认日期的酒店广告或免费预订链接。
  • selected:用户点击了已设置日期的酒店广告或免费预订链接。
GOOGLE-SITE Optional 用户查看您的酒店定价数据时所用的 Google 产品和服务。 可能的
    值如下:
  • localuniversal:用户通过 google.com 搜索找到了酒店预订链接。
  • mapresults:用户通过 maps.google.com 找到了酒店预订链接。
  • verification:Google 在对您的网站执行自动化数据质量测试时会使用此值。您无需为这些查询付费。Google Analytics(分析)可以使用此参数及其值来识别酒店广告自动验证流量。
  • unknown:用户通过无法确定来源发现了广告或免费预订链接。
LENGTH Recommended 住宿晚数,以酒店价格 Feed 中的 <Nights> 元素定义的住宿晚数表示。例如 3
NUM-ADULTS Recommended (must be used with the NUM-CHILDREN or FOR-EACH-CHILD-AGE condition) 用户为行程指定的成人入住人数。 此变量必须与 NUM-CHILDREN 和/或 FOR-EACH-CHILD-AGE 结合使用。
NUM-CHILDREN Recommended 用户在行程中指定的儿童入住人数(0 - 17 周岁)。需要 NUM-CHILDREN 和/或 FOR-EACH-CHILD-AGE 才能成功参与有儿童乘客的行程。
NUM-GUESTS Recommended (if you don't send child occupancy pricing) 用户为行程指定的入住人数(包括成人和儿童)。此值是 NUM-ADULTS 值和 NUM-CHILDREN 值的总和。为了最大限度地提高参与率,强烈建议同时使用 NUM-ADULTSNUM-CHILDREN
PACKAGE-ID Recommended (applies if you use Room Bundles) 酒店价格 Feed 中套餐的唯一标识符。对于标准软件包,软件包 ID 是 <Result> 块中 <PackageID> 元素的值。对于客房套餐,软件包 ID 是 Transaction 消息的 <RoomBundle><PackageData> 块中 <PackageID> 元素的值。
PARTNER-CURRENCY Optional 由三个字母组成的货币代码,由酒店价格 Feed 中的 <Baserate> 元素的 currency 属性定义。例如 USDCAD
PARTNER-HOTEL-ID Recommended 酒店的唯一标识符,由酒店列表 Feed 中的 <id> 元素定义。
PARTNER-ROOM-ID Recommended (applies if you use Room Bundles) 酒店价格 Feed 中客房的唯一标识符。对于标准客房,客房 ID 是 <Result> 块中 <RoomID> 元素的值。对于客房套餐,客房 ID 是为交易消息的 <RoomBundle><RoomData> 块中的 <RoomID> 元素分配的值。
PAYMENT-ID Optional (only applies to Ads) 如果您使用佣金追收代理机构,则解析为预定义的字符串 commission 或 Google 分配的 IATA 编号(例如“01234567”)。要更改 IATA 编号或预定义字符串的格式,请与您的技术支持客户经理 (TAM) 联系。
PRICE-DISPLAYED-TAX (Optional) 向用户显示的税费金额(以用户的本地货币表示)。 PRICE-DISPLAYED-TAX 的值是酒店价格 Feed 中 <Tax> 元素的值。例如,"3.14"。
PRICE-DISPLAYED-TOTAL (Optional) 向用户显示的客房总费用(以用户的本地货币为单位)。PRICE-DISPLAYED-TOTAL 的值是酒店价格 Feed 中的 <Baserate><Tax><OtherFees> 元素的总和。 例如,"152.13"。
PROMO-CODE (Optional)

如果您使用 ARI 促销,则此变量的值会分配给所应用的 <Promotion>id 属性。如果应用了多个促销活动,则系统会显示按任意顺序排列的促销 ID 列表(以英文逗号分隔)。

如果您使用 费率规则,且应用了相应的费率规则,则此变量的值会分配给 PromoCode 元素。

RATE-PLAN-ID Recommended (only applies if you use RoomBundles) 由价格 Feed 的 <RoomBundle> 块中的 <RatePlanID> 元素定义的 ID。<RatePlanID> 表示客房和套餐数据组合的唯一标识符。如需了解详情,请参阅 Room 软件包
RATE-RULE-ID Recommended (only applies if you use conditional rates or private rates) 由价格 Feed 的 <Rate> 块中的 rate_rule_id 属性定义的 ID。如需了解详情,请参阅 条件式费率

注意:仅显示条件式费率或未隐藏的不公开费率。

USER-COUNTRY Recommended 表示用户所在位置的两个字母的国家/地区代码。此信息提取自用户的客户端设置。例如 USFR
USER-CURRENCY Recommended 由三个字母组成的货币代码,表示用户的本地货币。USER-CURRENCY 变量的值是根据用户的客户端设置推断出来的。例如 USDCAD
USER-DEVICE Recommended 用户的设备类型。USER-DEVICE 的值可以是以下值之一:
  • mobile
  • tablet
  • desktop
  • unknown

USER-DEVICE 变量的值是根据用户的客户端设置推断出来的。

USER-LANGUAGE Recommended 两个字母的 ISO 639-1 语言代码,用于指定广告或免费预订链接的显示语言。USER-LANGUAGE 变量的值是根据用户的客户端设置推断出来的。例如 enfr
USER-LIST-ID(在 Google Ads 中定义) Optional (only applies if you use Audience Lists in Google Ads) 包含受众群体名单或用户信息的 Google Ads 用户名单 ID。受众群体名单是设置出价调整的基础。如果用户属于多个受众群体名单,系统会选择出价调整幅度最大的受众群体名单。出价调整幅度最高的受众群体之间的联系由系统随机决定。
VERIFICATION Optional 一个布尔值,用于验证链接是否由 Google 生成,用于测试还是自动验证。如果链接由 Google 生成用于测试或自动验证,则为 true,否则为 false

网址中的条件逻辑

您可以在着陆页文件的 <URL> 元素中使用特殊指令,以有条件地构建端点。

条件逻辑支持以下语句:

  • if_statement:如果为 true,则将遵循此条件的值插入到网址中,否则会插入 ELSE 指令之后的值。

  • for_statement:创建一个 FOR 循环条件,用于迭代提供的值的数量。

IF 和 FOR 语句包括:

条件 推荐/可选 说明
IF-AD-CLICK(仅限酒店广告) Optional 如果用户点击源自广告,则解析为 true。 如果用户点击源自免费的预订链接,则解析为 false
IF-CLICK-TYPE-HOTEL Optional 如果用户点击了酒店的商家信息,则解析为 true,否则解析为 false
IF-CLICK-TYPE-ROOM Optional 如果用户点击 Room Bundle 的列表,则解析为 true,否则解析为 false
IF-CLOSE-RATE-RULE-IDS Optional 如果一个或多个条件式费率因用户不符合条件而不可用,则解析为 true,否则解析为 false。默认情况下,如果向用户显示了不公开费率 界面处理方式,该值为 true
IF-DEFAULT-RATE Optional 如果用户点击了使用了默认日期的酒店商家信息,则解析为 true,否则解析为 false
IF-HOTEL-CAMPAIGN Optional 如果用户点击源自酒店广告系列,则解析为 true,否则解析为 false。对于在 Google Ads 中拥有多种广告系列类型的合作伙伴而言,这种区别有助于分配归因。
IF-PAYMENT-ID(仅限酒店广告) Recommended (if you use pay-per-stay Google Ads campaigns) 对于参与按入住付费 (PPS) 佣金计划的酒店,解析为 true;否则,此解析将解析为 false
IF-PROMO-CODE Optional 如果用户点击的费率基于 ARI 促销或具有指定 PromoCode 的费率规则,则解析为 true;否则解析为 false
IF-PROMOTED(仅限酒店广告) Recommended (if you use Promoted hotels) 如果用户点击了酒店宣传广告,则解析为 true,否则解析为 false
IF-RATE-RULE-ID Optional 如果用户选择了条件式费率 ,则解析为 true,否则解析为 false
IF-USER-LIST-ID(在 Google Ads 中定义) Optional 如果用户是您在为受众群体名单设置出价调节系数时指定的 Google Ads 客户名单 ID 的成员,则解析为 true,否则解析为 false
IF-VERIFICATION Optional 如果链接是由 Google 生成的用于测试或自动验证的链接,则解析为 true,否则解析为 false
ELSE Recommended (if you use any conditional IF statements) 如果不满足前面的条件,则遵循此条件的值会插入到网址中。
END-IF Optional (required if you have any IF conditional statements) 结束 IF 语句条件块。
FOR-EACH-CHILD-AGE Optional (required for child occupancy pricing) 针对价格 Feed 中的每个 <Child "age"> 元素执行一次。例如,如果 <OccupancyDetails> 包含 <Child age="17"><Child age= "17"> 这两个元素,则该指令会执行两次。
END-FOR-EACH Optional (required if using FOR-EACH block) 结束 FOR-EACH 语句条件块。

IF-AD-CLICK 示例

您可以构建一个条件块,用于检查用户是否点击了广告或免费的预订链接来重定向到您的着陆页。

以下示例在着陆页文件中使用此指令:

<URL>https://partner.com?hid=(PARTNER-HOTEL-ID)(IF-AD-CLICK)&amp;adType=1(ELSE)&amp;adType=0(ENDIF)</URL>

在此示例中,如果用户未点击广告,结果将如下所示:

https://www.partner.com?hid=123&adType=0

如果用户点击了广告,结果将如下所示:

https://www.partner.com?hid=123&adType=1

IF-CLICK-TYPE-HOTEL 示例

您可以构建一个条件块,用于检查用户是否选择了酒店套餐而无需明确的客房套餐。交易消息的 <Room Bundle> 块中 <RatePlanID> 元素的值将设置为用户选择的隐式关联的客房套餐价格。

以下示例在着陆页文件中使用此指令:

<URL>https://partner.com/(IF-CLICK-TYPE-HOTEL)landing(ELSE)landing_room(ENDIF)?hid=(PARTNER-HOTEL-ID)</URL>

在此示例中,如果用户选择了 Room Bundle,则结果将如下所示:

https://partner.com/landing_room?hid=123

如果用户未选择客房套餐,结果将如下所示:

https://partner.com/landing?hid=123

IF-CLICK-TYPE-ROOM 示例

您可以构建一个条件块,用于检查用户是否选择了 Room 软件包。

以下示例在着陆页文件中使用此指令:

<URL>https://partner.com/(IF-CLICK-TYPE-ROOM)landing_room(ELSE)landing(ENDIF)?hid=(PARTNER-HOTEL-ID)</URL>

在此示例中,如果用户未选择 Room Bundle,则结果将如下所示:

https://partner.com/landing?hid=123

如果用户选择了客房套餐,结果将如下所示:

https://partner.com/landing_room?hid=123

IF-DEFAULT-DATE 示例

使用 IF-DEFAULT-DATE 条件语句设置一个非日期参数,然后您的网站可以在用户未选择日期时利用该参数触发自定义行为。

以下示例检查是否使用了默认日期:

<URL>https://partner.com?hotelID=(PARTNER-HOTEL-ID)&amp;checkinDay=(CHECKINDAY)&amp;checkinMonth=(CHECKINMONTH)&amp;checkinYear=(CHECKINYEAR)&amp;nights=(LENGTH)<strong>(IF-DEFAULT-DATE)</strong>&amp;popup_datepicker=true(ELSE)&amp;popup_datepicker=false(ENDIF)</URL>

在此示例中,如果用户未选择日期,结果可能与以下显示默认日期选项的网址类似:

https://partner.com?hotelID=123&checkinDay=23&checkinMonth=05&checkinYear=2023&nights=1&popup_datepicker=true

如果用户选择了一个日期,结果可能与以下网址类似,具体取决于用户选择的行程:

https://partner.com?hotelID=123&checkinDay=23&checkinMonth=05&checkinYear=2023&nights=2&popup_datepicker=false

IF-HOTEL-CAMPAIGN 示例(酒店广告和免费预订链接点击)

您可以构建一个条件块,用于检查用户是否点击了源自酒店广告系列的广告。

以下示例在着陆页文件中使用此指令:

<URL>https://partner.com?hotelID=(PARTNER-HOTEL-ID)(IF-HOTEL-CAMPAIGN)&amp;hotel_campaign=(CAMPAIGN-ID)(ELSE)utm_campaign=(CAMPAIGN-ID)(ENDIF)</URL>

在此示例中,如果用户点击某个酒店广告系列网址,结果将如下所示:

https://www.partner.com?hotelID=123&hotel_campaign=12345678

如果点击的不是酒店广告系列网址(例如常规搜索广告系列),结果将显示为以下网址:

https://www.partner.com?hotelID=123&utm_campaign=87654321

如果您想区分酒店广告系列点击的流量与任何其他点击,这会非常有用。

FBL 点击次数出现空白的 CAMPAIGN-ID

如果点击来自免费的预订链接,则 IF-HOTEL-CAMPAIGN 会返回 TRUE,并且 CAMPAIGN-ID 值会留空,如以下网址所示:

https://www.partner.com?hotelID=123&hotel_campaign=

您可以使用 IF-AD-CLICK 条件语句来防止广告系列 ID 为空,如以下示例所示:

<URL>https://partner.com?hotelID=(PARTNER-HOTEL-ID)(IF-HOTEL-CAMPAIGN)(IF-AD-CLICK)&amp;hotel_campaign=(CAMPAIGN-ID)(ELSE)&amp;FreeBookingLink(ENDIF)(ELSE)utm_campaign=(CAMPAIGN-ID)(ENDIF)</URL>

IF-PAYMENT-ID 示例(仅限酒店广告)

使用 IF-PAYMENT-ID 条件语句,根据点击是否来自 PPS 佣金计划来更改网址。以下示例会检查点击是否来自 PPS 佣金计划,并根据结果为 booking_source 参数分配一个值:

<URL>https://partner.com?hid=(PARTNER-HOTEL-ID)&amp;booking_source=(IF-PAYMENT-ID)(PAYMENT-ID)(ELSE)cpc(ENDIF)</URL>

如果酒店加入了“佣金”计划,结果将是以下网址之一:

  • 如果没有向 Google 分配 IATA 号码:
    https://partner.com?hid=123&amp;booking_source=commissions
  • 如果 IATA 编号已分配给 Google:
    https://partner.com?hid=123&amp;booking_source=01234567

否则,结果将如下所示:

https://partner.com?hid=123&booking_source=cpc

IF-PROMOTED 示例(仅限酒店广告)

您可以构建一个条件块,用于检查用户是否点击了酒店宣传广告。

以下示例在着陆页文件中使用此指令:

<URL>https://partner.com/(IF-PROMOTED)1(ELSE)0(ENDIF)?hid=(PARTNER-HOTEL-ID)</URL>

在此示例中,如果用户选择了酒店宣传广告,结果将如下所示:

https://partner.com/1?hid=123

如果用户未选择酒店宣传广告,结果将如下所示:

https://partner.com/0?hid=123

IF-RATE-RULE-ID 示例

您可以构建一个条件块,用于检查用户是否选择了条件式费率;如果是,系统会使用交易消息的 <Rate> 块中 <RateRuleID> 元素的值。

以下示例在着陆页文件中使用此指令:

<URL>https://partner.com?hid=(PARTNER-HOTEL-ID)(IF-RATE-RULE-ID)&amp;customerType=42(ELSE)(ENDIF)</URL>

在此示例中,如果用户未选择条件式费率,结果将如下所示:

https://www.partner.com?hid=123

如果用户选择了条件式费率,结果将如下所示:

https://www.partner.com?hid=123&customerType=42

IF-USER-LIST-ID 示例(在 Google Ads 中定义)

如果您在 Google Ads 中为酒店广告系列中的受众群体名单设置出价调节系数,则可以将 IF-USER-LIST-IDUSER-LIST-ID 结合使用,以在您的网站上为属于特定 Google Ads 受众群体名单的客户设置参数。您可能需要这样做,以便进行跟踪,或者为受众群体名单成员自定义您的网站。

<URL>https://partner.com/?hid=(PARTNER-HOTEL-ID)(IF-USER-LIST-ID)&amp;audience_list=(USER-LIST-ID)(ELSE)(ENDIF)</URL>

在此示例中,如果用户不是受众群体名单的成员,则结果将如下所示:

https://www.partner.com?hid=123

如果用户曾是受众群体名单 12345678 的成员,结果将如下所示:

https://www.partner.com?hid=123&audience_list=12345678

IF-VERIFICATION 示例

如果您需要检查 Google 生成的网址是用于测试还是自动验证,则可以使用 IF-VERIFICATION

<URL>https://partner.com/?hid=(PARTNER-HOTEL-ID)(IF-VERIFICATION)&amp;isgoogle=true(ENDIF)</URL>

在此示例中,如果 Google 未生成用于测试或验证的网址,则结果将如下所示:

https://www.partner.com?hid=123

如果 Google 生成了网址用于测试或验证,结果将如下所示:

https://www.partner.com?hid=123&isgoogle=true

FOR-EACH-CHILD-AGE 示例

您可以构建一个条件块,用于填充酒店价格 Feed 中每个儿童入住人数的最大年龄。

以下示例在着陆页文件中使用此指令:

<URL>https://partner.com?adults=(NUM-ADULTS)&amp;children=(NUM-CHILDREN)(FOR-EACH-CHILD-AGE)&amp;age=(CHILD-INDEX)_(CHILD-AGE)(END-FOR-EACH)&amp;hid=(PARTNER-HOTEL-ID)&amp;</URL>

在此示例中,如果行程中分别有 2 名成人和 2 名 0 和 17 周岁的儿童,结果将如下所示:

https://www.partner.com?adults=2&children=2&age=0_0age=1_17&hid=123

如果行程有 2 名成人和 0 名儿童,则结果为以下网址:

https://www.partner.com?adults=2&children=0&hid=123

构建网址时的一般规则

所有变量都是可选的。您无需在着陆页网址中插入任何变量。不过,使用变量传递行程和用户信息通常可以为用户提供更好的体验,并帮助您遵守 Google 的政策。

在着陆页文件中定义构建的网址时,需遵循以下一般规则:

  • 所有变量都用左括号和右括号括起来。

  • 查询字符串参数只能在网址中的问号(“?”)后面传递。

  • 在最终输出中,查询字符串参数必须使用和号(“&”)分隔。因为和号是 XML 中的特殊字符,且着陆页文件格式是 XML。因此,您必须使用编码实体“&amp;”来代替它。最终输出会呈现实际的“&”字符。 例如:

    <!-- Do this: -->
    <URL>https://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID)&nights=(LENGTH)</URL>
    
    <!-- Do NOT do this: -->
    <URL>https://www.partnerdomain.com?hotelID=(PARTNER-HOTEL-ID)&nights=(LENGTH)</URL>
    

    此外,您还必须对可能包含在着陆页网址中的特殊字符进行网址编码。例如:

    • 空格(“ ”):将 <URL> 元素中的空格字符替换为“%20;”
    • 正斜杠(“/”):将 <URL> 元素中的正斜杠替换为“%2F;”

    并非所有非字母字符都必须经过网址编码。例如,连字符(“-”)无需进行网址编码。如需查看必须进行网址编码的常见字符列表,请参阅网址编码表

  • 单个参数的值可以由多个变量构成。以下示例通过 CHECKINDAYCHECKINMONTHCHECKINYEAR 变量构造了一个参数 checkinDate

    <URL>https://www.partnerdomain.com?checkinDate=(CHECKINDAY)%2F;(CHECKINMONTH)%2F;(CHECKINYEAR)</URL>
    

    该示例生成的网址可能如下所示:

    https://www.partnerdomain.com?checkinDate=7/23/1971
    
  • 您可以使用任意 ID 作为查询字符串参数的名称。您的服务器会处理这些值。但是,您传递的值仅限于可用变量列表

  • 除可用变量列表外,您最多可以使用 5 个自定义变量。