Category Archives: Ads Developer Blog

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

Changing statuses of app and app engagement ads that do not serve

On April 17, 2020, app ads and app engagement ads that do not serve will have their statuses changed automatically from ENABLED to DISABLED. For each ad group in App campaigns, only the first created ad is ever eligible to serve, so we’re disabling other ads in the same ad group to prevent confusion. This means that you may see some changes in the number of report rows if your queries have a condition that includes ad_group_ad.status for the Google Ads API or AdGroupAdStatus for the AdWords API.

What do you need to do?
If you’re not interested in the disabled ads, you don’t need to take any action. Only beware that the number of report rows returned by your query may change. For example, if your queries have a condition to get only enabled ads, you may see fewer report rows.

If you still wish to see the performance data of the disabled ads, make sure your report queries also include the disabled ads. Note that as they don’t serve anymore, these ads won’t accrue any more performance stats beyond the above-mentioned date.

In case you need more information on reporting, follow the below links:
For the Google Ads API, For the AdWords API, As always, if you have any questions, feel free to reach out to us on the AdWords API and Google Ads API forum.
 - Thanet Knack Praneenararat, Google Ads API Team

Upcoming change to the Google Ad Manager API

On Wednesday April 1st, 2020 existing metrics in the Ad Manager API's ReportService will start returning net revenue instead of gross revenue for Programmatic Guaranteed and Preferred Deals. If your application does not process Programmatic Guaranteed and Preferred Deals revenue data, no action is required.

This change will impact all API versions and reports run in the Ad Manager UI. For more information, see the Ad Manager release notes for March 9th.

To help this transition, new metrics have been added in v202002 to allow you to report on gross revenue in order to facilitate historical comparisons. These metrics are temporary and will be removed in future API versions.


Why are we making this change?

This change brings Programmatic Guaranteed and Preferred Deals into alignment with all other transaction types.

How can I tell if I am impacted?

If you use any of the below metrics and your application processes Programmatic Guaranteed and Preferred Deals values as gross revenue, you are impacted by this change:
  • AD_SERVER_ALL_REVENUE
  • AD_SERVER_CPD_REVENUE
  • AD_SERVER_CPM_AND_CPC_REVENUE
  • TOTAL_LINE_ITEM_LEVEL_ALL_REVENUE
  • TOTAL_LINE_ITEM_LEVEL_CPM_AND_CPC_REVENUE
  • TOTAL_LINE_ITEM_LEVEL_WITHOUT_CPD_AVERAGE_ECPM

What changes do I need to make?

You must update your application to process Programmatic Guaranteed and Preferred Deals values as net revenue before April 1st, 2020. If you need access to gross revenue values after April 1st, 2020, you can use temporary gross revenue metrics added in v202002. These metrics will be available until the end of February 2021.

Net revenue values starting 2020-04-01 Gross revenue values until 2021-03-01
AD_SERVER_ALL_REVENUE AD_SERVER_ALL_REVENUE_GROSS
AD_SERVER_CPM_AND_CPC_REVENUE AD_SERVER_CPM_AND_CPC_REVENUE_GROSS
AD_SERVER_CPD_REVENUE Not available
TOTAL_LINE_ITEM_LEVEL_ALL_REVENUE Not available
TOTAL_LINE_ITEM_LEVEL_CPM_AND_CPC_REVENUE Not available
TOTAL_LINE_ITEM_LEVEL_WITHOUT_CPD_AVERAGE_ECPM Not available



If you have questions about this change or are unsure if it impacts you, reach out to us on the Ad Manager API forums. We'll be happy to check if you're impacted and work with you to update your applications.
 - Chris Seeley, Ad Manager API Team

Deprecation of DBM API v1 and SDF Download Service

Today we’re announcing the deprecation of the Doubleclick Bid Manager (DBM) API v1 and the DBM API v1.1 Structured Data File (SDF) Download service. These services will no longer be supported and will be fully sunset on June 15, 2020. Refer to the table below to verify if methods you’re using will be available in v1.1 after June 15, 2020:


Service Methods Available in v1.1 after June 15, 2020?
Reporting queries.createquery
queries.deletequery
queries.getquery
queries.listqueries
queries.runquery
reports.listreports		 Yes
Line Item Settings lineitems.downloadlineitems
lineitems.uploadlineitems		 Yes
SDF Download sdf.download No. Use the new Display & Video 360 API instead.



