WorryFree Computers   »   [go: up one dir, main page]


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.

Starting June 10, 2024, we are rolling out a permanent change that automatically pauses Google Ads keywords that haven’t had any impressions during the last 13 months. The rollout is expected to be complete for all production Google Ads accounts in August 2024. We’re implementing this change to improve Google Ads experience for advertisers, in a similar way to what we changed earlier this year for ad groups with low activity.

You can unpause keywords if you still need them, or to remove them if you don’t. However, we recommend that all advertisers review their keywords, and only unpause the ones they expect to get impressions in the coming weeks.

What do I need to change?

No code changes are necessary, but Google Ads API developers can make changes to improve the transparency to their advertisers as to why the ad_group_criterion.status is set to PAUSED. If you keep local copies of Google Ads information in your database, you can keep them in sync by querying change history.

You can query the change event resource to see if the keyword status has changed with the following query for all API versions. If the change_event.changed_fields contains status, then this is a keyword that Google paused. Make sure to replace INSERT_YYYY-MM-DD with your own date range.

SELECT
change_event.new_resource,
change_event.old_resource,
change_event.changed_fields,
change_event.resource_name,
change_event.change_resource_name,
change_event.user_email
FROM change_event
WHERE
change_event.change_resource_type = 'AD_GROUP_CRITERION'
AND change_event.user_email = 'Low activity system bulk change'
AND change_event.resource_change_operation = 'UPDATE'
AND change_event.change_date_time BETWEEN ' INSERT_YYYY-MM-DD' AND ' INSERT_YYYY-MM-DD'
ORDER BY change_event.change_date_time DESC
LIMIT 50

An example of a change event where the keyword has been paused by Google would look similar to:

{
      "changeEvent": {
        "resourceName": "customers/1234567890/changeEvents/1708648783892610~5~0",
        "changeDateTime": "2024-02-22 16:39:43.89261",
        "changeResourceName": "customers/1234567890/adGroupCriteria/1234567890~0987654321",
        "changeResourceType": "AD_GROUP_CRITERION",
        "userEmail": "Low activity system bulk change",
        "oldResource": {
          "adGroupCriterion": {
            "status": "ENABLED"
          }
        },
        "newResource": {
          "adGroupCriterion": {
            "status": "PAUSED"
          }
        },
        "changedFields": "status",
        "resourceChangeOperation": "UPDATE",
      }
    }

You can use the resource names returned by this query to retrieve the current status of the keywords and mutate if, if needed.

Starting with v17, you can also retrieve the ad_group_criterion.primary_status field to see if your keywords have been paused; keywords that have this field set to PAUSED and for which the ad_group_criterion.primary_status_reasons contains AD_GROUP_CRITERION_PAUSED_DUE_TO_LOW_ACTIVITY are the ones that were automatically paused due to low activity. You can adjust the change history query to include these fields.

You will still be able to update your keywords and make changes while they are in a paused state.

Where can I get support?

If you have questions, please reach out to us on the support form or at googleadsapi-support@google.com.

Google Ads is rolling out a new feature that allows the account administrator to request its users to switch from a regular personal email address (for example john.doe@gmail.com) to a business email address (for example john.doe@example.com). We are making this change to improve account security and reduce potential surface for abuse. This is an informational post to highlight how this feature could affect the Google Ads API and Google Ads scripts developers.

How does this feature work?

To use this feature, the account administrator sends a request to an account user from the Google Ads UI to switch their personal email to a business email. If the user accepts, then the following steps are bundled behind the scenes:

  • A business email address is added to the Google Ads account.
  • A grace period of one month starts, where both the personal email address and business email address are active users in the Google Ads account.
  • The personal email address is removed from the Google Ads account at the end of the grace period.

Refer to our help center guide to learn more about this feature.

How does this affect API developers?

As a developer, you may need to do the following additional steps:

  1. If the user has authorized your application to make API calls to the Google Ads account using their personal email address, then the OAuth 2.0 refresh token will stop working once the personal email address is removed from the Google Ads account. You need to authorize the user with the new business email address.
  2. This change only works with Google Ads accounts. If the user manages other accounts, such as Google Analytics or Google Merchant Center, then the email address needs to be switched manually in those accounts. See the help center page for a more comprehensive list of locations where you might have to make a change.
  3. If you have authorized and scheduled Google Ads Scripts with the personal email address, you need to authorize the scripts with the business email address after this change.

How to get help

If you have any questions or need help, check out the Google Ads API support page or Google Ads scripts support page for options.

What's changing?

