Tag Archives: performance_max

Watch Performance Max and the Google Ads API On Demand

As previously announced, Ads Developer Relations hosted a workshop on July 17: Performance Max and the Google Ads API. We are grateful to all the Google Ads API and Performance Max enthusiasts who tuned in for the live workshop.

If you didn't get a chance to watch the workshop live, or you want to review content you previously watched, you can still view sessions on demand at the event site.

We hope you will take advantage of this awesome resource to learn more about the power of Performance Max campaigns, and hear from Google Ads API experts on how to build, manage, and report on Performance Max campaigns using the API.

Register for the Performance Max Workshop

As previously announced, the Performance Max and the Google Ads API workshop is only one week away, on July 17, 2024. Register today to reserve your spot.

As a reminder, this developer-focused, virtual workshop will provide you with knowledge, resources, and support to build, manage, and report on Performance Max campaigns in the Google Ads API. We’re offering this live workshop in three regions. Follow the links below to view the full agenda in your region.

Regional Workshop Times & Agendas

We look forward to seeing you!

Batch processing support for Performance Max

What’s New

Starting with Google Ads API v17, BatchJobService supports AssetGroupOperation. With this change you can use batch processing to create and manage entire Performance Max campaigns.

Batch processing is a powerful feature in the Google Ads API that lets you dispatch a set of operations, which might be interdependent, to multiple services without waiting for each operation to complete. Batch processing also provides automatic retries for transient errors, and automatic grouping of operations We have made batch processing available for AssetGroupOperation in response to your feedback to provide another option for working with asset groups asynchronously.

Implementation Details

Using AssetGroupOperation with batch processing for Performance Max campaigns is similar to how you use other operations, with the following special considerations:

When creating asset groups using batch processing, AssetGroupOperation and AssetGroupAssetOperation must be sequential without other operations in between. This is due to how operations are grouped together when processed. You can learn more about the considerations and best practices for using batch processing to create Performance Max campaigns in the Batch processing for Performance Max guide.

Here’s how to create an asset group in a batch job:

  1. Create a MutateOperation containing an AssetGroupOperation. This is no different than creating a MutateOperation using the GoogleAdsService.Mutate service. See the mutating resources guide.
  2. Associate assets with the asset group by creating a MutateOperation containing operations of type AssetGroupAssetOperation for each asset required; the sequential AssetGroupOperation and operations of type AssetGroupAssetOperation must combine to meet applicable minimum asset requirements.
  3. Add the operations of type MutateOperation to the batch job as you would with any other type of operation.
  4. Run the batch job by calling RunBatchJob after adding all operations.

The following resources contain additional information to help you with your integration:

Improving Performance Max integrations Blog Series

This article is part of a series that discusses new and upcoming features that you have been asking for. We’ll cover what’s new and how it differs from the current implementation approach.

Keep an eye out for further updates and improvements on our developer blog, continue providing feedback on Performance Max integrations with the Google Ads API, and as always, contact our team if you need support.

Workshop Reminder

Register today for the Performance Max and the Google Ads API workshop happening on July 17!

Upcoming Workshop: Performance Max and the Google Ads API

Today, we’re announcing an upcoming developer workshop, Performance Max and the Google Ads API. These virtual sessions will provide you with knowledge, resources, and support to create, manage, and report on Performance Max campaigns in the Google Ads API. The workshop will be presented live in three regions on July 17, 2024.

Regional Workshop Times & Agendas

Hear from Google Ads API experts as we:

  • Tour the core features and business goals available in Performance Max campaigns.
  • Detail key technical pieces of your Performance Max implementation, from setup to reporting.
  • Build a Performance Max interface in an interactive demo.
  • Review best practices for configuring and optimizing your Performance Max campaigns.
  • Discuss Performance Max and AI in an experts panel.