If you are using the DBM API v1 Line Item Settings service or Reporting service, you must migrate to v1.1 by the sunset date to avoid an interruption of service. Consult the API release notes for the finer details of the changes between v1 and v1.1. Important things to know are:
  • Queries created and accessed through the Reporting service require more specific filters in the params.groupBy field in v1.1. You might have to add more values to the params.groupBy field in order to create the same report structure they generated in v1.
  • Responses from listqueries and listreports calls are paginated in v1.1. Users have to update their implementation to traverse multiple pages if they wish to consume more than the first 100 items returned.
  • The Line Item Settings service had no changes between v1 and v1.1. Users only have to update the version they are using.
The SDF Download service is deprecated in DBM API v1 and v1.1. Users should immediately migrate to the new Display & Video 360 API, which was released earlier this week. The Display & Video 360 API offers a new asynchronous SDF Download Service featuring new filter options and a new download format compared to its DBM API counterpart.

Guides are available to help you set up the new Display & Video 360 API, as well as use it to get started downloading SDFs.

- Trevor Mulchay, Display & Video 360 API Team

Preventing App engagement campaigns for prohibited apps

Starting on April 1, 2020, the Google Ads API will prevent the creation of new App engagement campaigns for apps in prohibited categories.

The Google Ads API currently allows you to create App engagement campaigns for any category of app. But if an app from a prohibited category is chosen, those campaigns are prohibited from serving ads. This can lead to confusion among advertisers.

Enabling the API to validate that such campaigns are indeed eligible to serve before their creation will allow developers to take corrective action early on and also ensure client accounts are able to serve their intended ads.

Change details
App engagement campaigns are identified in the API as campaign objects with the following properties. Once this change goes into effect, API calls to create campaigns of the above type will fail if the campaign’s app_campaign_setting.app_id references an app in a prohibited category.

Versions v3 and later of the API will throw a SENSITIVE_CATEGORY_APP error. Earlier versions of the API will throw a more generic UNKNOWN error, since the error code is not published in those versions. These errors may surface from the following services and operations.

API Version Service Operation Error
v3+ CampaignService create CampaignError.SENSITIVE_CATEGORY_APP
v1, v2 CampaignService create CampaignError.UNKNOWN

For instances of error code CampaignError.UNKNOWN, the GoogleAdsError’s details.unpublished_error_code field will indicate, “CampaignError.SENSITIVE_CATEGORY_APP”.

Implementation and support
If you create App engagement campaigns with the Google Ads API, please add error handling for apps in prohibited categories. In order to leverage the new SENSITIVE_CATEGORY_APP error, please upgrade to v3 of the Google Ads API first where possible.

If you’re unable to upgrade versions before the change goes into effect, please check for error code CampaignError.UNKNOWN upon campaign creation, and verify that the error’s details.unpublished_error_code string matches the error name documented in the previous section, to indicate a prohibited category may be in use.

For more details on implementing support for App campaigns, see our App Campaigns developer guide for more information. And as always, if you have any questions about this change, don’t hesitate to reach out to us on the Google Ads API developer forum.
Adam Ohren, Google Ads API Team

Introducing Display & Video 360 API v1

Today we’re releasing the Display & Video 360 API v1. It offers a new, improved way to interact with your Display & Video 360 resources programmatically.

This initial API release includes new asynchronous Structured Data File (SDF) download functionality. This allows for the generation and downloading of large SDFs without worrying about individual API requests timing out. This is a change compared to the existing DoubleClick Bid Manager (DBM) API SDF Download service. Along with this change, other major changes include:
  • New default version logic that utilizes the default version of the partner or advertiser specified by the user.
  • New filter capabilities, including the ability to specify the exact resources to include in the generated files.
  • New response format that returns the generated SDFs as a .zip file to download, rather than JSON.

The Display Video 360 API SDF Download service will be replacing the DBM API SDF Download service. The deprecation of that service will be announced soon, and an immediate migration to the new API is advised. You can get started setting up the Display & Video 360 API here, and downloading Structured Data Files here.

More functionality will be coming to the Display & Video 360 API in the coming months, including line item management and targeting. Keep an eye out for future announcements!


- Trevor Mulchay, Display & Video 360 API Team

Introducing Display & Video 360 API v1

