Google Ads Developer Blog: August 2018

Announcing v0_3 of the Google Ads API

Wednesday, August 29, 2018

Today we’re announcing the beta release of Google Ads API v0_3. With minor versions like this one, you’ll continue to point to v0 as your endpoint, but you will need to update your client libraries to use the new features. Here are the highlights:

Campaigns. We’re expanding beyond Search campaigns with keyword targeting to include:

Display campaigns
Campaign groups
Ad schedules
Campaign shared sets
Shared sets for keyword criteria
Campaign bid modifiers for interaction types.
Ad group bid modifiers.

Queries. GoogleAdsService.search provides the ability to filter by resource name.
Creatives. For ad disapproval error handling, PolicyFindingDetails replaces PolicyViolationDetails for expanded text ads.
Hotel Ads. Hotel ads, first introduced in v0_1, is a whitelisted feature with an ad type that is created automatically by the system based on your provided hotel listings and prices. To learn more about the hotel ads migration and what’s next, check out our recent webinar:

Recommendations. Recommendations provide customized suggestions to help increase your campaigns' performance. In the v0_3 release, we’ve added new recommendation types to the API and a new “dismissed” field.

Five new recommendation types are available in the API:

Bidding with Maximize conversions
Bidding with Enhanced CPC
Bidding with Maximize clicks
Expand your reach with Google Search partners
Use optimized ad rotation

Added “Dismissed” field to search, retrieve, or apply dismissed recommendations.

Shopping. Smart Shopping Campaigns combine standard Shopping and Display remarketing campaigns, and use automated bidding and ad placement to promote your products and business across networks.
This release of Google Ads API supports the creation of Smart Shopping Campaigns, which can be used with Maximize Conversion Value bidding strategies. Product offers can be subdivided into groups using the ListingGroupInfo criterion, which currently supports the following dimension types: Product Condition, Product Type, Listing Brand, Custom Attribute (L0-4).
Access to Smart Shopping campaigns is currently only available to whitelisted developers.
Python client library. We’ve now also released a Python client library. In the v0 and v0_2 releases, we released Java, C#, Ruby, and PHP client libraries.

To get started with the API, our team has put together these resources:

Google Ads API Beta Sign-up
Google Ads API Reference
Google Ads API Guides
Google Ads API Client Libraries

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

Nadine Sundquist, on behalf of the Google Ads API Team

More changes to issue reporting in the Content API for Shopping

Thursday, August 23, 2018

Update: The date for this change has moved to February 25, 2019.
What's changed?
There are three major changes being announced in this post:

Accountstatuses now returns aggregated product statistics.
Accountstatuses now includes the new format for product-level issues.
itemLevelIssues objects now contain human-readable descriptions.

Aggregated product statistics in Accountstatuses
The number of products in a given account can now be retrieved directly from Accountstatuses. Like the Merchant Center, you can retrieve the following aggregated statistics: active products, expiring products, disapproved products, and pending products. These statistics are given separately for each combination of destination, channel, and target country. For example:

"products": [{
  "country": "US",
  "destination": "Shopping",
  "channel": "online",
  "statistics": {
    "active": "1542",
    "expiring": "14",
    "disapproved": "152",
    "pending": "743"
  },
  ...
}]

Here, there are 1542 active products that target the USA that can be used in online Shopping campaigns, 14 active but expiring products, 152 disapproved products, and 743 pending products.

Product-level issues in Accountstatuses
In addition to the new product statistics, the "products" field also contains an itemLevelIssues field similar to the itemLevelIssues field added to Productstatuses earlier this year. Using the contents of this field, you can now see explicitly whether a given issue is impacting the servability of a product and whether the issue needs your attention or just further processing on Google's part.

Human-readable descriptions in itemLevelIssues
In both Productstatuses and Accountstatuses, the objects in the itemLevelIssues field now have some additional fields, which contain English descriptions and helpful links for issues that are suitable for surfacing to clients. The following fields have been added:

description contains a short English description of the issue.
detail contains a detailed English description of the issue.
documentation contains a URL for a web page that can help resolve the issue.

Here is an example itemLevelIssues object that includes these fields:

{
  "attributeName": "image link",
  "code": "image_link_pending_crawl",
  "description": "Image not retrieved (crawl pending)",
  "destination": "Shopping",
  "detail": "Wait for the product image to be crawled (up to 3 days)",
  "documentation": "https://support.google.com/merchants/answer/160640",
  "resolution": "pending_processing",
  "servability": "disapproved"
}

What do you need to do?
Now that the human-readable information is available for itemLevelIssues in both systems, we now consider the old dataQualityIssues fields deprecated. We will no longer include them in Productstatus or Accountstatus resources on Dec 1, 2018, therefore you should migrate to the new itemLevelIssues fields as soon as possible.

If you have any questions or feedback about this change, or any other questions about the Content API for Shopping, please let us know on the forum.
- Stevie Strickland, Content API for Shopping Team

Upcoming changes to DBM API reporting

Wednesday, August 22, 2018

The week of September 17, 2018, a number of DoubleClick Bid Manager API reporting dimensions and metrics will be renamed. This renaming will modify both API names and column header names in generated report files. These changes are being made to more closely align API field names with their UI counterparts after the recent launch of the Google Display & Video 360 brand. The changes are as follows:

Dimensions

Old API name	Old column header	New API name	New column header
FILTER_ACTIVITY_ID	Conversion Pixel DCM ID	FILTER_FLOODLIGHT_ACTIVITY_ID	Floodlight Activity ID
FILTER_FLOODLIGHT_PIXEL_ID	Conversion Pixel ID	FILTER_DV360_ACTIVITY_ID	DV360 Activity ID
FILTER_MOBILE_DEVICE_MAKE	Mobile Make	FILTER_DEVICE_MAKE	Device Make
FILTER_MOBILE_DEVICE_MAKE_MODEL	Mobile Make and Model	FILTER_DEVICE_MODEL	Device Model
FILTER_MOBILE_DEVICE_TYPE	Device Type	FILTER_DEVICE_TYPE	Device Type

Metrics

Old API name	Old column header	New API name	New column header
METRIC_POST_CLICK_DFA_REVENUE	DCM Post-Click Revenue	METRIC_CM_POST_CLICK_REVENUE	CM Post-Click Revenue
METRIC_POST_VIEW_DFA_REVENUE	DCM Post-View Revenue	METRIC_CM_POST_VIEW_REVENUE	CM Post-View Revenue
METRIC_PIXEL_LOADS	Pixel Load Count	METRIC_FLOODLIGHT_IMPRESSIONS	Floodlight Impressions

To allow users time to prepare for these changes, the new API names listed above will be made available the week of September 3, 2018. Both old and new API names will be supported until October 1, 2018, at which point the old API names will be disabled. Users are advised to use this transitional period to update workflows impacted by this change, to avoid an interruption in service.

If you have questions regarding these changes, please reach out to your Display & Video 360 account team.

- Jonathon Imperiosi, DBM API Team

Announcing v201808 of the Google Ad Manager API

Tuesday, August 21, 2018

We're happy to announce that v201808 of the Google Ad Manager API is available starting today. This version brings several new forecasting features, including forecast breakdowns by date and targeting. You can also forecast for AMP-only traffic and Proposal Line Items.

For video users, note that the new requestPlatformTargeting field is required when creating video line items.

For a full list of API changes in v201808, see the release notes.

If you're using one of our client libraries, you'll notice they've been updated to reflect our new name, so allow extra time for upgrading. A migration guide for each client library is available on GitHub:

Java
.NET
PHP
Python
Ruby

For questions about this or any other API changes, reach out to us on the Ad Manager API forums.

- Chris Seeley, DFP API Team

Upcoming changes to mobile placement targets and exclusions

Tuesday, August 21, 2018

What's changing
Starting September 18, 2018, AdWords API requests that attempt to target or exclude a Placement criterion where the url is exactly adsenseformobileapps.com will fail and result in a CriterionError with reason INVALID_PLACEMENT_URL. You can read more about this change in the Google Ads help center.

What you should do
Modify your application so that it does not add the above Placement criterion via the AdWords API, and review and modify your mobile targeting to achieve your campaign goals. You will no longer be able to exclude all mobile apps from targeting using this Placement criterion, but you can refine your mobile app targeting and exclusions using any of the following criteria:

