Hotel ad groups support partitioning your hotels into many hotel listing groups, across multiple dimensions so you can adjust bids for each group accordingly. Consider the tree below, where at the first level, the hotels have been broadly divided as 5-star hotels, 4-star hotels, and other hotel classes. At the second level, the hotels in other hotel classes have been divided as "United States" hotels, "United Kingdom" hotels, and hotels in other regions.
Each node in the tree is either a subdivision or a unit, as defined by
ListingGroupType. A subdivision introduces a
new level in the tree, while units are leaves of the tree. Each subdivision must
always be completely partitioned, so it must contain a node representing
Other. In the example, the root and Hotel Class: (Other) nodes are
subdivisions. This tree structure with subdivisions and units allows you to set
bids at the unit level and also ensures that every hotel listing falls into one
and only one unit node in the tree.
Nodes are objects of the ListingGroupInfo class,
which contains the ListingGroupType field that
indicates if the nodes are unit or subdivision. Setting ListingGroupInfo to
listing_group of AdGroupCriterion will link it to
the AdGroup.
Setting Percent CPC bids
You are allowed to set percent_cpc_bid_micros of
AdGroupCriterion on only unit nodes. Attempting to
do so on subdivision nodes will fail with an error.
Listing dimensions
A ListingGroupInfo also has a case_value which is
a ListingDimensionInfo that contains one of
several dimension type. A ListingGroupInfo represents the values associated
with your hotels, such as hotel ID, hotel country, or hotel class. A full description of
the available ListingDimensionInfo types is available in the reference
documentation.
Each immediate child of a subdivision must have a case_value of the same
ListingDimensionInfo subtype. Only the root node doesn't have a case_value.
Remember that each subdivision must contain an "empty" case_value of the
correct type, representing "all other values".
For more details, check out the following code snippet which adds the first level of the listing group tree.
private static function addLevel1Nodes(
int $customerId,
int $adGroupId,
string $rootResourceName,
array &$operations,
int $percentCpcBidMicroAmount
) {
// Creates hotel class info and dimension info for 5-star hotels.
$fiveStarredDimensionInfo = new ListingDimensionInfo([
'hotel_class' => new HotelClassInfo(['value' => new Int64Value(['value' => 5])])
]);
// Creates listing group info for 5-star hotels as a UNIT node.
$fiveStarredUnit = self::createListingGroupInfo(
ListingGroupType::UNIT,
$rootResourceName,
$fiveStarredDimensionInfo
);
// Creates an ad group criterion for 5-star hotels.
$fiveStarredAdGroupCriterion = self::createAdGroupCriterion(
$customerId,
$adGroupId,
$fiveStarredUnit,
$percentCpcBidMicroAmount
);
// Decrements the temp ID for the next ad group criterion.
self::$nextTempId--;
$operation = self::generateCreateOperation($fiveStarredAdGroupCriterion);
$operations[] = $operation;
// You can also create more UNIT nodes for other hotel classes by copying the above code in
// this method and modifying the value passed to HotelClassInfo() to the value you want.
// For instance, passing 4 instead of 5 in the above code will create a UNIT node of 4-star
// hotels instead.
// Creates hotel class info and dimension info for other hotel classes by *not* specifying
// any attributes on those object.
$othersHotelsDimensionInfo = new ListingDimensionInfo([
'hotel_class' => new HotelClassInfo()
]);
// Creates listing group info for other hotel classes as a SUBDIVISION node, which will be
// used as a parent node for children nodes of the next level.
$otherHotelsSubDivision = self::createListingGroupInfo(
ListingGroupType::SUBDIVISION,
$rootResourceName,
$othersHotelsDimensionInfo
);
// Creates an ad group criterion for other hotel classes.
$otherHotelsAdGroupCriterion = self::createAdGroupCriterion(
$customerId,
$adGroupId,
$otherHotelsSubDivision,
$percentCpcBidMicroAmount
);
$operation = self::generateCreateOperation($otherHotelsAdGroupCriterion);
$operations[] = $operation;
self::$nextTempId--;
return $otherHotelsAdGroupCriterion->getResourceName();
}
Available dimensions for ListingDimensionInfo
The following ListingDimensionInfo types are available for Hotel Ads:
Tip: Others unit nodes can be created by passing an empty object of
ListingDimensionInfo types to ListingGroupInfo. You also have to set the
percent_cpc_bid_micros field of the AdGroupCriterion
of an Others unit node.
Temporary IDs
Ad group criteria are not assigned IDs until the mutate request that creates
them is processed by the server. However, a ListingGroupInfo is invalid until
it is complete, so whenever you create a subdivision you must also create at
least one of its children in the same operation.
To allow you to set the parent_criterion_id of
ListingGroupInfo for the child nodes, you can use
temporary criterion IDs. These are locally unique (rather than globally unique)
identifiers that apply only within the context of a single mutate request. Any
negative integer can be used as a temporary ID. In the code
examples, the ID of the root ListingGroupInfo is set to -1.
When the request is processed, each AdGroupCriterion is assigned a positive
global ID as usual.