Category Archives: Ads Developer Blog

The official blog for information about the AdWords, AdSense, DoubleClick and AdMob APIs and SDKs

Sunsetting Portofolio Enhanced CPC Bid Strategies

On March 22, 2021 we will begin to sunset portfolio (shared) Enhanced cost-per-click (ECPC) bid strategies. The following behaviors will be blocked in all versions of both the AdWords API and the Google Ads API:
  • Creating new portfolio ECPC strategies.
  • Attaching portfolio ECPC strategies to campaigns.
Note that standard (non-portfolio) ECPC strategies will not be affected.

Affected Portfolio Enhanced CPC Strategies
Google Ads API Bidding_strategy.type = BiddingStrategyType.ENHANCED_CPC
AdWords API SharedBiddingStrategy.type = MANUAL_CPC,

SharedBiddingStrategy.biddingScheme.enhancedCpcEnabled = TRUE


Change Description
Any operation creating new portfolio ECPC strategies, or attaching a portfolio ECPC strategy to a campaign, will generate one of the following errors:

Error Upon Creation Error Upon Attaching
Google Ads API BIDDING_STRATEGY_NOT_SUPPORTED CANNOT_ATTACH_BIDDING_STRATEGY_TO_CAMPAIGN
AdWords API BIDDING_STRATEGY_NOT_SUPPORTED CANNOT_ATTACH_BIDDING_STRATEGY_TO_CAMPAIGN


Migration Description
In the future, we will remove the portfolio ECPC strategy entirely, in favor of standard ECPC. In order to prepare for this change, you can proactively migrate all your portfolio ECPC strategies to standard ECPC strategies using the instructions below.

All remaining portfolio ECPC campaigns and strategies will be automatically migrated at a later date. We will post an update on this blog ahead of that migration.

Self-migration using Google Ads API
Update a campaign by using CampaignService.MutateCampaigns() to set its manual_cpc.enhanced_cpc_enabled field to true. Be sure to set the update_mask on your request to match:

operations: [
{
update: {
resource_mame: customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID,
manual_cpc: {
enhanced_cpc_enabled: true
}
},
update_mask: manual_cpc.enhanced_cpc_enabled
}
]
Self-migration using AdWords API
Update a campaign by using CampaignService.mutate() to set its biddingStrategyType to MANUAL_CPC, and its biddingScheme.enhancedCpc field to true:

<operations>
<operator>SET</operator>
<operand>
<id>CAMPAIGN_ID</id>
<biddingStrategyConfiguration>
<biddingStrategyType>MANUAL_CPC</biddingStrategyType>
<biddingScheme>
<enhancedCpcEnabled>true</enhancedCpcEnabled>
</biddingScheme>
</biddingStrategyConfiguration>
</operand>
</operations>
If you have any questions or need additional help, contact us via the forum or at [email protected].

Changes to phrase match and broad match modifier

On February 4, 2021, we announced upcoming changes to phrase match and broad match modifier. To simplify the keyword portfolio and help advertisers reach more relevant user searches, we are bringing behaviors of broad match modifier (BMM) into phrase match, and phasing out support for BMM. This will be a gradual rollout that will change the back end processing for keyword match types (AdWords API, Google Ads API, Google Ads scripts) in order to simplify keywords and make it easier to reach relevant customers.

The updated phrase match will contain the best of both match types: the control of phrase match, and the expanded reach of broad match modifier. Both phrase and BMM keywords will continue to work and beginning February 18, 2021 for our first wave of languages (English, German, Spanish, French, Italian, Dutch, Portuguese, Russian), keywords using the phrase or BMM notations will begin to use the updated phrase match behavior. In Q2 we will begin the same process for all other Google Ads languages, and expect to complete in July 2021.

In July 2021, once all languages have the updated phrase match behavior, advertisers will be prevented from creating new BMM keywords (but any legacy BMM keywords will still work).

The changes to phrase match and BMM will not impact negative keyword match types.

How does this change affect the AdWords API, Google Ads API and Google Ads scripts?
Starting in July 2021, you will no longer be able to create new BMM keywords (i.e. matchType of BROAD and keyword text in which tokens begin with +). We will do a separate reminder announcement as we get closer to this milestone.