For more details, check out the criteria usage grid that indicates which criterion types can be targeted and excluded at the campaign or ad group level. If you have any questions or need help, please contact us via the forum.

- Josh Radcliff, AdWords API Team

Deprecation of assisted-conversions reporting fields

Monday, August 20, 2018

Starting September 10, 2018, AdWords API and AdWords scripts reports will start returning no values (two dashes) for the following assisted-conversions fields for all API versions:

Why are we deprecating these reporting fields?
Often, the last click before a conversion gets all the credit. But along the way, other clicks and impressions might have guided your customers toward that conversion. Previously, assisted-conversions reporting fields were created to give conversions to the clicks and impressions that assisted in such a scenario. However, it’s still not easy to compare those conversion values between campaigns, ad groups, and keywords, as conversion metrics are double-counted and not normalized.

With the advent of attribution models that allow you to assign fractional credits to multiple clicks that contribute to conversions, you can now distribute credits among many clicks in a way that they can be summed up to 1.00. Conversion reporting fields, such as Conversions, AllConversions, and CrossDeviceConversions, are now returned based on the fractional-credit model, so please migrate to those reporting fields instead.

As always, if you have any questions or concerns, please post on our forum.

- Thanet Praneenararat, Google Ads API Team

Announcing v3.2 of the DCM/DFA Reporting and Trafficking API

Tuesday, August 14, 2018

Today we're releasing v3.2 of the DCM/DFA Reporting and Trafficking API. Highlights of this release include:

Support for responsive creatives and placements
Additional signal fields for offline conversions

Details of these and all other changes are covered in our release notes.

Deprecation and sunset reminder
In accordance with our deprecation schedule, this release marks the beginning of the deprecation period for v3.1, which will sunset on February 28, 2019. After this date, any requests made against v3.1 will begin returning errors.

As a final reminder, API version 2.8 will be sunset on August 31, 2018. To avoid an interruption in service, all users are required to migrate to a newer version before the sunset date.

Learn More
As with every new version of the DCM/DFA Reporting and Trafficking API, we encourage you to carefully review all changes in the release notes. For those of you looking to get going right away, updated client libraries are now available. If you're just starting out, the Get Started guide is a great reference to help you get up and running quickly.

Give it a try and let us know if you have any questions!

- Jonathon Imperiosi, DCM API Team

Announcing the Mediation Test Suite Beta

Thursday, August 9, 2018

Today we're announcing the release of Mediation Test Suite Beta. Mediation Test Suite is a lightweight SDK that enables Google AdMob publishers to easily test mediation ad network integrations without having to make changes in the AdMob UI, saving you and your developers time. It is available on Android, iOS, and Unity.

Mediation Test Suite allows you to:

View a full list of mediation ad source configurations for your app

Automatically check your project for missing SDKs, adapters, and manifest changes required by partner ad sources

Load a banner, interstitial, rewarded, or native ad for any ad source using a certified Google Mobile Ads SDK implementation

Batch test multiple ad sources for the same ad unit

Test both open source mediation adapters and custom event adapters

Integrating Mediation Test Suite is easy -- once you have the SDK imported, it can be launched with just a single line of code. All you need is your AdMob app ID. On Android, the launch code looks like this: import com.google.android.ads.mediationtestsuite.MediationTestSuite; ... String appId = "YOUR-ADMOB-APP-ID"; MediationTestSuite.launch(MainActivity.this, appId); On iOS, all that's required is importing the correct header and launching the Test Suite: #import "GoogleMobileAdsMediationTestSuite.h" ... NSString* appId = @"YOUR-ADMOB-APP-ID" [GoogleMobileAdsMediationTestSuite presentWithAppID:appId onViewController:self delegate:nil]; Unity is just as simple, but please note that you need to use the appropriate app ID for your platform: using GoogleMobileAdsMediationTestSuite.Api; ... #if UNITY_ANDROID string appId = "YOUR-ANDROID-ADMOB-APP-ID"; #elif UNITY_IPHONE string appId = "YOUR-iOS-ADMOB-APP-ID"; #else string appId = ""; #endif MediationTestSuite.Show(appId); Including Mediation Test Suite in production builds is optional You are not required to keep the Mediation Test Suite library in the production release of your app; however, you may choose to leave it in and hide it behind a debug gesture. Doing so enables you to launch Mediation Test Suite within your production build. You can find more information about how to use Mediation Test Suite in the developer guide (Android | iOS | Unity). Remember that Mediation Test Suite is a beta product, so if you have any questions or feedback, please contact us on the developer forum.

