Category Archives: Ads Developer Blog

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

Rescheduled changes to targeting expansion in Display & Video 360 API and Structured Data Files

On March 25, 2023, optimized targeting will gradually begin replacing targeting expansion for all display, video, and audio line items in Display & Video 360. By mid-April, optimized targeting will be live for all partners. These changes will be reflected in Display & Video 360 API and Structured Data Files (SDF), and might impact your existing implementation and the success of your requests.

Similar changes were previously announced and subsequently postponed late last year, but these rescheduled changes have some important differences. Please read this blog post in its entirety if you use the targetingExpansion field in the Display & Video 360 API or the “Audience Targeting - Similar Audiences” column in SDF to configure your Display & Video 360 line items.

Changes in the Display & Video 360 API

Optimized targeting will be configured using the existing targetingExpansion field and 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 ways:

  • The targetingExpansionLevel field will only support two possible values:
    • NO_EXPANSION: optimized targeting is off.
    • LEAST_EXPANSION:optimized targeting is on.
  • Optimized targeting will not automatically be turned on for eligible line items created or updated by the Display & Video 360 API. 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 be deprecated. If set to true, it will automatically be reset to false.
  • 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.

We will also update the configurations of existing line items as follows:

To aid in this migration, we are adding a new LineItemWarningMessage value to Display & Video 360 API v1 and v2. The warning value DEPRECATED_FIRST_PARTY_AUDIENCE_EXCLUSION will be added to the warningMessages field of line items that have excludeFirstPartyAudience set to true.

Changes in the Structured Data Files

Targeting expansion is currently set using the “Audience Targeting - Similar Audiences” column in Line Item and Insertion Order SDF formats. These columns will be deprecated when optimized targeting replaces targeting expansion. When downloading SDFs, this column will always be set to FALSE and when uploading SDFs, the value of this column will be ignored.

Eligible line items created using SDF upload will have optimized targeting turned off by default. You will not be able to manage optimized targeting configurations using existing SDF versions and must instead use the Display & Video 360 UI or API.

Upcoming SDF v6 will support optimized targeting configurations. The SDF v6 launch will be announced on the Google Ads Developer Blog and in the SDF release notes.

Preparing for these changes

To prepare for these changes, we recommend the following:

  • Turn on automated bidding for line items currently using fixed bidding with targeting expansion before March 25, 2023 so that they are eligible for optimized targeting.
  • Update your Display & Video 360 API integration to directly exclude any first-party audiences using audience targeting before March 25, 2023 to account for the deprecation of the excludeFirstPartyAudience field.
  • Update your Structured Data Files integration to no longer use the “Audience Targeting - Similar Audiences” column in Line Item and Insertion Order SDFs before March 25, 2023 to account for the column deprecation.

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

Google Ads API v11 sunset reminder

Google Ads API v11 will sunset on March 29, 2023. After this date, all v11 API requests will begin to fail. Please migrate to a newer version prior to March 29, 2023 to ensure your API access is unaffected.

We've prepared various resources to help you with the migration: In addition, using the Google Cloud Console, you can view the list of methods and services to which your project recently submitted requests:
  1. Open the Dashboard page (found under APIs & Services) in the Google Cloud Console.
  2. Click on Google Ads API in the table.
  3. On the METRICS subtab, you should see your recent requests plotted on each graph. At the bottom of the page, you’ll see the Methods table, where you can see which methods you’ve sent requests to. The method name includes a Google Ads API version, a service, and a method name, e.g., google.ads.googleads.v11.services.GoogleAdsService.Mutate. In this way, you can see all versions that you’ve used recently.
  4. (Optional) Click on the time frame at the top right of the page if you need to change it.
If you have questions while you’re upgrading, please reach out to us on the forum or at [email protected].
 - Thanet Knack Praneenararat, Google Ads API Team

Changes to location targeting in Google Ads Search, Shopping, Display, and Performance Max campaigns

Starting on April 14, 2023, there will be changes made to the location targeting settings for Search, Shopping, Display, and Performance Max campaigns in the Google Ads API. We are making this change to simplify the location targeting portfolio and improve advertiser performance. All versions will throw errors if you try to set the location target settings to one of the values shown below.

Campaign.geo_target_type_setting fields
positive_geo_target_type can no longer be set to SEARCH_INTEREST for Search, Shopping, and Display campaigns. The default value is PRESENCE_OR_INTEREST.
negative_geo_target_type can no longer be set to PRESENCE_OR_INTEREST for Performance Max, Search, Shopping, and Display campaigns. The default value is PRESENCE.
The error returned if these values are used is SettingError.SETTING_VALUE_NOT_COMPATIBLE_WITH_CAMPAIGN.