What impact should advertisers expect?
Impact will depend on each advertiser's usage of phrase and/or BMM and how comprehensive their query coverage is.
  • Advertisers predominantly using phrase match are expected to see an incremental increase in clicks and conversions
    • This is due to the additional queries to which these keywords will now be eligible to match. For example, “holidays in zambia” as a phrase keyword will now begin to match to “holiday spots in zambia”, which was previously only eligible for BMM.
  • Advertisers predominantly using BMM are expected to see a slight decrease in clicks and conversions
    • The majority of this loss is from BMMs where the modifier was only applied to part of the keyword, e.g. tennis +shoes.
    • In addition we are now considering word order when it’s important to the meaning of the keyword, so some matches that previously matched to BMM will be filtered out.
What should I do?
Advertisers may experience traffic shifts. User queries that previously matched to keywords in one match type may become eligible to match to a phrase or legacy BMM keyword causing the volume to move across keywords. For this reason it is important for advertisers to monitor their accounts and adjust budgets if needed to accommodate additional volume. Additional best practices are outlined in the announcement.

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

The Invoice Service of Google Ads API is out of beta

The InvoiceService is now available for all API users starting with version 6 of the Google Ads API. Earlier API versions will continue to only support this service for allowlisted accounts.

This service retrieves the monthly invoices of Google Ads accounts. Each returned Invoice comes loaded with data (for example: adjustments, regulatory costs, taxes, account budgets) and can be downloaded as a PDF file. Google Ads manager accounts can use the data to automatically reconcile customer invoices. To get started, read through our dedicated guide.

If you have any questions or need additional help, contact us through the forum or at [email protected].

Disabling "lead" category mutates in AdWords API

On March 8, 2021 we're disabling mutates to the Lead category in the AdWords API. The Google Ads API ConversionActionCategory is not affected. This is a follow-on to the conversion category changes and expanded conversion categories announced in September 2020, which provided a finer grained categorization of conversions.

We are making this change because we are seeing some advertisers change their new category conversion types back to Lead category through the AdWords API, resulting in ambiguity since multiple new categories map to this old category. The following table summarizes how the AdWords API will respond to mutates that set the conversion category to Lead.
Existing Category AdWords API READs (Existing behavior) AdWords API Mutate to LEAD Response
Lead Lead OK
“Old” category “Old” category ERROR
“New” lead category Lead OK
“New” non-lead category “Old” category ERROR

Since the AdWords API does not support all the new conversion categories, reading in a new fine grained Lead conversion category will be mapped to Lead upon read, but will continue to be persisted as the finer grained new category. If read through the Google Ads UI or Google Ads API, the new conversion category will be accurately retrieved.

As a recap from our September 2020 announcement, here is the mapping of new conversion category types to existing AdWords API ConversionTracker.Category enum values:
New Conversion Category Mapping to ConversionTracker.Category
Add to cart LEAD
Begin checkout LEAD
Purchase PURCHASE
Subscribe PURCHASE
Sign-up SIGNUP
Phone call lead LEAD
Imported lead LEAD
Submit lead form LEAD
Book appointment LEAD
Request quote LEAD
Get directions LEAD
Outbound click LEAD
Contact LEAD
Download DOWNLOAD
Page view PAGE_VIEW
Engagement DEFAULT
Store visit DEFAULT
Store sale PURCHASE
Other DEFAULT

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

January update to Display & Video 360 API v1

Today we’re releasing an update to the Display & Video 360 API which includes the following features:
More detailed information about this update can be found in the Display & Video 360 API release notes.

Before using these new features, make sure to update your client library to the latest version.

If you run into issues or need help with these new features, please contact us using our support contact form.


Sunset of the Ad Manager API v202002

On Monday, March 1, 2021, in accordance with the deprecation schedule, v202002 of the Ad Manager API will sunset. At that time, any requests made to this version will return errors.

If you’re still using v202002, now is the time to upgrade to a newer release and take advantage of additional functionality. For example, in v202011 we added the getTrafficData method to the ForecastService, which is capable of exploring historical and forecasted network-level data for a particular date range and targeting configuration.

When you’re ready to upgrade, check the full release notes to identify any breaking changes. Keep in mind that v202002 is the final version to use int types for Activity and ActivityGroup, and all later versions use type long. After you’ve considered all of the changes, grab the latest version of your client library and update your code.

As always, don't hesitate to reach out to us on the developer forum with any questions.

Changes to Hotel Ads pricing buckets in the Google Ads API

On February 23rd, Google Ads API will be changing the way Hotel price buckets returns data by utilizing two new values in the hotel_price_bucket segment. Those new values will be added as enums in v6_1, “Lowest Unique” and “Only partner shown”.

Because there is overlap between the two new values and the existing “Lowest tied” value, after February 23rd developers using API versions earlier than v6_1 will see reports with the “Unknown” value wherever the two new values would be shown. This can result in one or two rows with the “Unknown” value.

