Google Ads Developer Blog

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.  
  
  
  
   - Da Yang, Google Ads API Team
  
  
      
  
                          
  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.  
  
  
  
   - Da Yang, Google Ads API Team