Category Archives: Ads Developer Blog

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

The Query Builder Blog Series: Part 1 – Setting the Stage

An important part of our role in Developer Relations is gathering your feedback, as developers using our APIs, so that we can improve products and create tools that will make for a better developer experience. This is particularly important now because the Google Ads API is now out of Beta. We have received several important pieces of feedback as it relates to the Google Ads Query Language (GAQL) and constructing GAQL queries. Specifically, we’ve learned that

  • GAQL is a powerful and flexible mechanism for retrieving data from the Google Ads API. In order to get the most out of it and construct queries efficiently, it is important to understand the details and nuances of this query language.
  • The previous version of the Interactive Google Ads Query Builder tool was useful for constructing GAQL query strings. However, there were opportunities to make the query building process faster while exposing some of the logic behind the tool to better understand how GAQL query string validation works.
As a result, we have released a new version of the Interactive Google Ads Query Builder tool that has several benefits, which you can view in the release blog post.

In developing this new tool, we approached the Google Ads API from a user's perspective to better understand developer use cases. Throughout the process, we documented our experience to share how we approach using the Google Ads API. This is the first in a series of blog posts following that journey. The Query Builder Blog Series will include the following topics.

  • Designing a resource schema: designing a detailed JSON resource schema that will serve as the canonical data set for the Interactive Query Builder Angular application.
  • Creating a resource schema: how we can use the GoogleAdsFieldService to create an enhanced resource schema that includes incompatible fields to make building this application easier.
  • Creating a resource service: how to create a resource service that determines which fields are displayed to users in various parts of the application.
  • Determining Field Selectability: how to create a selection service that determines whether a field is selectable or not in a given clause of a Google Ads Query Language (GAQL) query string.
  • Field Selection & Query Validation: how to update the selection service to select fields and validate the GAQL string.
  • Summary: a summary of key lessons learned from this process.

We hope you enjoy and learn from this blog series. Stay tuned for more interesting content.

If you have any questions or need additional help, contact us via the forum or at [email protected]
- Devin Chasanoff, on behalf of the Google Ads API Team

March 2021 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.
- Trevor Mulchay, Display & Video 360 API Team

Announcing the New and Improved Interactive Query Builder

Today, we are releasing a new and improved version of the Google Ads Query Language (GAQL) interactive query builder. The new version is resource-centric and helps you build a GAQL query based on the resource in the FROM clause. There are two ways to to access the query builder:


Navigate to the developer documentation Reports tab. Expand the Query Builder on the left side of the page. Choose your resource.

Click the Help me build a query button for any resource in the reporting reference documentation.







Highlights

As users type, the new search bar filters fields dynamically.





We also designed this tool with a goal of educating developers about the Google Ads Query Language as they use it. The query builder dynamically surfaces hints (such as field compatibility)





and prompts (for example, to notify users of requirements to add fields to multiple clauses of a query).





The new query builder features “pretty print” mode to display queries in an easy to read format, as well as “interactive” mode, which provides the ability to remove and reorder fields directly within the query box.





As you get started with the new query builder, please feel free to share feedback by clicking the Send feedback button on the top right of any page.




If you have any questions or need additional help, contact us via the forum or at [email protected]
- Devin Chasanoff, on behalf of the Google Ads API Team

Upcoming Change to the Enforcement of Temporary IDs with Product Partitions and Listing Groups

Beginning in May, 2021 we will enforce a requirement that temporary IDs be unique for all objects in newly created listing groups (used for Hotel Ads and Shopping Ads in the Google Ads API) and product partitions (used for Shopping Ads in the AdWords API). This change will affect all versions of both the AdWords and Google Ads APIs.

Temporary IDs must be unique across an entire mutate request–even if the objects are in separate listing group trees or product partition trees.

In order to avoid unnecessary breakages, API users should update their applications to ensure that all temporary IDs used in individual requests are unique.

Here is a snapshot of the expected behavior for requests that continue using non-unique temporary IDs:

API and mutate method Current Behavior New Behavior
BatchJobService with the Google Ads API Customers will receive a non-specific error, meaning it may not specify that the issue is related to temporary IDs. Customers will start receiving failed operations that contain the error: MutateError.MUTATE_ERROR_TEMP_ID_ALREADY_EXISTS
BatchJobService with the AdWords API Customers will receive a non-specific error, meaning it may not specify that the issue is related to temporary IDs. Customers will start receiving failed operations that contain the error: NewEntityCreationError.DUPLICATE_TEMP_IDS
AdGroupCriterionService or GoogleAdsService.Mutate with the Google Ads API Customers will not receive an error. Customers will start receiving the error: MutateError.MUTATE_ERROR_TEMP_ID_ALREADY_EXISTS
AdGroupCriterionService with the AdWords API Customers will not receive an error. Customers will start receiving the error: NewEntityCreationError.DUPLICATE_TEMP_IDS


