Category Archives: Ads Developer Blog

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

Removing support for old OpenRTB versions

Starting today, Google’s OpenRTB implementation will be updated to only include fields and messages for the latest supported version, OpenRTB 2.5. This will affect the OpenRTB protocol and any APIs or tools used to configure bidder endpoints.

OpenRTB protocol changes
As a result of supporting only the latest version, the following fields are deprecated and will no longer be populated:
  • BidRequest.imp[].banner.hmax
  • BidRequest.imp[].banner.hmin
  • BidRequest.imp[].banner.wmax
  • BidRequest.imp[].banner.wmin
Additionally, the following fields may now be populated for all bidders:
  • BidRequest.device.ext.user_agent_data
  • BidRequest.device.geo.accuracy
  • BidRequest.device.geo.utcoffset
  • BidRequest.imp[].banner.api: This will support the value MRAID_3.
  • BidRequest.imp[].banner.format
  • BidRequest.imp[].banner.vcm
  • BidRequest.imp[].metric
  • BidRequest.imp[].native.api: This will support the value MRAID_3.
  • BidRequest.imp[].video.api: This will support the value MRAID_3.
  • BidRequest.imp[].video.companionad.api
  • BidRequest.imp[].video.companionad.format
  • BidRequest.imp[].video.companionad.vcm
  • BidRequest.imp[].video.linearity
  • BidRequest.imp[].video.maxduration
  • BidRequest.imp[].video.placement
  • BidRequest.imp[].video.playbackend
  • BidRequest.imp[].video.skip
  • BidRequest.site.mobile
  • BidRequest.test
  • BidRequest.wlang
If a newer OpenRTB specification is published, Google may upgrade the current supported version to match it. Previously deprecated fields that are removed from the specification will also be removed from the protocol. Non-deprecated fields that are removed will be marked as deprecated in the protocol, and eventually removed following a brief deprecation period.

Authorized Buyers Real-time Bidding API changes
The behavior of the bidders.endpoints resource will change. The following enum values for bidProtocol will be deprecated:
  • OPENRTB_2_2
  • OPENRTB_2_3
  • OPENRTB_PROTOBUF_2_3
  • OPENRTB_2_4
  • OPENRTB_PROTOBUF_2_4
  • OPENRTB_2_5
  • OPENRTB_PROTOBUF_2_5
New enum values for bidProtocol will be added to represent the latest supported OpenRTB version in either JSON or Protobuf formats:
  • OPENRTB_JSON
  • OPENRTB_PROTOBUF
If you have existing endpoints with their bidProtocol set to any of the deprecated values above, they will automatically be migrated to either OPENRTB_JSON or OPENRTB_PROTOBUF depending on the format specified by the original value. Additionally, any modifications to your endpoints that would set bidProtocol to the deprecated values will instead set it to OPENRTB_JSON or OPENRTB_PROTOBUF.

Feel free to reach out to us via the Authorized Buyers API support forum with any feedback or questions you may have related to these changes.
- Mark Saniscalchi, Authorized Buyers Developer Relations

Announcing deprecation and sunset of Similar Audiences

On November 1, 2022, we announced our plans to sunset Similar Audiences in 2023 as we work on simplifying our existing product portfolio and strengthening our future-proof solutions in a changing privacy landscape. We expect to roll out this change in two phases for both Google Ads API and Google Ads scripts:
  1. Starting May 2023: New similar audiences segments will stop being generated, and existing similar audiences segments will no longer be added to campaigns and ad groups. Ad groups and campaigns that already have similar audience segments attached will continue to function as expected.
  2. Starting August 2023: Similar audience segments will be removed from all ad groups and campaigns. You will continue to have access to historical reporting data for similar audience segments from past campaigns.
What is the impact on Google Ads API?
Any requests that mutate entities related to Similar Audiences will start failing with errors. This includes: The data retrieved using GoogleAdsService.Search or GoogleAdsService.SearchStream requests will gradually be depleted of any references to Similar Audiences. This includes queries relying on the reports user_list, audience, combined_audience, and any others that are based on targeting, or conversion values segments or metrics. When we get closer to the sunset date, check out the deprecation and sunset guide for the exact errors that will be thrown.

