Category Archives: Ads Developer Blog

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

Announcing v19.1 of the Google Ads API

Today, we’re announcing the v19.1 release of the Google Ads API. To use any of the v19.1 features, you must upgrade your client libraries and client code. The updated client libraries and code examples will be published next week. This release includes no breaking changes and maintains backwards compatibility for those who have already upgraded to v19.

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.

 - , Google Ads API Team

Unlock Premium Ad Experiences for livestreams with Server-Guided Ad Insertion (SGAI)

We're excited to introduce Google's approach to Server Guided Ad Insertion (SGAI), designed to unlock key benefits:

  • Flexibility: Support for new innovative ad formats to meet publisher’s diverse needs
  • Control: Greater control over ad break scheduling
  • Efficiency: Resource savings and operational simplification

SGAI is an ad insertion method where an ad server instructs the video player on how to manage ad transitions dynamically within the content stream. This technique blends the advantages of two common methods: it offers the seamless ad integration seen in server-side insertion (SSAI) and the implementation ease found in client-side insertion (CSAI). SGAI’s ability to support non-intrusive ad experiences, such as squeezebacks and L-banners, where advertisements appear alongside the continuously playing content, creates prominent branding opportunities and experiences alongside content.

In this post, we'll address the key questions on the core concepts and benefits of this exciting new technology.

What is the "server-guided" part in SGAI?

SGAI uses Google Dynamic Ad Insertion (DAI) to perform ad selection, transcoding, and return the ad pod manifest for the entire ad break, ready for the video player to load and play just like a content stream.

The server-guided aspect highlights the collaborative nature of ad delivery in SGAI. While Google DAI servers do the heavy lifting of building and delivering the ad break, the client app and video player takes control of the ad break timing and insertion.

Control over ad break scheduling

To control the ad break timing, you can use your own infrastructure, such as a packager, an encoder, a manifest manipulator or a direct notification to the client app. Ahead of the ad breaks, you can use the Ad Manager’s Early Ad Break Notification API to create and schedule upcoming ad breaks, optimizing ad fill rate for high concurrency livestream events.

Using these tools, you define the expected start time, duration, and metadata of the ad break and signal Google Ad Manager, your client app and the video player to prepare and play the ad break.

How flexible is SGAI?

There are two different methods of using server guided ad insertion to meet diverse publisher needs:

  • Client-side ad stitching: the client app listens to the video player's timed metadata for upcoming ad break events or follows a preset ad schedule. The client app proactively loads the ad break manifest.
    At ad break start, the client app can switch between content and ad, or arrange both content and ads simultaneous playbacks to implement innovative ad formats, such as squeezeback, L-banner, side-by-side windows.
  • Server-side ad stitching: the packager, or encoder, inserts an ad marker pointing to the ad manifest into the content manifest. The video player reactively loads the ad break manifest and switches between content and ad in due time.

We design our SGAI to work with standards, such as HLS interstitials and the upcoming DASH specification. This allows for easy interoperability across different players, client platforms and streaming tech stacks.

How does SGAI client-side ad stitching work?

This section covers an SGAI client-side example in which the video player parses SCTE-35 markers in the content manifest and schedules an ad break. This approach offers server resource savings and operational simplification.

The livestream flow has the following key steps:

  1. The client app loads the IMA SDK to create DAI pod serving stream sessions and process ad events.
  2. The client app uses a video player for playback, and constructs the HLS or DASH ad pod manifest URLs, incorporating SCTE-35 data as needed.
  3. A few seconds before the expected ad break time, the video player loads the ad pod manifest. At the beginning of the ad break, the client app switches from the content to the ad playback.

How does SGAI server-side ad stitching work?

Livestream workflows with SGAI server-side ad stitching follow similar steps above, but a packager inserts ad markers pointing to ad pod manifest URLs shortly before each ad break.

Next Steps

We encourage you to explore SGAI documentation to create premium ad experiences with efficiency and adaptability. To get started on using SGAI, contact your Google account manager.

- Thang Duong, Ads Developer Relations and Sourya Roy, Senior Product Manager, Google Ad Manager

Launching Structured Data Files v8.1 and upcoming changes

Today we’re announcing the general availability of Structured Data Files v8.1. All users can now use SDF v8.1 to upload and download SDFs in the Display & Video 360 UI, and to download SDFs through the Display & Video 360 API.

SDF v8.1 adds support for controlling inventory source settings for Demand Gen ad groups, enforces OMID targeting set at the advertiser level, and renames TrueView Content Filter column to Inventory Mode in “Line Item” and “Insertion Order” files.