If you have any questions or need additional help, contact us via the forum or at [email protected]
- Ben Karl, on behalf of the Google Ads API Team

AdFormat in Search Query Performance Report will start returning UNKNOWN starting 2021-05-12

On 2021-05-12 we will deprecate the  AdFormat column in the Search Query Performance Report for AdWords API and Google Ads scripts. From then onwards, the report will return UNKNOWN for this field. This does not affect the Google Ads API.

The AdFormat column provides the type of creative that was triggered such as text, image, or video. If you still require this information, you can instead select AdGroupId and CreativeId from the same report, then call AdGroupAdService.get() to retrieve the Ad.type field.

This completes the migration that was started in January 2020 to remove AdFormat from all reports.

If you have any questions about this or anything else related to the AdWords API, please reach out to our support team on the forum.

Nick Birnie, Google Ads API Team

Securing Google Publisher Tags with Content Security Policy

The Google Publisher Tag (GPT) now supports integrating with a Content-Security-Policy (CSP). Using a CSP, you can precisely control which external sources are allowed to load on your site, on a page-by-page basis. In this way, CSPs help to detect and defend against common web vulnerabilities such as cross site scripting (XSS) attacks.

Although CSPs can be implemented in a number of ways, GPT only supports the strict CSP method, using nonces. For detailed instructions on setting this up, see our guide on Integrating with a Content Security Policy.

A note on existing CSPs

While GPT did not previously support CSPs, we're aware that some publishers worked around this by using CSPs based on an allowlist of domains. As previously mentioned, however, only nonce-based strict CSP implementations are supported. This is due to the fact that the set of domains GPT accesses is subject to change over time.

If you've been using GPT with an allowlist-based CSP, we strongly recommend that you supplement or replace it with a nonce-based strict CSP policy. This will reduce the risk that a future change to GPT may break ad serving on your page.
 - Khoi Doan, Google Publisher Tags Team

Sunset grace period for existing v2 users of the Content API for Shopping

As we’ve previously announced, we will stop supporting legacy v2.0 of the Content API for Shopping in favor of v2.1, which has been available since March 2019.

As this has been a difficult year for all of us, in order to provide you ample time to migrate to v2.1 we will be extending the sunset date for existing merchant accounts actively using v2.0 to September 30, 2021. However, we will not allow new merchant accounts onto v2.0 after April 30, 2021. The account restrictions will not impact users accessing new sub-accounts via an existing multi-client account (MCA), provided that MCA has been actively making v2.0 requests.

We will publish another blog post in the coming weeks with a process for requesting an exemption to add new accounts to your v2.0 integration after April 30, 2021.

Throughout this grace period, we will continue to provide support for your efforts to migrate to v2.1. We strongly encourage you to migrate to v2.1 as soon as possible.

What do I need to know?
In March 2019, we released version 2.1 of the Content API for Shopping with major improvements to the API management experience for Merchant Center programs, including: See the complete list of changes in the release notes and the migration guide to help with the transition.

If you have any questions or issues during migration, contact your Google representative for Merchant Center programs, or ask questions in the Content API for Shopping forum.

What do I need to do?
Migrate to v2.1 of the Content API as soon as possible.
Benji Rothman, Content API for Shopping Team

New validation for line items in Display & Video 360 API

Beginning in May 2021, the Display & Video 360 API will start enforcing new validation when creating or updating line item resources.

This validation will require all Floodlight activity configurations in a line item to use the same lookback windows. All TrackingFloodlightActivityConfig objects assigned to conversionCounting.floodlightActivityConfigs in a line item must have the same postClickLookbackWindowDays value and the same postViewLookbackWindowDays value. The values of the two lookback window types do not have to be the same.

This validation will be enforced when creating new line items or updating the conversionCounting.floodlightActivityConfigs field of an existing line item. 
Requests that do not comply will return one of two errors, depending on the invalid field: “Floodlight click windows must be the same” or “Floodlight view windows must be the same.”

Once this validation is in effect, you will still be able to retrieve and update unrelated fields of line items that do not comply with this rule.

If you run into issues or have questions regarding this new validation, please contact us using our support contact form.
- Trevor Mulchay, Display & Video 360 API Team

February 2021 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.
- Trevor Mulchay, Display & Video 360 API Team

Sunset date for deprecated DBM API services postponed to April 15, 2021

The sunset of deprecated services in the DoubleClick Bid Manager (DBM) API, originally scheduled for February 26, 2021, has been postponed to April 15, 2021. The deprecated services scheduled for sunset include the entirety of DBM API v1, the DBM API v1.1 SDF Download service, and the DBM API v1.1 Line Item service.

Prior blog posts regarding this sunset give instructions on how to migrate from these deprecated services to either the DBM API v1.1 Reporting service or the Display & Video 360 (DV360) API. Consult these previous announcements for more information.

If you encounter issues with your migration or want to report a separate issue, please contact us using our support contact form.


- Trevor Mulchay, Display & Video 360 API Team