变量和条件

酒店广告和免费的预订链接包含指向可供用户预订客房的着陆页的链接。您可以定义 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:用户点击了客房套餐的列表。
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 是交易消息的 <RoomBundle><PackageData> 块内 <PackageID> 元素的值。
PARTNER-CURRENCY Optional 由 3 个字母组成的货币代码,由酒店价格 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> 表示房间和套餐数据组合的唯一标识符。如需了解详情,请参阅 客房套餐
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 如果用户点击的是 客房套餐的商家信息,则解析为 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>

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

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>

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

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 个自定义变量。