Tag Archives: google_ads

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!

- Da Yang, Google Ads API Team

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!

 - Laura Chevalier, Google Ads API Team

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.
Ian Ballantyne, Google Ads API Team

Introducing "Solutions": A New Way to Automate Management of your Google Ads Account

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.

- David Stevens, Google Ads API Product Manager

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.

Ian Ballantyne, Google Ads API Team

Optimally configure the Attribution Reporting API for ad measurement

Background

Ad-tech providers have historically used third-party cookies for conversion measurement, and for attributing conversions to ad interactions. Conversion measurement is critical for evaluating the performance of ad campaigns and automated bidding strategies. Now, with technology changes and privacy regulations on the rise, traditional ad-measurement systems must change in order to remain effective while protecting user privacy.

Chrome’s Attribution Reporting API (ARA), part of the Privacy Sandbox initiative, offers a new path to conversion measurement after Chrome’s planned third-party cookie deprecation in the second half of 2024, subject to addressing any remaining competition concerns of the UK’s Competition and Markets Authority (CMA). Google’s ads teams have made significant investments in learning to use the ARA more effectively, to help advertisers achieve more accurate measurement.

In a previous post, we provided a high-level overview of the approach Google’s ads teams are taking to effectively blend the ARA event-level and aggregate summary reports to maximize accuracy. A key point is that your configuration determines what data you query, and how you query it. It’s crucial for ad-tech providers to effectively configure the ARA for their use cases. Google’s ads teams have found that configuring specific ARA settings can lead to notable accuracy improvements. We encourage other ad-tech providers to integrate with the ARA to retrieve the conversion data they need, and process the ARA's output to help maintain accurate measurement in a post-third-party-cookie world.

The ARA is flexible to support various use cases. Google’s ads teams use this flexibility to configure unique ARA settings for each advertiser. This way, ARA-based measurement adapts to each advertiser’s specific needs. For example, we’ve noticed that when advertisers differ in conversion volume, it’s better to have advertiser-specific configurations related to the granularity of aggregation keys and the maximum observable conversions per ad interaction.

Google’s ads teams’ approach

Here's how Google's ads teams use the ARA to ensure the raw data we receive is as useful as possible for downstream blending. We configure ARA settings as explicit mathematical optimizations by defining objective functions to represent data quality, then choosing settings to optimize those functions. Ad-tech providers can choose their own approach. Google’s ads teams plan to continue sharing insights we learn from our own optimizations with the ad-tech community.

Please see our detailed technical explainer for more information about our approach to ARA configuration.

- Harikesh Nair, Senior Director, Data Science, Ads Measurement

Python Version Support in the Google Ads API Client Library

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.
- Ben Karl, on behalf of the Google Ads API Team

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.

- Da Yang, Google Ads API Team

Store Sales Direct Uploads Not Supported in the Google Ads API

As of early October 2023, Google no longer supports Store Sales Direct (SSD) as a standalone product, and therefore SSD conversion upload requests to the Google Ads API are also no longer supported.

Users who were previously allowlisted for this feature will now receive a NOT_ON_ALLOWLIST_FOR_STORE_SALES_DIRECT error when attempting to upload SSD conversions. Existing SSD conversions will continue to be available in reports.

The removal of SSD is part of a simplification of the overall Store Sales product. Users who previously relied on SSD should review the Store Sales onboarding guide to understand if they are eligible for ongoing store sales measurement. If eligible, work with your Google Ads account team to update the feature. Please reference our Upload Store Sales Conversions guide, which has been updated to reflect these changes.

If you have any questions about this change, please feel free to contact us through the forum or at [email protected] for additional help.

- Ben Karl, on behalf of the Google Ads API Team