On April 24, 2023, we will start performing any necessary auto-migration of fields to the new default values until no more invalid combinations exist. The auto-migration will occur on a per-campaign basis. You can confirm that the migration is complete for a Google Ads account by checking that these two queries return zero rows.


SELECT campaign.id, campaign.geo_target_type_setting.positive_geo_target_type, campaign.advertising_channel_type FROM campaign WHERE campaign.advertising_channel_type IN ('DISPLAY', 'SEARCH', 'SHOPPING') AND campaign.geo_target_type_setting.positive_geo_target_type = 'SEARCH_INTEREST' LIMIT 1
SELECT campaign.id, campaign.advertising_channel_type, campaign.geo_target_type_setting.negative_geo_target_type FROM campaign WHERE campaign.geo_target_type_setting.negative_geo_target_type = 'PRESENCE_OR_INTEREST' AND campaign.advertising_channel_type IN ('DISPLAY', 'PERFORMANCE_MAX', 'SEARCH', 'SHOPPING') LIMIT 1
Where can I get support?
If you have questions, please reach out to us on the forum or at [email protected].
Nadine Wang, Google Ads API Team

Updating Display & Video 360 API creative asset media ID values on April 5, 2023

On April 5, 2023, we will be updating mediaId values in the Display & Video 360 API for all uploaded Asset resources and requiring that customers use these new ID values when associating assets with Creative resources.

What is changing?

We are changing the ID space that is used to identify creative assets. This means that assets previously uploaded to Display & Video 360, such as image, video, and HTML files, will now have new IDs.

This change will have the following effects:

  • Existing mediaId values of assets associated with a creative resource through the assets field will automatically be updated to use this new ID space.
  • Attempting to use any previously generated mediaId values to associate an asset to a creative will return an error.

What do I need to do?

In preparation for this change, we recommend that you stop using any cached media IDs when creating or updating creatives, and instead upload assets immediately before using them for creative production.

After April 5, 2023, we recommend updating any cached media IDs to the new values by retrieving them from associated creative resources or re-uploading them using advertisers.assets.upload.

If you are not caching media IDs, you do not need to do anything in regards to this change.

If you have questions regarding this change, please contact us using our support contact form.

- Trevor Mulchay, Display & Video 360 API Team

Announcing v202302 of the Google Ad Manager API

We're pleased to announce that v202302 of the Google Ad Manager API is available starting today, February 21st. This release brings a number of new features for Reporting including Yield Group metrics, Programmatic metrics, and time zone support.

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

Bid Manager API v1.1 will sunset on April 27, 2023

The Bid Manager API v1.1 will sunset on April 27, 2023. The Bid Manager API v1.1 was deprecated in August 2022 and originally scheduled to sunset on February 28, 2023.

Please migrate to v2 before the sunset date to avoid an interruption of service.

You can read our release notes for more information about v2. Follow the steps in our v2 migration guide to help you migrate from v1.1 to v2.

If you run into issues or need help with your migration, please contact us using our support contact form.

- Trevor Mulchay, Display & Video 360 API Team

Announcing v13 of the Google Ads API

Today, we’re announcing the v13 release of the Google Ads API. To use some of the v13 features, you will 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

Image and Location Auto-migrations in Google Ads API

What’s changing?
Beginning on April 3, 2023, we will start auto-migrating image and location extensions to assets. The auto-migration is scheduled to end on September 15, 2023.

Once the image and location extensions have been migrated to assets, you won’t be able to access the image and location extensions. The image and location assets will be the entities that are served. Metrics for the extensions will be available until sometime in 2024.

Why is this changing?
Extensions are migrating to assets.

What do I need to do?
Upgrade to version v12 or v13 of the Google Ads API. We recommend that you upgrade to v13.

The auto-migration will not keep a mapping of feed IDs to asset IDs. If you would like to keep a record of feed IDs to asset ID mappings, create a new asset image or location based on your feed, and save that ID mapping locally.

Can I opt-out of the auto-migration?
No. We offered an opt-out for the first batch of auto-migration, but you can’t opt out of this auto-migration.

How will the migrations occur?
The migrations occur at an account level. During the migration of an account, which will take several minutes, you won’t be able to execute any image or location mutations of either extensions or assets. When the migration is complete, you will have access to the assets.