We are updating the Google Ads API resource usage policy to throttle GoogleAdsService.Search and GoogleAdsService.SearchStream query patterns that consume excessive amounts of API resources. If a particular query pattern is throttled, other services, methods, and query patterns will continue to work unaffected.

Starting the week of June 17, 2024, and only for the throttled query patterns, requests will be affected as follows:

  • If you use version v16 or older of the API, you will receive a QuotaError.RESOURCE_EXHAUSTED error.
  • If you use version v17 or later of the API, you will receive a QuotaError.EXCESSIVE_SHORT_TERM_QUERY_RESOURCE_CONSUMPTION or QuotaError.EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION, depending on whether the excessive resource consumption was for a short period of time (a few minutes), or a long period of time.

To help you identify and monitor your expensive reports, we will also return a cost metric for individual reports. To view the cost for successful reports, see the following fields:

Why this change?

We are making this change to preserve the reliability and stability of the API.

What do I need to do?

Before June 17, 2024, update your applications to do the following:

  • Handle the new error codes when making GoogleAdsService::Search or GoogleAdsService::SearchStream calls
    • If you use version v16 or earlier of the Google Ads API, then handle QuotaError.RESOURCE_EXHAUSTED errors.
    • If you use version v17 or later of the API, handle the QuotaError.EXCESSIVE_SHORT_TERM_QUERY_RESOURCE_CONSUMPTION and QuotaError.EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION errors.
    • If one or more of your reporting query patterns are throttled, you should review and fix the query pattern. Here are some ways to improve query performance:
    • Run the query less frequently.
    • Use a less expensive query pattern or view.

To learn more about optimizing your queries, see manage data efficiency.

  • [Optional] Incorporate the new query_resource_consumption metric into your monitoring systems to detect and handle new expensive queries.

How to get help

If you have any questions about this change or need help optimizing specific query patterns, check out the Google Ads API support page for options.

Today, we’re announcing the v16_1 release of the Google Ads API. To use some of the v16_1 features, upgrade your client libraries and client code. The updated client libraries and code examples will be published next week. This version has no breaking changes.

Here are the highlights:

Where can I learn more?

The following resources can help you get started:

If you have any questions or need additional help, contact us via the forum.

Google Ads API v14 will sunset on June 5, 2024. After this date, all v14 API requests will begin to fail. Migrate to a newer version prior to June 5, 2024 to ensure your API access is unaffected.

Here are some resources to help you with the migration: You can view a list of methods and services your project has recently called using the Google Cloud Console:
  1. Open the Dashboard page (found under APIs & Services) in the Google Cloud Console.
  2. Click on Google Ads API in the table.
  3. On the METRICS subtab, you should see your recent requests plotted on each graph. At the bottom of the page, you’ll see the Methods table, where you can see which methods you’ve sent requests to. The method name includes a Google Ads API version, a service, and a method name, e.g., google.ads.googleads.v14.services.GoogleAdsService.Mutate. In this way, you can see all versions that you’ve used recently.
  4. (Optional) Click on the time frame at the top right of the page if you need to change it.
If you have questions while you’re upgrading, reach out to us on the forum or at googleadsapi-support@google.com.

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.

Starting with version 19.0.0, the Google Ads API client library for .NET requires .NET version 6.0 or higher. Support for .NET Framework remains unchanged and the minimum required version remains 4.7.2.

Version 18.1.0 of the Google Ads API client library for .NET, which adds support for the Google Ads API v16, will be the last version that supports .NET version 5.0. We will still fix security issues for this client library version until the Google Ads API v16 is sunset in January 2025, but no new features will be added.

.NET version 5.0 reached its end of life in May 2022. Microsoft no longer provides security fixes for this version, so we strongly recommend migrating to newer versions as soon as possible.

The Google Ads API client library for .NET already supports newer LTS versions like .NET 6.0 and 8.0, and we plan to support forthcoming LTS versions as well.

Here are some useful resources to help with the .NET upgrade:

We're excited to announce the launch of "Solutions," a new tool for Google Ads that makes it easier to manage and automate tasks in your account. With Solutions, you can quickly and easily generate reports that show you how your campaigns are performing against your business goals, automate simple management tasks and more.

Solutions is available for free in Google Ads under Tools and includes a number of features that make it easy to customize your reports, including the ability to:

  • Filter your data by campaign, ad group, keyword, or other dimensions
  • Set flexible budgets
  • Manage negative keyword lists throughout your account
  • Sort your data by any metric
  • Export your reports to a variety of formats, including CSV and XLSX

To learn more about Solutions, visit the the Google Ads Help Center.

Benefits of Using Solutions