In addition to launching SDF v8.1, we are also announcing the following two breaking changes to Structured Data Files that will go into effect on April 22, 2025:

  • You will no longer be able to create YouTube video action line items using SDF. Instead, customers should create Demand Gen line items. Any attempted creation of line items using SDF upload with a Subtype column value of “Action” and a Type column value of “TrueView” will fail.
  • You will be required to include the value “Video Partners” in the TrueView Inventory Source Targeting column of line items with the Type column value of “Demand Gen”. Once this enforcement begins, the value will be backfilled for existing line items and included when downloading new Structured Data Files. To control whether ad groups within Demand Gen line items serve on Google Display Network inventory, you will be required to update to SDF v8.1 and set your desired values in the Demand Gen Inventory Source Strategy and Demand Gen Enabled Inventory Sources columns for ad groups. More details on this renaming and inventory expansion can be found in the Display & Video 360 Help Center.

Full details on the changes between v8 and v8.1 can be found in the Structured Data Files release notes. If you are still using v6, v7 or v7.1, you can follow the instructions in our v7 and v8 migration guides.

If you run into issues or need help with this new version, please follow the instructions in our support guide, or contact us using our contact form.

- Trevor Mulchay, Display & Video 360 API Team

Deprecation of Display & Video 360 API v3

Today, we are deprecating Display & Video 360 API v3. We will sunset v3 on October 7, 2025. Please migrate to Display & Video 360 API v4 before the sunset date to avoid an interruption of service.

New features will not be added to v3 now that it is deprecated. All new feature releases will target v4 exclusively. Read our release notes for more information on updates made to the API in v4 and see our GitHub repository for new code samples using v4. Follow the steps in our v4 migration guide to migrate.

If you run into issues or need help with this new version, please follow the instructions in our support guide or contact us using our contact form.

- Trevor Mulchay, Display & Video 360 API Team

Google Ads API Introducing New Error Codes for Invalid Developer Tokens Starting April 28, 2025

Previously, if any Google Ads API request had an invalid developer token, the API returned an OAUTH_TOKEN_HEADER_INVALID error, which is also used for other invalid request header values. To make it clear when the authentication error is specifically caused by an invalid developer token, we are changing the API to return a new error code, DEVELOPER_TOKEN_INVALID, for version v19.1 of the Google Ads API. All API versions before v19 will handle invalid developer tokens by throwing a DEVELOPER_TOKEN_NOT_APPROVED error instead. If you are using version v19 of the API with our client libraries, you will need to update to the latest version of the client libraries after the v19.1 release. These changes will be effective starting April 28, 2025.

Anyone who has already set up the Google Ads API to make successful calls are highly unlikely to be affected by this change. It is mainly meant to improve the experience of new developers onboarding to the API.

If you have any questions, please ask them in the Google Ads API forum. We're here to help!

 - Dora Sun - Google Ads API Team

Upcoming Performance Max campaign migration to enable brand guidelines

Starting on May 1, 2025, we will begin to automatically enable brand guidelines for Performance Max campaigns that use the same brand assets (BUSINESS_NAME, LOGO, and LANDSCAPE_LOGO) across all asset groups.

Please note the rollout timelines:
  • For Google Ads UI users: The process will begin on May 1, 2025 for customer IDs that exclusively manage their campaigns using the UI.
  • For API users: This process will begin on June 1, 2025.
The overall process across all campaigns is expected to be complete by July 31, 2025.

Important Notes:
  • Only campaigns using consistent business names and logo assets across all asset groups will be automatically migrated. Campaigns with variations in these assets will not be migrated.
  • All eligible Performance Max campaigns under a customer ID will be migrated simultaneously.
  • After migration, each migrated campaign will have its own set of brand assets stored at the campaign level using CampaignAsset.
  • You can tell if a campaign has been migrated by checking its Campaign.brand_guidelines_enabled field.
Actions Required
If your application creates asset groups, update your code to check the campaign’s Campaign.brand_guidelines_enabled field. This will tell you whether to include brand assets in the new asset group.

If your application modifies brand assets, update your code to check the campaign’s Campaign.brand_guidelines_enabled field. This will tell you where to save the brand asset; either on a campaign using a CampaignAsset or on an asset group using an AssetGroupAsset.

