Controls and inventory filtering for vertical ads

Vertical ads provide specialized features for AI-Max-enabled Search campaigns that are linked to a vertical feed, such as hotels. You can control which vertical ad formats are served at the ad group level, and you can control which feed entities are targeted using vertical ads item group rules.

Overview

This guide covers two main features for managing vertical ads:

1. Format controls: Opt in or opt out of specific ad formats (text ads, booking links, and vertical promotion ads) at the ad group level.
2. Vertical ads items management: Filter and target specific inventory from your linked vertical (formerly called travel) feed using a rule-based system that involves SharedSet andSharedCriterion`.

Prerequisites

Before you implement these features, make sure your campaign meets the following requirements:

• Campaign type: Must be a Search campaign.
• Vertical feed: An active vertical data feed must be linked to the campaign.
• AI Max: The "AI Max" setting must be enabled on the campaign.

Note: If you attempt to modify the format control settings on campaigns without AI Max or an active vertical data feed, that will result in VERTICAL_ADS_FORMAT_SETTING_NOT_SUPPORTED errors. Similarly, if you attempt to modify item management on such campaigns, that will result in VERTICAL_ADS_ITEM_GROUP_RULE_LIST_NOT_SUPPORTED errors.

Ad Group Format Controls

You can now configure which vertical ad formats are active for a specific ad group. This is managed through the vertical_ads_format_setting field on the AdGroup resource.

Available Formats

• Text ads: Enabled by default. Can be disabled.
• Booking links: Opt-in required.
• Vertical promotion ads: Opt-in required.

Validation rules

• You cannot opt out of all three formats simultaneously for a single ad group.
• These settings only apply to STANDARD and SEARCH_DYNAMIC_ADS ad group types.

Example: Update format settings

The following example demonstrates how to disable text ads and enable vertical promotion ads for an existing ad group.

Java

// Assuming 'adGroup' is an existing AdGroup object.
AdGroup adGroupToUpdate = AdGroup.newBuilder()
    .setResourceName(adGroup.getResourceName()) // Example: "customers/{id}/adGroups/{id}"
    .setVerticalAdsFormatSetting(
     
   VerticalAdsFormatSetting.newBuilder()
            .setDisableTextAds(true)
            .setEnableBookingLinks(false)
            .setEnableVerticalPromotionAds(true)
    )
    .build();

AdGroupOperation operation = AdGroupOperation.newBuilder()
    .setUpdate(adGroupToUpdate)
    .setUpdateMask(FieldMasks.allSetFieldsOf(adGroupToUpdate))
    .build();

// Submit the operation using AdGroupService...

Vertical ads items management

To target a specific subset of your feed inventory, such as "Hotels in Boston" or "Exclude 1-star hotels", you must use vertical ads item group rules.

How the data model works

The data model uses a shared criteria approach:

1. SharedSet: Create a SharedSet with type VERTICAL_ADS_ITEM_GROUP_RULE_LIST.
2. SharedCriterion: Add rules (criteria) to this set. Each rule specifies a dimension, such as City or Hotel Class, and a value. You can also create negative criteria to exclude items.
3. AdGroupCriterion: Link the SharedSet to your AdGroup using an AdGroupCriterion.

Supported dimensions

You can filter entities based on the following dimensions in SharedCriterion:

• item_code: Specific listing ID.
• city_criterion_id, region_criterion_id, country_criterion_id: Geo-targeting constants.
• brand_text: Brand name.
• hotel_class: Star rating (1-5).
• vertical_ads_item_category: Category, such as CONCERT.

Code example: Creating and linking rules

This example creates a rule to include items in "Boston" or "San Francisco" and exclude "1-star" and "2-star" hotels.

Python

# 1. Create the SharedSet
shared_set_operation = client.get_type("SharedSetOperation")
shared_set = shared_set_operation.create
shared_set.name = "Boston/SF Premium Hotels"
shared_set.type_ = client.enums.SharedSetTypeEnum.VERTICAL_ADS_ITEM_GROUP_RULE_LISTshared_set.vertical_ads_item_vertical_type = client.enums.VerticalAdsItemVerticalTypeEnum.HOTELS
# Submit SharedSetOperation...

# 2. Add Criteria (Rules) to the SharedSet
shared_criteria_operations = []

# Rule A: Include Boston and SF
included_city_ids = [1006543, 1014221] # Geo Target Constant IDs
for city_id in included_city_ids:
    op = client.get_type("SharedCriterionOperation")
    criterion = op.create
    criterion.shared_set = shared_set_resource_name
    criterion.vertical_ads_item_group_rule.city_criterion_id = city_id
    shared_criteria_operations.append(op)

# Rule B: Exclude 1 and 2 Star Hotels
excluded_stars = [1, 2]
for star_rating in excluded_stars:
    op = client.get_type("SharedCriterionOperation")
    criterion = op.create
    criterion.shared_set = shared_set_resource_name
    criterion.vertical_ads_item_group_rule.hotel_class = star_rating
    criterion.negative = True # Mark as exclusion
    shared_criteria_operations.append(op)

# Submit SharedCriterionOperations...

# 3. Link to AdGroup
agc_operation = client.get_type("AdGroupCriterionOperation")
agc = agc_operation.create
agc.ad_group = ad_group_resource_name
agc.status = client.enums.AdGroupCriterionStatusEnum.ENABLED
agc.vertical_ads_item_group_rule_list.shared_set = shared_set_resource_name

# Submit AdGroupCriterionOperation...

Reporting

You can retrieve performance metrics for vertical ads using the GoogleAdsService.SearchStream or GoogleAdsService.Search methods. For the Google Ads API, v23 adds specific segments for granular reporting.

New segments

• segments.vertical_ads_listing_city: The city associated with the listing.
• segments.vertical_ads_vertical_type: The vertical type, such as hotel or rental car.

Sample GAQL query

SQL

SELECT
  segments.vertical_ads_listing_city,
  metrics.clicks,
  metrics.all_conversions_value,
  metrics.impressions
FROM
  ad_group
WHERE
  segments.date DURING LAST_30_DAYS

Error handling

These are common errors you may encounter when configuring vertical ads.

Error code	Cause	Recommended action
INVALID_VERTICAL_ADS_FORMAT_SETTING	All three ad formats (text, booking link, promotion ads) were disabled simultaneously.	Ensure at least one format is enabled (set to true) in the VerticalAdsFormatSetting.
VERTICAL_ADS_FORMAT_SETTING_NOT_SUPPORTED_...	The campaign does not have AI Max enabled or lacks an active vertical feed.	Enable AI Max in campaign settings and ensure a valid vertical feed is linked.
VERTICAL_ADS_ITEM_GROUP_RULE_LIST_DOES_NOT_EXIST	The SharedSet resource name provided in the AdGroupCriterion does not exist.	Verify the shared_set resource name matches a created set.
VERTICAL_ADS_ITEM_GROUP_RULE_IS_NOT_SUPPORTED...	The criterion type used is not supported for the specific vertical, such as hotel class for car rentals.	Check that the vertical_ads_item_group_rule dimension matches your vertical type.