Example:
Currently, data for ONLY_PARTER_SHOWN and LOWEST_UNIQUE are not returned, instead data is only shown for LOWEST_TIED.
LOWEST_TIED 12
Once the changes are released on February 23rd, developers on API versions v6_1 and greater will see the two new ONLY_PARTER_SHOWN and LOWEST_UNIQUE values, with the two new price buckets being displayed.
LOWEST_UNIQUE 3
ONLY_PARTER_SHOWN 4
LOWEST_TIED 5
After the changes are released on February 23rd, any developers on API versions lower than v6_1 will see “UNKNOWN” where the new values would have otherwise been shown.
UNKNOWN 3
UNKNOWN 4
LOWEST_TIED 5
If you have any questions about this change or any other API feature, please reach out to your account team directly, or contact us via the forum.

Announcing new Real-time Bidding experiments

Google is launching experiments that are intended to provide bidders with an opportunity to test and provide collaborative feedback on ads-privacy proposals–these are features intended to improve user privacy protections and provide mechanisms for testing Chrome Privacy Sandbox proposals. We strongly encourage interested bidders to sign up and participate! Three new experiments made available today are described below.

Experiment #1: TURTLEDOVE simulation

The RTB protocols and infrastructure have been updated to enable a server-side simulation of Chrome’s TURTLEDOVE proposal, as described in the TURTLEDOVE simulation proposal. Bidders interested in participating can reference the TURTLEDOVE RTB Simulation API guide to learn more about the specific API and protocol changes associated with this experiment. Along with these changes, a new biddingFunctions resource for managing bidding functions that are used in the server-side simulation was added to the Real-time Bidding API.

The goal of this simulation is to provide bidders with an opportunity to experiment with Chrome’s proposal before it is implemented in Chrome, so that participating bidders can provide feedback on its viability and effectiveness. The APIs and modified RTB workflow used in the server-side simulation are conceptually similar to the ones that Chrome may later implement for TURTLEDOVE, based on existing proposals and public design discussions. Feedback relevant to Google’s simulation should be directed to the ads-privacy issue tracker, whereas feedback relevant to the TURTLEDOVE proposal itself should be directed to Chrome’s TURTLEDOVE issue tracker. To report bugs or technical questions about this experiment, you may contact the [email protected] support alias.

Experiment #2: Federated Learning of Cohorts (FLoC)

Google will allow participating bidders to experiment with Chrome’s FLoC proposal by simulating FLoC cohorts on its servers, based on algorithms described in this Google Research & Ads whitepaper. To facilitate this experiment, a Floc message has been added to the BidRequest in the Google RTB protocol, and as an extension of the User object for Google’s OpenRTB implementation. The message is structured as follows:


message Floc {
// The value of a cohort ID – a string identifier that is common to a large
// cohort of users with similar browsing habits.
optional string id = 1;
// The type of the FLoC. See
// https://github.com/google/ads-privacy/blob/master/proposals/FLoC/FLOC-Whitepaper-Google.pdf.
enum FlocType {
// Default value that should not be used.
FLOC_TYPE_UNKNOWN = 0;
// FLoC simulated using affinity hierarchical clustering with centroids
// and feature extraction based on Topic categories as described in the
// whitepaper.

SIMULATED_AFFINITY_CLUSTERING_CENTROID_VERTICAL = 2;
// FLoC simulated using SortingLSH clustering algorithm and Domain One-hot
// encoding feature extraction as described in the whitepaper.
SIMULATED_SIMHASH_SORTING_LSH_DOMAIN_ONE_HOT = 3;
// FLoC simulated using a k Random Centers locality-sensitive hash
// function as described in
// https://github.com/google/ads-privacy/blob/master/proposals/FLoC/k-random-centers.md
// with Domain TF-IDF feature extraction as described in the whitepaper.
KCENTER_DOM_FILTERED_TFDIF = 4;
}
optional FlocType type = 2;
}

Only web requests are in scope for the FLoC simulation experiment. In practice, only a small percentage of bid requests for bidders opted-in to the experiment would include this message, and those that do would not include pseudonymous user identifiers such as google_user_id and hosted_match_data.

Floc would also not be populated as a result of privacy controls, such as when users opt out of personalized advertising. Upon winning impressions, bidders can render creatives as usual and use their cookie-based identifiers to attribute conversions–for instance–to measure how well different FLoCs correlate with conversions.

We encourage participants to use the issue tracker to leave feedback on the simulated cohort algorithms. One useful metric to include would be the conversion rates for each FlocType in the experiment, possibly in comparison to regular traffic, where bidders may rely on cookie-based identifiers for targeting and optimization.