- Jon Weisbaum, Mobile Ads Developer Relations

Announcing Google Ads scripts 2018 workshops

Tuesday, August 7, 2018

We are pleased to announce the locations and dates for the 2018 Google Ads (formerly AdWords) scripts workshops. These events will be taking place across the United States, Europe, and Asia in September and October. Please join us for some informative talks and interactive codelabs.

We will be offering multiple sessions for two levels: beginner and advanced users. The beginner sessions are designed for new users of Google Ads scripts and business managers who are considering automation for their existing manual Google Ads processes. The advanced sessions will cater to experienced Google Ads scripts users who want to explore advanced scenarios and keep up with the latest developments.

Please visit the event site for full details and to register for an event near you. We will be hosting the following sessions:

New York City (Advanced) on September 4, 2018
San Francisco (Advanced) on September 7, 2018
Hamburg (Beginner) on September 27, 2018
Hamburg (Advanced) on September 28, 2018
Tokyo (Beginner) on September 28, 2018
London (Beginner) on October 3, 2018
London (Advanced) on October 4, 2018
Singapore (Beginner) on October 15, 2018

We hope to see you there!

- Mike Cloonan, Google Ads Scripts Team

Multi-factor authentication policy for Google Ads accounts

Monday, August 6, 2018

Today, we are rolling out a feature that allows the administrative users of Google Ads accounts to set a required multi-factor authentication policy, including 2-Step Verification. When this new authentication policy is enabled on a particular Google Ads account, all users who want to access that account must have their Google accounts enrolled in 2-Step Verification.

Note: The Google account users can alternately fulfill this requirement by enrolling their accounts in Advanced Protection.

What will happen to your API access?
If 2-Step Verification is required for a particular Google Ads account, then 2-Step Verification also needs to be set up for the Google account used to generate the OAuth2 refresh token accessing the Google Ads account. Follow this link to opt in to 2-Step Verification. Failing to do so will result in the AuthorizationError.TWO_STEP_VERIFICATION_NOT_ENROLLED error when you try to access the Google Ads account.

Access to the Google Ads account will be restored once you opt in to the 2-Step Verification. The multi-factor authentication policy does not affect the way you access the AdWords API or the Google Ads API Beta in any other aspects--you can still use an OAuth2 refresh token and a developer token to access the AdWords API and the Google Ads API Beta as usual.

2-Step Verification ensures only strongly verified users have access to your Google accounts. Opt in now to avoid hitting the AuthorizationError.TWO_STEP_VERIFICATION_NOT_ENROLLED error in advance.

As always, if you have any questions or concerns, please post on our forum.

- Thanet Praneenararat, AdWords API Team

Upcoming changes to HTML5 template ads in AdWords API & Scripts

Thursday, August 2, 2018

Starting August 27, 2018, creating TemplateAds with IDs 419 (HTML5 Ads) may result in an error in AdWords API and Scripts. AdWords API users will see the error AdError.Reason.USER_DOES_NOT_HAVE_ACCESS_TO_TEMPLATE when creating HTML5 ads using various services.AdWords Scripts users may see an error that the ad cannot be saved when using the HTML5AdBuilder class to create a new HTML5 ad.

Existing accounts that have used or are currently using HTML5 ads will be whitelisted, and will continue to be able to upload HTML5 ads. Existing HTML5 ads will also continue to serve after this date.

If your account is new, or has never used HTML5 ads before, you may be affected by this change. We recommend one of the following options to fix this error:

You may apply for HTML5 access in your account by filling in the whitelist request form
You can use an AMPHTML instead of a regular HTML file in your HTML5 bundle. AMPHTML ads won’t trigger the above error.
You will automatically be approved for HTML5 access once you have spent more than $9000 USD on AdWords and your account is more than 90 days old

If you have questions about this change, please reach out to us on the AdWords API forum or AdWords Scripts forum.
- Anash Oommen, AdWords API Team

Ads Developer Blog