What is the impact on Google Ads scripts?
Any requests that relate to Similar Audiences are impacted. Mutating requests will start failing with errors and reporting requests will start returning data depleted of any references to Similar Audiences. This includes: What should I do?
We recommend that API users manually migrate and stop using Similar Audiences before May 2023 in their calls to avoid any disruptions. You can refer to the announcement and Help Center article to learn more about migration options.

If you have any questions or need additional help, contact us through the forum or at [email protected].
Pierrick Voulet, Google Ads API Team

Announcing v202211 of the Google Ad Manager API

We're pleased to announce that v202211 of the Google Ad Manager API is available starting today, November 2nd. This release lays the groundwork for multiple third-party impression tracking URLs. ImageCreative and other creative types replaced the string field thirdPartyImpressionTrackingUrl with the list field thirdPartyImpressionTrackingUrls. Currently only a single URL can be provided in the list.

For the full list of changes, check the release notes. Feel free to reach out to us on the Ad Manager API forum with any API-related questions.
- Chris Seeley, Ad Manager API Team

Upcoming changes to targeting expansion in Display & Video 360 API

On November 7, 2022, optimized targeting will gradually begin replacing targeting expansion for display, video, and audio line items under a Display & Video 360 partner, with the new feature launched for all partners by November 9, 2022. We will be making changes to the Display & Video 360 API to reflect this. These changes may impact the existing configurations of your resources, and the behavior for your currently successful requests.

Read the optimized targeting and targeting expansion guides to understand the differences between optimized targeting and targeting expansion. Optimized targeting is not available for over-the-top line items, or line items that use fixed bidding.

There will be no structural changes to the existing targetingExpansion field or TargetingExpansionConfig object in Display & Video 360 API LineItem resources. Once optimized targeting replaces targeting expansion for your partner, these fields will be used to manage optimized targeting in the following manner:
  • The targetingExpansionLevel field will only support two possible values:
    • NO_EXPANSION: optimized targeting is off
    • LEAST_EXPANSION: optimized targeting is on
  • NO_EXPANSION will be the default value for the targetingExpansionLevel field and will be automatically assigned if you do not set the field
  • If you set targetingExpansionLevel to one of the following values, it will automatically be reset to LEAST_EXPANSION:
    • SOME_EXPANSION
    • BALANCED_EXPANSION
    • MORE_EXPANSION
    • MOST_EXPANSION
  • excludeFirstPartyAudience will continue to set whether first-party audiences should be excluded from targeting. This will now apply to optimized targeting instead of targeting expansion.
  • If you turn on optimized targeting for an ineligible line item, the request will not return an error and the change will persist. However, you must update the line item to be eligible before it will use optimized targeting when serving.
  • Optimized targeting will not automatically be turned on for eligible line items created or updated by the Display & Video 360 API.
We will also be updating the configurations of existing line items as follows: To prepare for this change, it is recommended that you turn on automated bidding for line items currently using fixed bidding with targeting expansion before November 7, 2022 to continue using audience expansion to improve campaign performance.

If you have questions regarding these changes or need help with these new features, please contact us using our support contact form.
- Trevor Mulchay, Display & Video 360 API Team

October 2022 update to Display & Video 360 API v2

Today we’re announcing the October 2022 update to Display & Video 360 API v2, which is still in beta. This update includes the following features:
  • Partial insertion order targeting write support for a subset of targeting types with the addition of create and delete methods to the insertion order AssignedTargetingOptions service.
  • The ability to duplicate an existing line item to create a new line item with identical settings and assigned targeting under the same insertion order.
More detailed information about this update can be found in the Display & Video 360 API release notes and updated instructions on migrating from v1 to v2 can be found in our migration guide. Before using these new features, make sure to update your client library to the latest version.

If you have questions regarding the breaking changes or run into issues or need help with these new features, please contact us using our support contact form.
- Trevor Mulchay, Display & Video 360 API Team

Announcing v12 of the Google Ads API

Today, we’re announcing the v12 release of the Google Ads API. To use some v12 features, you’ll 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.
Thanet Knack Praneenararat, on behalf of the Google Ads API Team

Google Ads API Video Roundup