Whether you’re new to Performance Max or looking to expand upon an existing integration, we'll have a variety of sessions to help you achieve your goals and boost your Google Ads account performance with the power of Google AI. We’ll be delivering several talks to discuss what's unique about Performance Max and explain key concepts across experience levels.

Throughout the workshop, you’ll have the opportunity to interact with our team via live Q&A.

Head over to the event site to register and view the full agenda. We look forward to seeing you!

A new guide to help you upgrade to Performance Max using the Google Ads API


Do you want to discover if Performance Max can provide additional benefits beyond your existing campaigns?
Are you interested in upgrading existing campaigns to Performance Max?
Do you need to scale your upgrades using the Google Ads API?

What’s new
If the answer to any of these questions is “yes”, then the new Upgrade to Performance Max guide can help. In this guide you will discover:
  • A summary of the benefits available in Performance Max
  • Steps to assist you managing the upgrade process
  • Eligibility information to help you understand which existing campaigns you are able to upgrade using the Google Ads API
  • Recommendations to compare reporting between existing campaigns and Performance Max campaigns
  • Enhancements you can make to improve your upgraded campaign
Feedback and support
If you have further questions or concerns about upgrading to Performance Max, we want to hear from you. Please provide any feedback on the upgrade process or Performance Max using our feedback page. If you require further support with your upgrade, please reach out to our team via one of our support channels.

Introducing the Performance Max Developer Guide

Today we are pleased to announce the release of a dedicated Performance Max developer guide. With this release, we’ve moved Performance Max content to its own tab in the main navigation of our developer documentation with a dedicated landing page and updated navigation to help you more easily find the information you need to build Performance Max integrations.

Other notable improvements include:

Improving Performance Max integrations Blog Series

This article is part of a series that discusses new and upcoming features that you have been asking for. Keep an eye out for further updates and improvements on our developer blog, continue providing feedback on Performance Max integrations with the Google Ads API, and as always, contact our team if you need support.

Important information for Performance Max campaigns using page feeds with text asset automation opted out

Note: You can ignore this if you are not using Google Ads Performance Max with page feeds and text asset automation

What’s happened?

In October 2023, as part of Google Ads API v15, we launched the ability to configure your campaign to automatically generate text assets. Assets such as dynamic headlines or descriptions that match your landing page content can be configured by setting the Campaign.AssetAutomationSetting of TEXT_ASSET_AUTOMATION to be opted-in or opted-out. We also launched the ListingGroupFilterDimension.Webpage dimension to allow Performance Max campaigns to filter URLs from a page feed specified by a CampaignAssetSet linking the campaign to an AssetSet of type PAGE_FEED.

For this feature to work correctly, developers need to provide BOTH the page feed configuration AND set text asset automation to OPTED_IN (which is the default behavior, if you do not specify a Campaign.AssetAutomationSetting of type TEXT_ASSET_AUTOMATION). We noticed that some developers have included a page feed or a listing group filter for a webpage, but have text asset automation set to OPTED_OUT. Unfortunately this combination will not correctly utilize the page feed for Performance Max campaigns as might be expected.

What is happening today?

Starting Feb 15, 2024, we will begin throwing OPERATION_NOT_PERMITTED_FOR_CONTEXT errors if a Performance Max campaign is created or updated such that it contains the follow incompatible state:

Incompatible state for a Performance Max campaign with a page feed and text asset automation
Campaign.AssetAutomationSetting of type TEXT_ASSET_AUTOMATION is set to OPTED_OUT AND A CampaignAssetSet linking the campaign to an AssetSet of type PAGE_FEED
OR
An AssetGroupListingGroupFilter with ListingGroupFilterDimension set to Webpage.

We are doing this to let you know that this combination is not valid and won’t serve ads utilizing landing page content as expected.

What happens next?