The image and location migrations are not synchronized. It is likely they will occur at different times for each account.

How do I know when an account has been migrated?
Use the following v13 fields, in the Customer resource, to track the status of the migration: 

bool image_asset_auto_migration_done
string image_asset_auto_migration_done_date_time
bool location_asset_auto_migration_done
string location_asset_auto_migration_done_date_time
If you are using v12, you can instead consult the UI and you will see an alert once your account has been migrated.

What happens after the auto-migration?
Accounts that have been migrated will reject mutate calls for feed-based entities.

If you have any questions, please reach out to us on the forum.
Bob Hancock, Google Ads API Team

Use Mobile Ads SDK Volume APIs Correctly to Maximize Video Ad Revenue

The volume control APIs provided by the Google Mobile Ads SDK are intended to mirror your app’s own custom volume controls. Utilizing these APIs ensures that the user receives video ads with the expected audio volume.

We’ll talk about some best practices implementing the volume control APIs in your iOS, Android or Unity project.

Why are we mentioning this?

Publishers can lose revenue when using these APIs to lower or mute the volume of the Google Mobile Ads SDK. Two issues we have commonly seen:

  1. Apps are using their own custom volume controls not sending the app’s accurate volume to the Google Mobile Ads SDK, but always sending zero
  2. App are just muting the SDK

Some apps have close to a 100% mute rate which doesn’t sound correct (pun intended). Setting application volume to zero or muting the application reduces video ad eligibility, which as a result may reduce your app’s ad revenue.

Volume control APIs

The Google Mobile Ads SDK offers two volume control APIs: setting the volume and toggling mute. These APIs are applicable to App Open, Banner, Interstitial, Rewarded and Rewarded Interstitial ad formats. For Native ads, use GADVideoOptions.

Setting application volume on each platform

iOS GADMobileAds.sharedInstance().applicationVolume = 1.0
Android MobileAds.setAppVolume(1.0f)
Unity MobileAds.SetApplicationVolume(1.0f)

Use applicationVolume to set your custom volume relative to the device volume. The range can be from 0.0 (silent) to 1.0 (current device volume). For example, if the device volume level was at half level and the user set your app’s custom volume to max level, set the applicationVolume to 1.0 and the user will receive an ad with the volume at half level.

Setting application mute on each platform

iOS GADMobileAds.sharedInstance().applicationMuted = true
Android MobileAds.setAppMuted(true)
Unity MobileAds.SetApplicationMuted(true)

Use applicationMuted if your custom volume controls include a mute button. Only toggle applicationMuted if the user selects your custom mute button. For example, if the user adjusts your custom volume to 0 you do not need to call applicationMuted; just call applicationVolume = 0.0.

Setting mute for native ads on each platform

iOS 
let videoOptions = GADVideoOptions()
videoOptions.startMuted = true
adLoader = GADAdLoader(
    adUnitID: "AD_UNIT_ID",
    rootViewController: self,
    adTypes: [ ... ad type constants ... ],
    options: [videoOptions])
Android 
val videoOptions = VideoOptions.Builder()
        .setStartMuted(false)
        .build()
val adOptions = NativeAdOptions.Builder()
        .setVideoOptions(videoOptions)
        .build()
val adLoader = AdLoader.Builder(this, "AD_UNIT_ID")
        .forNativeAd( ... )
        .withNativeAdOptions(adOptions)
        .build()
Unity N/A - Native video ads are not supported in Unity.

Use startMuted if your custom volume controls include a mute button. Only toggle startMuted if the user selects your custom mute button.

Best Practices

To use our APIs as intended:

  1. applicationVolume should be called only when your custom volume control settings are set to reflect the new volume
  2. applicationMuted or startMuted should only be toggled to true if the user has muted your custom volume

As a rule of thumb, if your app does not have custom volume controls then you should not use these APIs.

What should you do?

To verify that your mobile applications are using these APIs correctly, we recommend that you enable test ads and force load a video test ad in your application. If your app has custom volume controls, the ad’s volume should be at the same level as the custom volume. Otherwise, the ad’s volume should match the device volume.

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

 - Justin Malandruccolo, Mobile Ads Developer Relations

February 2023 update to Display & Video 360 API

Today we’re announcing the February 2023 update to Display & Video 360 API. This update 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. We have also added a new guide page on retrieving YouTube & Partners line items using the Display & Video 360 API.

If you have questions regarding the breaking changes, 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