Solutions offers a number of benefits, including:

  • It's easy to use. Solutions is a simple and straightforward script that can be used by anyone, regardless of their technical expertise.
  • It's customizable. Solutions can be customized to meet your specific automation needs.
  • It's efficient. Solutions can generate reports quickly and easily, saving you time and effort.
  • It's accurate. Solutions uses the Google Ads API to pull data directly from your Google Ads account, ensuring that your reports are accurate and up-to-date.

Developers Site Solution Library

In order to try to provide the best possible experience and to avoid duplication of efforts, we will also be sunsetting our manual solutions library in the coming months.

Get Started with Solutions Today!

Solutions is a powerful tool that can help you get the most out of your Google Ads campaigns. To get started, simply install the solution from the Google Ads Solutions gallery.

Starting March 11, 2024 we are rolling out a permanent change that automatically pauses search campaign ad groups that were created at least 13 months ago and have not had impressions in the past 13 months. The rollout is expected to be complete for all production Google Ads accounts by April 30, 2024. This is being done to improve Google Ads experience for advertisers.

Advertisers who are affected by this change will be able to unpause ad groups if they still need them. However, we recommend that advertisers review their ad groups and only unpause the ones you expect to get impressions in the coming weeks. Unpaused ad groups will be automatically paused again if they don’t receive any impressions over the next 3 months.

What do I need to change?

No code changes are necessary, but Google Ads API developers can make changes to improve the transparency to their advertisers as to why the ad_group.status is set to PAUSED. If you keep local copies of Google Ads information in your database, you can keep them in sync by querying change history.

You can query the change event to see if the ad group status has changed with the following query for all API versions. If the change_event.changed_fields contains status, then this is an ad group that Google paused. Make sure to replace INSERT_YYYY-MMM-DD with your own date range.

SELECT ad_group.status, ad_group.resource_name, ad_group.name, 
ad_group.id, change_event.change_date_time, 
change_event.new_resource, change_event.old_resource, 
change_event.changed_fields, change_event.change_resource_type, 
change_event.user_email, change_event.ad_group 
FROM change_event 
WHERE change_event.user_email = 'Low activity system bulk change'  
AND change_event.change_resource_type = 'AD_GROUP' 
AND ad_group.status = 'PAUSED' 
AND change_event.change_date_time >= 'INSERT_YYYY-MMM-DD' 
AND change_event.change_date_time <= 'INSERT_YYYY-MMM-DD' 
ORDER BY change_event.change_date_time DESC LIMIT 50

An example of a change event where the ad group has been paused by Google would look similar to:

{
      "adGroup": {
        "resourceName": "customers/1234567890/adGroups/5432154321",
        "status": "PAUSED",
        "id": "5432154321",
        "name": "Your ad group name"
      },
      "changeEvent": {
        "resourceName": "customers/1234567890/changeEvents/1708648783892610~5~0",
        "changeDateTime": "2024-02-22 16:39:43.89261",
        "changeResourceType": "AD_GROUP",
        "userEmail": "Low activity system bulk change",
        "oldResource": {
          "adGroup": {
            "status": "ENABLED"
          }
        },
        "newResource": {
          "adGroup": {
            "status": "PAUSED"
          }
        },
        "changedFields": "status",
        "adGroup": "customers/1234567890/adGroups/5432154321"
      }
    }

Starting with v16, the API returns the reason as to why the ad group was paused with new fields. You can adjust the change history query to include these fields.

API Version Query Ad Group Changes
v16.1+ Starting in v16.1, the ad_group.primary_status_reasons will contain AD_GROUP_PAUSED_DUE_TO_LOW_ACTIVITY if ad_group.primary_status is set to PAUSED by Google.
v16 Starting in v16, the ad_group.primary_status_reasons will contain AD_GROUP_PAUSED if ad_group.primary_status is set to PAUSED by Google.

You will still be able to update your ad groups and make changes while they are in a paused state.

Where can I get support?

If you have questions, please reach out to us on the support form or at googleadsapi-support@google.com.

What happened?

For developers linking Merchant Center accounts to Google Ads using Google Ads API v14, there was an issue from 04:00 PST Monday, Feb 19 to 08:00 PST Tuesday, Feb 20 that caused some requests to the MutateMerchantCenterLink method of MerchantCenterLinkService to return MutateError.RESOURCE_NOT_FOUND. Also calls to ListMerchantCenterLinks may not have returned some MerchantCenterLinks with link status PENDING.

What should I do?

If you use Google Ads API v14 to link Merchant Center accounts to Google Ads accounts using MerchantCenterLinkService, you should check to see if you have accounts that have pending link requests during the period of time described above. This issue has now been resolved and you may retry the failed calls to complete the linking of Merchant Center accounts. Also check ListMerchantCenterLinks for accounts with link status PENDING. Some of these link requests may not have previously been returned during that time period.