For those developers who have campaigns in this incompatible state, starting April 15, 2024, we will automatically fix the compatibility by removing CampaignAssetSet resources linking a campaign to an AssetSet of type PAGE_FEED and removing AssetGroupListingGroupFilter resources with ListingGroupFilterDimension set to Webpage only if the Campaign.AssetAutomationSetting of type TEXT_ASSET_AUTOMATION is set to OPTED_OUT. This fix will match how the campaign is currently serving and no action is required if you would like the campaign to remain in this state. If you would like to utilize the landing page content, then you will need to opt-in to text asset automation.

What do I need to do?

First, confirm that you are using text asset automation and page feed assets or asset group listing filters with webpage dimensions in your Performance Max campaigns. Otherwise, you are not impacted by this change.

To check if your Performance Max campaign is in an incompatible state for page feeds, run the following GAQL queries:

1) Check for page feeds linked to campaigns that have text asset automation opted-out:

SELECT 
  asset_set.id, 
  asset_set.name, 
  asset_set.resource_name, 
  campaign.id, 
  campaign.name, 
  campaign.resource_name, 
  campaign.asset_automation_settings, 
  campaign_asset_set.status, 
  campaign.status 
FROM campaign_asset_set 
WHERE 
  campaign.advertising_channel_type = 'PERFORMANCE_MAX' 
  AND asset_set.type = 'PAGE_FEED' 
  AND asset_set.status = 'ENABLED' 
  AND campaign_asset_set.status = 'ENABLED' 
  AND campaign.status != 'REMOVED' 

You may be impacted if any of the CampaignAssetSet resources, linking a campaign to an AssetSet of type PAGE_FEED, have a campaign_asset_set.status that is set to ENABLED and an item in campaign.asset_automation_settings with TEXT_ASSET_AUTOMATION set to OPTED_OUT.

2) Check for asset group listing group filters with dimension webpage for campaigns that have text asset automation opted-out:

SELECT 
  asset_group.id, 
  asset_group.name, 
  asset_group.resource_name, 
  asset_group_listing_group_filter.case_value.webpage.conditions, 
  asset_group_listing_group_filter.id, 
  asset_group_listing_group_filter.resource_name, 
  asset_group_listing_group_filter.listing_source, 
  campaign.id, 
  campaign.name, 
  campaign.resource_name, 
  campaign.asset_automation_settings, 
  campaign.status 
FROM asset_group_listing_group_filter 
WHERE 
  asset_group.status != 'REMOVED' 
  AND campaign.advertising_channel_type = 'PERFORMANCE_MAX' 
  AND asset_group_listing_group_filter.listing_source = 'WEBPAGE' 
  AND campaign.status != 'REMOVED'

You may be impacted if any of the AssetGroupListingGroupFilter resources have a case_value that is a Webpage and an item in campaign.asset_automation_settings with TEXT_ASSET_AUTOMATION set to OPTED_OUT.

Manually fix the inconsistent state of the campaign

If you would like to manually configure the campaign yourself ahead of the automatic fix, we suggest one of the two options:

Options to manually fix the inconsistent state of a Performance Max campaign
OPTION A) Turn on text asset automation
Set Campaign.AssetAutomationSetting of type TEXT_ASSET_AUTOMATION to OPTED_IN
OPTION B) Remove associated page feed references
Remove BOTH:
The CampaignAssetSet linking the campaign to an AssetSet of type PAGE_FEED AND The AssetGroupListingGroupFilter with ListingGroupFilterDimension set to Webpage.

You will be able to make this change until April 15, 2024, after which option B will be automatically applied to fix the Performance Max campaign. Note that after the automatic fix is applied, the serving state of the campaign won't change from how it is serving today.

How do I get support?

For more details on how to correctly use automatically generated text assets with landing pages, see the automatically created assets section of the Performance Max guide. If you require further support, please reach out to our team via one of our support channels.

Performance Max Guide Enhancements

Today, we are pleased to announce several guide enhancements to improve the experience of creating, managing and reporting on Performance Max campaigns with the Google Ads API.

Improving Performance Max integrations Blog Series