To avoid extra steps later, we strongly recommend migrating all of your campaigns now using CampaignService.EnablePMaxBrandGuidelines. If you migrate your campaigns manually, each CampaignService.EnablePMaxBrandGuidelines request can only include 10 EnableOperations.

If you have any questions or need help, check out the Google Ads API support page for options.
 - Sarah Pollack, Google Ads API Team

Promoting Display & Video 360 API v4 to general availability

We’re pleased to announce that we are promoting Display & Video 360 API v4 from beta to general availability. With v4 entering general availability, it is now our recommended version. Our guides have been updated to reflect v4 features and conventions.

We recommend migrating from v3 to v4 at your earliest convenience, as v3 will be deprecated and sunset in the coming months. See instructions on migrating to v4 in our migration guide and an exhaustive list of changes made in v4 in our February 13, 2025 release notes.

Before trying to call v4, make sure to update your client library to the latest version.

If you run into issues or need help using this new version, please contact us using our support contact form.

- Trevor Mulchay, Display & Video 360 API Team

Upcoming change to LowerTargetRoas recommendations in the Google Ads API and Google Ads scripts

As of v17 of the Google Ads API, recommendations of type LOWER_TARGET_ROAS have included a current_average_target_micros as a whole currency value instead of a micros value (where one million is equivalent to one currency unit) as indicated by the field name. On April 23, 2025, we are rolling out a fix to populate current_average_target_micros with the micros value.

Note that as a result of the incorrect unit, the currently returned current_average_target_micros value is truncated and is therefore less precise than the micros equivalent. If you were converting the existing value to micros by multiplying by 1,000,000, the resulting value wouldn't necessarily be correct because any digits past the first position are dropped. For example, a current_average_target_micros value of 5 might have been converted to 5,000,000 in micros before the change, but could be returned as 5,750,000 (more precise) after the change.

What do I need to do?

If you use the Google Ads API or Google Ads scripts to query the recommendation resource for recommendations of type LOWER_TARGET_ROAS, and your application logic uses the current_average_target_micros field, you must update your application to treat the value as micros instead of a whole budget value for when the change takes effect on April 23, 2025.

If you have any questions or need help, check out the Google Ads API support page for options.

 - Laura Chevalier, Google Ads API Team

REST code examples now available for the Google Ads API

Historically, we have always heard from the Google Ads API developer community that code examples are one of the most useful tools to learn about the API and its features. For a long time, however, our API documentation offered code examples for the Google Ads client libraries, but not for REST. We've heard requests from the community to offer more REST code examples, and so we've been working hard to create and integrate a rich set of REST examples directly into our developer documentation.

Now, alongside client library examples, you'll find corresponding REST examples showing you exactly how to structure your curl commands or equivalent code in your preferred language to perform common operations like:
  • Create customer accounts
  • List accessible accounts
  • Manage recommendations
  • Generate keyword ideas
  • And more!
You can find these examples in relevant sections of the Google Ads API documentation on our developer site. For instance, when you look at the guide for listing accessible accounts, you'll now see a "cURL" tab alongside other language options, providing a clear and concise REST-based example.

At the moment, we've added a small, but substantial, subset of examples. We're adding more soon.

Have ideas for additional REST examples?
You can help us prioritize which examples to add and also help implement them. To request a specific code example, open an issue on the REST code examples GitHub repository. You can also open pull requests to help create new examples, or expand the existing ones. Our team will review your submission, and your contribution could help other Google Ads API users.

We hope this addition of REST examples, driven by your valuable feedback, will significantly improve the development experience for a wide range of Google Ads API users. We're excited to see how these examples help you build even more innovative solutions.
 - Mattia Tommasone, Google Ads API Team

Improved Change Tracking in Google Ads API

Over the next several Google Ads API updates, we'll be adding new types of resources you can track using the ChangeStatus feature.

What this means for you:
  • More detailed tracking: You'll soon be able to better track changes to your Google Ads accounts.
  • Important - Check for UNKNOWN changes: Even in older versions of the API, you might start seeing new change entries. These entries will show up as UNKNOWN resource types because the older versions won’t support the new values.
How to prepare:
  • Handle UNKNOWN: If your app uses ChangeStatus, make sure it can handle entries with a resource type of UNKNOWN. This will prevent errors when the new types are added.
  • Update to the latest API version: Once the new version is released, updating your app will show the correct, specific names of the new change types instead of UNKNOWN.
  • We'll announce the exact new resource types in the release notes when the update is live.
If you have any questions, please ask them in the Google Ads API forum. We're here to help!
- Mike Cloonan, Google Ads API Team