Experiment #3: Exchange-enforced frequency capping

The RTB protocols have been updated to enable an experiment for the exchange-enforced frequency capping proposal, which intends to support the critical frequency capping use case for the inventory provided by a single exchange without reliance on user identifiers provided in bid requests. A FrequencyCap message has been added to the BidResponse in the Google RTB protocol, and as an extension of the Bid object for Google’s OpenRTB implementation. The message is structured as follows:


  message FrequencyCap {
// An ID that can represent a bidder's use-case for frequency capping; for
// example, it could represent their campaign, ad, line item, etc. It should
// not contain any user-specific information or identifiers.
optional string fcap_id = 1;

// The time units for which frequency caps can be enforced.
enum TimeUnit {
UNKNOWN_TIME_UNIT = 0;
MINUTE = 1;
DAY = 2;
WEEK = 3;
MONTH = 4;
// When INDEFINITE is used, time_range will be ignored. INDEFINITE means
// the frequency cap will be applied for a long period of time, (longer
// than a month) but not necessarily forever.
INDEFINITE = 5;
}

// The unit of time used to specify the time window for which a frequency
// cap applies.
optional TimeUnit time_unit = 2;

// The length of the time window, in units specified by time_unit, for which
// the frequency cap applies. For instance, if time_unit=WEEK and
// time_range=3, then capping is applied for a three week period. If the
// time_unit=INDEFINITE, this will be ignored.
optional int32 time_range = 3 [default = 1];

// The maximum number of impressions allowed to be shown to a user for
// the provided frequency_cap_id within the time window described by
// time_unit and time_range.
optional int32 max_imp = 4;
}


Additional information about this experiment can be found in the proposal, and we encourage participants to leave feedback in the issue tracker.

Mark Saniscalchi, Authorized Buyers Developer Relations

Ad Policy Error Management is evolving in Google Ads API

On March 1st, 2021, all versions of the Google Ads API will replace policy violations with policy findings for all remaining ad types.

The impact is limited to the creation and update of ads that trigger ad policy errors for the following types:
  • CALL_ONLY_AD
  • EXPANDED_DYNAMIC_SEARCH_AD
  • GMAIL_AD
  • HTML5_UPLOAD_AD
  • IMAGE_AD
  • LEGACY_APP_INSTALL_AD
  • LOCAL_AD
  • RESPONSIVE_DISPLAY_AD
  • RESPONSIVE_SEARCH_AD
  • VIDEO_RESPONSIVE_AD
If your application is impacted by this change and not upgraded before March 1st, 2021, then the ad policy errors will no longer be recognized and the requested exemptions will not be applied.

What’s Changing
Both AdGroupAdService.MutateAdGroupAds and AdService.MutateAds methods will behave differently: What’s Not Changing What to Do
Before March 1st, 2021, make sure to add the support of policy findings in your management of ad policy errors. To get started, you can refer to our guide and code example that are both dedicated to ad policy error management. We recommend testing with the ad types that already use policy findings: EXPANDED_TEXT_AD and RESPONSIVE_SEARCH_AD.

If you have any questions or need additional help, contact us through the forum or at [email protected].

Ad Policy Error Management is evolving in Google Ads API

On March 1st, 2021, all versions of the Google Ads API will replace policy violations with policy findings for all remaining ad types.

The impact is limited to the creation and update of ads that trigger ad policy errors for the following types:
  • CALL_ONLY_AD
  • EXPANDED_DYNAMIC_SEARCH_AD
  • GMAIL_AD
  • HTML5_UPLOAD_AD
  • IMAGE_AD
  • LEGACY_APP_INSTALL_AD
  • LOCAL_AD
  • RESPONSIVE_DISPLAY_AD
  • RESPONSIVE_SEARCH_AD
  • VIDEO_RESPONSIVE_AD
If your application is impacted by this change and not upgraded before March 1st, 2021, then the ad policy errors will no longer be recognized and the requested exemptions will not be applied.

What’s Changing
Both AdGroupAdService.MutateAdGroupAds and AdService.MutateAds methods will behave differently: What’s Not Changing What to Do
Before March 1st, 2021, make sure to add the support of policy findings in your management of ad policy errors. To get started, you can refer to our guide and code example that are both dedicated to ad policy error management. We recommend testing with the ad types that already use policy findings: EXPANDED_TEXT_AD and RESPONSIVE_SEARCH_AD.

If you have any questions or need additional help, contact us through the forum or at [email protected].