This article is part of a series that discusses new and upcoming features that you have been asking for. Keep an eye out for further updates and improvements on our developer blog, continue providing feedback on Performance Max integrations with the Google Ads API, and as always, contact our team if you need support.

Performance Max: Create Search Themes beta with the Google Ads API

What’s New

The recently announced search themes beta feature for Performance Max campaigns lets you provide Google AI with valuable inputs about your customers and business to further optimize Performance Max campaign serving and placement. Beginning in Google Ads API v15, you can create search themes for Performance Max campaigns with the API.

How It Works

  • Search themes beta lets you indicate queries that you know your customers are looking for. They are optional and are additive to what queries Performance Max would match by using your URLs, assets, and more.
  • You can add up to 25 search themes per asset group.
  • Search themes will respect brand exclusions in Performance Max and account-level negative keywords. You can configure brand exclusions through campaign criteria using the BRAND criterion type. Similarly, account-level negative keywords are configured at a customer level using CustomerNegativeCriterionService and the NegativeKeywordList criteria.
  • Results driven from search themes will bring your customers to the landing pages you’ve indicated with your Final URL expansion, page feeds, or URL settings. Final URL expansions can be enabled or disabled with url_expansion_opt_out.
  • Search themes will have the same prioritization as your phrase match and broad match keywords in your Search campaigns.
  • You’ll be able to see the search categories that your ads matched to, and associated conversion performance, in your search terms insights at both the campaign and account levels with the campaign_search_term_insight and customer_search_term_insight reports. You can also view search term insights for custom date ranges, download your data, and access it using the API.

Implementation Details

In the Google Ads API, a search theme is a type of AssetGroupSignal, which can be attached to Performance Max campaigns at the asset group level. You can add a search theme to an asset group by creating an AssetGroupSignal and populating the

AssetGroupSignal.search_theme with a SearchThemeInfo criterion containing a text string representing your search theme, for example, "activities for children". In addition, you must populate the AssetGroupSignal.asset_group with the resource name of an existing asset group you are targeting.

Here is a Java example for creating a search theme asset group signal:

// Creates a search theme asset group signal.
AssetGroupSignal assetGroupSignal =
    AssetGroupSignal.newBuilder()
        .setAssetGroup(assetGroupResourceName)
        .setSearchTheme(
            SearchThemeInfo.newBuilder().setText("activities for children").build())
        .build();

You can add multiple asset group signals to a single asset group by creating multiple AssetGroupSignal objects targeting the same asset group. However, each AssetGroupSignal object can only represent a single search theme or audience signal.

Reporting

You can use the asset_group_signal resource to get the search themes present in a Google Ads account. While performance metrics are currently available at the asset group level, they are not available at the asset group signal level.

Here is a GAQL example to retrieve search theme texts for a specific asset group:

SELECT
  asset_group_signal.search_theme.text
FROM asset_group_signal
WHERE
  asset_group.id = <Asset Group ID>

Policy Exemptions

In v15 of the Google Ads API, we also introduced two new fields to provide additional information about search_theme approval: asset_group_signal.approval_status and asset_group_signal.disapproval_reasons. Search theme text must be approved by Google. The asset_group_signal.approval_status field provides information about the approval status, and if the search theme text is not approved, the asset_group_signal.disapproval_reasons field lists the reasons why.

Here is a GAQL example to retrieve search theme texts with policy review information for a specific asset group:

SELECT
  asset_group_signal.search_theme.text, 
  asset_group_signal.approval_status, 
  asset_group_signal.disapproval_reasons 
FROM asset_group_signal 
WHERE 
  asset_group.id = <Asset Group ID>

If your search theme text is not approved, and you believe the usage adheres to Google’s policies, you can submit a policy exemption request for the search theme that triggered the policy violation.

For example, if your search theme contains medical terms, and you believe the usage of the terms adheres to Google Ads policies and warrants further review, you can use the AssetGroupSignalOperation.exempt_policy_violation_keys[] field to request a policy exemption.

