Category Archives: Ads Developer Blog

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

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].

Changes to conversion columns in AdWords API and Scripts

What's changing?
We are introducing restrictions on certain combinations of conversion columns in AdWords API and Google Ads scripts reports. If your reporting queries include these column combinations, you need to fix your queries before Feb 15, 2021.

Technical details
Starting the week of Feb 15, 2021, you will receive a ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT error if your AdWords API report request contains columns from both of the restricted column sets listed below. Similarly, calls to the AdsApp.report method in Google Ads scripts will fail for queries with these restricted column combinations.

Restricted conversion columns:
  • ConversionAdjustment
  • ConversionAdjustmentLagBucket
  • ConversionAttributionEventType
  • ConversionCategoryName
  • ConversionLagBucket
  • ConversionTrackerId
  • ConversionTypeName
Metrics columns:
  • AllConversionRate
  • ConversionRate
  • CostPerAllConversion
  • CostPerConversion
  • CostPerCurrentModelAttributedConversion
The ReportDefinitionService.getReportFields method will reflect these restrictions in the exclusiveFields list of each impacted column.

What should you do?
Before Feb 15, 2021, review and modify the reporting queries in your AdWords API and Google Ads scripts applications to stop using the prohibited column combinations.

Why is this changing?
These column combinations are currently disallowed by the Google Ads UI, Google Ads Editor and the Google Ads API. This change makes the AdWords API and Google Ads scripts behaviour consistent with the rest of the Google Ads platform.

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

Update to Customer Match Uploads in the Google Ads API and the AdWords API Starting March 1, 2021

On March 1, 2021, the Google Ads API and the AdWords API will have a new upload limit for each Customer Match upload request. There is no change to the limit of the overall Customer Match audience list size.

What code do I need to change?
When uploading user identifiers for Customer Match, check that the number of user identifiers you are uploading per request is within the limit.
Google Ads API AdWords API
Limit 100,000 per request 500,000 per user list ID per request
Method OfflineUserDataJobService.AddOfflineUserDataJobOperations() AdWordsUserListService.mutateMembers()
Field userIdentifiers membersList
Error on exceeding upload limit TOO_MANY_USER_IDENTIFIERS TOO_MANY


Why is this changing?
In order to make the processing of Customer Match user identifiers more efficient, we needed to set the new upload limit.

If you have any questions while updating your code, please reach out to us on our Google Ads API and AdWords API forum.

The google_global_site_tag will no longer be filterable in Google Ads API

What's changing?
Starting the week of Jan 25, 2021, the customer.remarketing_setting.google_global_site_tag field will no longer be filterable in the Google Ads API. If you use this field in a WHERE clause of a GAQL query in a call to the GoogleAdsService.Search or GoogleAdsService.SearchStream method, you will receive a QueryError.PROHIBITED_FIELD_IN_WHERE_CLAUSE error. Similarly, the GoogleAdsFieldService.SearchGoogleAdsFields method will report this field as non-filterable. This change affects all versions of the Google Ads API.

What should you do?
Before Jan 25, 2021, review and modify your Google Ads API reporting queries to stop using the google_global_site_tag field for filtering purposes.

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

Google Ads API v3 sunset reminder

Google Ads API v3 will sunset on February 10, 2021. After this date, all v3 API requests will begin to fail. Please migrate to a newer version prior to February 10, 2021 to ensure your API access is unaffected.

We've prepared various resources to help you with the migration:

If you have questions while you’re upgrading, please reach out to us on the forum or at [email protected].

December 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.

Live Webinar: Website Conversions & Audience Remarketing

The Google Ads API Developer Relations team will be hosting a live webinar, Website Conversions & Audience Remarketing with the Google Ads API, on December 11 at 10 AM EST (3 PM GMT).

Mark your calendar


Prerequisites
In order to get the most out of this webinar, we suggest you develop a basic understanding of the Google Ads API. In order to learn more, please visit our API Overview documentation or check out this Google Ads API Overview workshop from 2019. In addition, you may find this post useful to learn how conversion tracking works in Google Ads.

Agenda
The webinar will cover the topics below and include code walkthroughs to demonstrate how to perform different actions with the Google Ads API client libraries. We will also be hosting a live Q&A at the end.
  • What conversion actions are
  • How to create and utilize conversion actions
  • How remarketing works in the Google Ads API
  • How to define different audience types
  • How to measure audience performance
Reminders
Feel free to add the event to your calendar. In addition, you can set a reminder for the event on YouTube by clicking the “Set reminder” button on the YouTube event page.

We look forward to sharing our knowledge of the Google Ads API with you and answering your questions. If you have any questions or need additional help, contact us via the forum or at [email protected]