The Google Ads Developers Channel is your video source for release notes, best practices, new feature integrations, code walkthroughs, and video tutorials. Check out some of the recently released and popular videos and playlists below, and remember to subscribe to our channel to stay up to date with the latest video content.

Google Ads API Best Practices - Error Handling and Debugging
In this episode of the Google Ads API Best Practices Series, we discuss how to handle errors that may occur when interacting with the Google Ads API, along with tools that may help you debug your applications, such as logging and the REST interface.
Meet the Team with David Wihl
In this video, David Wihl shares a bit about his role as a Developer Relations Engineer at Google and discusses his work in supporting the Performance Max campaign API integration.

[Live Demo] Building a Google Ads API Web App
Getting started with the Google Ads API? In this 8-episode series, we take a deep dive into developing web apps with the Google Ads API, with a focus on the OAuth flow, by building a multi-tenant app entirely from scratch.

Logging & Monitoring
This miniseries covers the basics of adding logging and monitoring to your Google Ads API integration and then goes into more advanced topics, with a special focus on Cloud tooling. Google Ads Query Language (GAQL)
In this series, we cover everything you need to know about the Google Ads Query Language to make reporting requests against the Google Ads API. We begin with the basics and build in subsequent episodes to cover various nuances of GAQL. We even dive into the various tools available to help you structure your queries. This playlist will equip you with the information you need to know to become a GAQL power user. For additional topics, including Authentication and Authorization and Working with REST, check out the Google Ads API Developer Series.

As always, feel free to reach out to us with any questions via the Google Ads API forum or at [email protected].
- Devin Chasanoff, on behalf of the Google Ads API Team

Google Publisher Tags add official TypeScript type definitions

Today we're happy to announce the release of official TypeScript type definitions for Google Publisher Tags (GPT)!

Why TypeScript?

According to a recent State of JS developer survey, nearly 70% of developers regularly use TypeScript in some capacity, up from 60% the year before. As this segment of the community continues to grow, we are committed to providing the best experience possible for those working with TypeScript and GPT. We believe this is important not just because TypeScript is popular, but because it helps developers validate the correctness of their code and provides a number of quality of life improvements that make working with GPT more delightful.

How we got here

Until now, a number of community-led projects such as @types/doubleclick-gpt and @types/googletag have provided unofficial GPT type definitions. While these projects have done a great job of making our API more accessible to TypeScript developers, manually curated type definitions inevitably lag behind changes made to GPT, leading to those definitions sometimes being out of date. To address this, we've updated our release process to automatically generate type definitions from internal source code and sync changes to our own GitHub repository and the DefinitelyTyped project. This ensures that our official definitions are always up to date with the most recently released versions of GPT.

Try it and let us know what you think

For users new to TypeScript, we've published a TypeScript and Google Publisher Tags guide that covers the basics and provides a demo of the new type definitions in action. For those already familiar who want to try the new definitions right away, they can be installed via NPM by running: 

npm install --save-dev @types/google-publisher-tag

If you'd like to make a suggestion, report a bug, or leave any other feedback about this new offering, feel free to open an issue on our GitHub issue tracker.

 - Jonathon Imperiosi, Google Publisher Tags Team

Google Ads API 2023 release and sunset schedule

We’re announcing our tentative 2023 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.

Version Planned Release
Type* 		Projected launch* Projected sunset*
V13 Major January/February 2023 January 2024
V13_1 Minor April/May 2023 January 2024
V14 Major May/June 2023 May 2024
V14_1 Minor July/August 2023 May 2024
V15 Major September/October 2023 September 2024
*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.
- David Stevens, Google Ads API Product Manager

Sunsetting support for Top content bid adjustments in Google Ads API

We recently announced that Top content bid adjustments are no longer available for any campaigns. To align with this change, Google Ads API will make the following changes starting November 1, 2022.

  1. Attempting to set an AdGroupBidModifier with its preferred_content field set will fail with an ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT error.
  2. Attempting to retrieve an AdGroupBidModifier with its preferred_content field set will return a zero value for the bid_modifier field.
If you need to retrieve the existing values for these fields for future reference, we recommend that you download these values before November 1, 2022.

If you have any questions or need additional help, contact us using any of the following support options: - Anash P. Oommen, Google Ads API Team