Improving Performance Max integrations Blog Series

This article is part of a series that discusses new and upcoming features that you have been asking for. Keep an eye out for further updates and improvements on our developer blog, continue providing feedback on Performance Max integrations with the Google Ads API, and as always, contact our team if you need support.

If you are new to Performance Max Campaigns, you can learn more with our getting started guide. Check out our asset groups and asset group signals guides to learn more.

Performance Max: create listing groups using batch processing

What’s New

Starting on October 4, 2023, AssetGroupListingGroupFilters can be created asynchronously using batch processing with the Google Ads API. If you use BatchJobService to create AssetGroupListingGroupFilter entities and other Performance Max resources in a single request, errors in the listing group tree creation will not block the creation of the remaining entities. However, the operations to create a listing group tree will still be atomic. This means that if any operation related to the creation of a listing group tree returns an error, all operations related to that listing group tree will also fail, save a few caveats, which are detailed in this Jobs & listing group filters guide.

This update does not change the behavior of any existing batch jobs that do not include operations that create listing group filters.

Previous Behavior

Prior to October 4, 2023, AssetGroupListingGroupFilters could only be created synchronously using the GoogleAdsService.Mutate or AssetGroupListingGroupFilterService.MutateAssetGroupListingGroupFilters method. Requests using the GoogleAdsService.Mutate method are always atomic when they contain AssetGroupListingGroupFilterOperation operations. This is because partial_failure is not supported for these operations, which means that an error in listing group tree creation would block all other operations in the request. If you tried creating AssetGroupListingGroupFilter entities prior to October 4, 2023 using batch processing, you would receive a MutateError.OPERATION_DOES_NOT_SUPPORT_PARTIAL_FAILURE error.

Change Rationale

Batch processing is a powerful feature in the Google Ads API that allows you to dispatch a set of operations, which may be interdependent, to multiple services without synchronously waiting for the operations to complete. We have made batch processing available for AssetGroupListingGroupFilters in response to your feedback to provide another option for creating listing group trees asynchronously and without blocking other operations in the same request.

Implementation Details

In order to add an AssetGroupListingGroupFilter using a batch job:

  1. Create a MutateOperation containing an AssetGroupListingGroupFilterOperation. This is no different than creating a MutateOperation using the GoogleAdsService.Mutate service.
  2. Add the MutateOperation to the batch job as you would with any other type of operation.

The example below demonstrates the process of adding a single AssetGroupListingGroupFilter to an existing batch job. See the Creating Shopping Listing Groups guide to learn more about creating product partition trees using AssetGroupListingGroupFilter entities.

// Constructs the AssetGroupListingGroupFilter.
AssetGroupListingGroupFilter listingGroupFilter =
     AssetGroupListingGroupFilter.newBuilder()
         .setAssetGroup(assetGroupResourceName)
         .setType(ListingGroupFilterType.UNIT_INCLUDED)
         .setVertical(ListingGroupFilterVertical.SHOPPING)
         .build();

// Constructs the operation to create the AssetGroupListingGroupFilter.
MutateOperation operation = MutateOperation.newBuilder()
     .setAssetGroupListingGroupFilterOperation(
           AssetGroupListingGroupFilterOperation
      .newBuilder()
      .setCreate(listingGroupFilter))
      .build();

// Sends a request to add the operation to the batch job.
AddBatchJobOperationsResponse response =
    batchJobServiceClient.addBatchJobOperations(
        AddBatchJobOperationsRequest.newBuilder()
            .setResourceName(batchJobResourceName)
            .addMutateOperations(operation)
            .build());

The following resources contain additional information to help you with your integration:

Improving Performance Max integrations Blog Series

This article is part of a series that discusses new and upcoming features that you have been asking for. We’ll cover what’s new and how it differs from the current implementation approach.

Keep an eye out for further updates and improvements on our developer blog, continue providing feedback on Performance Max integrations with the Google Ads API, and as always, contact our team if you need support.