How to get help

If you have any questions or need help, check out the Google Ads API support page for options.

Today, we’re announcing the v16 release of the Google Ads API. To use some of the v16 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published next week.
Here are the highlights: Where can I learn more?
The following resources can help you get started: If you have any questions or need additional help, contact us via the forum.

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.

On April 30, 2024, the creation of hotel campaigns with COMMISSION bidding strategy will sunset. This bidding strategy was available only to travel advertisers. Requests to create new hotel campaigns or apply this bidding strategy to existing campaigns after April 30th will result in a BiddingStrategyError.BIDDING_STRATEGY_NOT_SUPPORTED error. Existing campaigns with the COMMISSION bidding strategy will continue to run until October 31, 2024. After this day campaigns will stop serving until their bidding strategy is updated. A notification will be displayed in the Google Ads UI, guiding users on how to update the affected campaigns.

We suggest that travel advertisers with Hotel campaigns and Things to do Ads migrate to the Target ROAS (TARGET_ROAS) auto bidding strategy. You can find more information about the tROAS in our Help Center article.

If you have any questions or concerns, please don't hesitate to contact us in the forum.

Today, we are pleased to announce a new video series just published on our YouTube channel, titled “Getting started with the Java Client Library”.

The seven episodes guide you through all the steps required to create a Google Ads campaign with the Java client library from scratch; the only prerequisites are a working Java development environment and a Google Ads manager account.

The videos walk you through the setup of an empty Java project and the import of the Google Ads client library for Java, then describe the process to obtain all required credentials and how to configure them in your Java project.

The last video in the series puts everything together and shows how to execute a basic call to the Google Ads API by running the AddCampaigns code example.

We hope the video series will help you understand all the required steps to get started developing a Java application on top of the Google Ads API. Meanwhile, even if you’re not using Java, we still recommend subscribing to the Google Ads Developers channel on YouTube to always be up to date with our video content.

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.

Google Ads API v13 will sunset on January 31, 2024. After this date, all v13 API requests will begin to fail. Please migrate to a newer version prior to January 31, 2024 to ensure your API access is unaffected.

We've prepared various resources to help you with the migration: In addition, using the Google Cloud Console, you can view the list of methods and services to which your project recently submitted requests:
  1. Open the Dashboard page (found under APIs & Services) in the Google Cloud Console.
  2. Click on Google Ads API in the table.
  3. On the METRICS subtab, you should see your recent requests plotted on each graph. At the bottom of the page, you’ll see the Methods table, where you can see which methods you’ve sent requests to. The method name includes a Google Ads API version, a service, and a method name, e.g., google.ads.googleads.v13.services.GoogleAdsService.Mutate. In this way, you can see all versions that you’ve used recently.
  4. (Optional) Click on the time frame at the top right of the page if you need to change it.
If you have questions while you’re upgrading, please reach out to us on the forum or at googleadsapi-support@google.com.

In June 2023, support for Python 3.7 was deprecated in the Google Ads API Client Library for Python. In Q1 2024, a major version of the library will be released that makes it incompatible with Python 3.7. Library changes related to compatibility with Python 3.7 will be limited to critical security or stability patches.

Google Ads API users who depend on Python 3.7 can continue using version 22.1.0 of the library, which includes API v15 support, until v15 of the is sunset in September 2024. All Python users should upgrade to Python 3.8 or higher as soon as possible.

In the future, Python users should expect that the library will become incompatible with unsupported versions of Python as soon as they reach end-of-life status. When Python 3.8 becomes unsupported in October 2024, a major version of the library will be released that is incompatible with Python 3.8. At least two months before a Python version deprecation, we will publish a blog post to help remind users of the change.

The below resources are available to help users plan ahead for future language support removal: If you have any questions about this change, please file an issue on the client library repository on GitHub.

We’re announcing our tentative 2024 release and sunset schedule for upcoming versions of the Google Ads API to bring greater clarity to your planning cycle. Please keep in mind that these dates are only estimates and may be adjusted going forward. Additionally, releases may be added, removed, or switched between major and minor versions.
Version Planned Release
Type*
Projected launch* Projected sunset*
V16 Major January/February 2024 January 2025
V16.1 Minor April/May 2024 January 2025
V17 Major May/June 2024 May 2025
V17.1 Minor July/August 2024 May 2025
V18 Major September/October 2024 September 2025

*Estimated and subject to change

Where can I learn more? Check back for any updates as the blog is the best place to stay informed about developments in this space.

If you have any questions or need additional help, contact us via the forum.

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.