Today we’re releasing the Display & Video 360 API v1. It offers a new, improved way to interact with your Display & Video 360 resources programmatically.

This initial API release includes new asynchronous Structured Data File (SDF) download functionality. This allows for the generation and downloading of large SDFs without worrying about individual API requests timing out. This is a change compared to the existing DoubleClick Bid Manager (DBM) API SDF Download service. Along with this change, other major changes include:
  • New default version logic that utilizes the default version of the partner or advertiser specified by the user.
  • New filter capabilities, including the ability to specify the exact resources to include in the generated files.
  • New response format that returns the generated SDFs as a .zip file to download, rather than JSON.

The Display Video 360 API SDF Download service will be replacing the DBM API SDF Download service. The deprecation of that service will be announced soon, and an immediate migration to the new API is advised. You can get started setting up the Display & Video 360 API here, and downloading Structured Data Files here.

More functionality will be coming to the Display & Video 360 API in the coming months, including line item management and targeting. Keep an eye out for future announcements!


- Trevor Mulchay, Display & Video 360 API Team

Announcing v3_0 of the Google Ads API beta

Today we’re announcing the v3_0 release of the Google Ads API beta. To use the v3_0 features via the new endpoint, please update your client libraries. If you are upgrading from v1 or v2, some of your code may require changes when you switch to the new v3 endpoint. Please see the migration guide for more information on breaking changes.

Here are the highlights: Where can I learn more?
The following resources can help you get going with the Google Ads API: The updated client libraries and code examples will be published next week. If you have any questions or need additional help, please contact us via the forum.
Nadine Wang, on behalf of the Google Ads API Team

Responsive Display Ads in Google Ads Scripts

Today we are adding support for new responsive display ads in Google Ads scripts. Starting last year, you could no longer create legacy responsive display ads, but you could still fetch your existing ads.

These new responsive display ads have added support for multiple text, image, and video assets in the same ad. The ResponsiveDisplayAd object gained new methods to support the new associated fields, and you can begin adding new responsive display ads in your scripts.

The new and legacy responsive display ads are both represented via the same ResponsiveDisplayAd object. Make sure to read the full object documentation to check which methods are relevant for legacy ads or new ads. We also have a short guide demonstrating some of the key changes.

If you have any questions or concerns, please don't hesitate to contact us via the forum.
- Mike Cloonan, Google Ads scripts Team

Announcing v202002 of the Google Ad Manager API



We're happy to announce that v202002 of the Google Ad Manager API is available starting today. This version includes several new features around video ads.

For “Ad Exchange historical” reports, there are several new video Columns available beginning with “AD_EXCHANGE_VIDEO_”. Here are a few of the new metrics:


  • AD_EXCHANGE_VIDEO_START – the number of impressions where the video was played for video ads by Ad Exchange properties
  • AD_EXCHANGE_VIDEO_SKIPS – The number of times a skippable video is skipped
  • AD_EXCHANGE_VIDEO_UNMUTE – The number of times a user unmutes the video ad

You can now associate a video Creative with an ad registry, such as Ad-ID or Clearcast. Video metadata is also getting enhanced with the addition of Content.contentBundleIds to show which ContentBundles a Content object belongs to and Content.cmsMetadataValueIds to show which CmsMetadataValues are associated with a Content object.

The release notes contain the full list of API changes for v202002 and all other active API versions.

Feel free to reach out to us on the Ad Manager API forum with any API-related questions.
 - , Ad Manager API Team

Gmail on standard Shopping campaigns

Beginning the week of Mar 4th, 2020, Shopping ads (both Product Shopping ads and Showcase Shopping ads) in your standard Shopping campaigns that target the Google Display Network will be eligible to appear on Gmail in addition to YouTube and Google Discover. This means that reporting information will include Gmail in addition to YouTube and Google Discover for the following configurations: To allow your advertisers to opt-in/opt-out of Gmail, YouTube and Google Discover for standard Shopping campaigns, you will need to enable or disable the following setting:
  • Google Ads API - Modify the NetworkSettings of the standard Shopping campaign and set target_content_network to true (opt-in) or false (opt-out).
  • AdWords API - Modify the NetworkSetting of the standard Shopping campaign and set targetContentNetwork to true or false.
If you have any questions or need help, please contact us via the forum.
- Ian Ballantyne, on behalf of the Google Ads API Team