Category Archives: Google Ads Developer Blog

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

Reach your most valuable customers with Customer Match

Did you know that you can reach past website visitors and app users? Let's say you’re a travel brand. You can now reach people who have joined your rewards program as they plan their next trip. For example, when these rewards members search for “non-stop flights to new york” on Google.com, you can show relevant ads at the top of their search results on any device right when they’re looking to fly to New York. And when those members are watching their favorite videos on YouTube or catching up on Gmail, you can show ads that inspire them to plan their next trip.

Behind the scenes, this works by adding people to a UserList.

Prior to v201509 there were four different types:

  • BasicUserList: Remarketing to people who took specific actions (such as purchasing shoes) on your website or app.
  • RuleBasedUserList: Remarketing to people who follow advertiser-defined rules. The rule can be as simple as all visitors to your website (which is the easiest way to start remarketing).
  • LogicalUserList: Combining two or more user lists. For example, customers who purchased shoes and/or visited specific pages of your website at specific times.
  • SimilarUserList: Remarketing to people that share similar interests and behaviors with those in other user lists. For example, you can reach new potential customers that share similar interests and behaviors with those who purchased shoes on your website.

A SimilarUserList is automatically created by Google for each UserList based on a variety of factors, such as the number of people on the original list, how recently these people joined the original list, the types of sites that these people browsed and whether the original list is your own. This process may take up to 4 days once the seed list is created.

You can target or exclude user lists at the ad group level, but you can only exclude them at the campaign level.

As a reminder, please have a look at the policy for advertising based on interests and location and the policy for remarketing lists for search ads.

Customer Match

v201509 introduced a new user list type: CrmBasedUserList. It enables you to create a user list using your customers’ email addresses.

Suppose you have an existing database of email addresses of your newsletter subscribers for “people who love shoes”. With a CrmBasedUserList you can reach these subscribers and adjust your bidding accordingly, present different ads, and more. You can use a SimilarUserList of your subscribers list to potentially find new customers who share similar behaviors and interests.

Each CrmBasedUserList must have an optOutLink to provide a link to the page where people can manage their preferences for receiving email messages from the advertiser, including opting out of the advertiser email messages.

Before using this targeting strategy, please take the time to read our policy page.

A CrmBasedUserList can be used for targeting on the Search network, YouTube and Gmail, whereas a SimilarUserList of a CrmBasedUserList can only be used for targeting on YouTube and Gmail.

Keep the following points in mind when using a CrmBasedUserList:

  • Advertisers must collect email addresses as 1st party. For example, an agency can submit email addresses on behalf of an advertiser if the advertiser collected the email addresses directly from its customers.
  • Email addresses can be from Gmail or non Gmail addresses as long as they are associated with a Google account. We recommend adding all available email addresses to maximize the size of the result.
  • Ads will serve only when the user list has at least 1,000 active members. Active members are those who have used Google Search, YouTube, or Gmail at least once over the last 30 days.

If you want to read more about CrmBasedUserList, have a look at our guide and code examples.

As always, feel free to visit us or ask questions on the AdWords API Forum or our Google+ page.

, AdWords API Team

Announcing v201511 of the DFP API

If I asked you "why do you love this time of year?", I might get back a variety of responses ranging from "the fall foliage where all the leaves change color," or "turkey, stuffing, and pumpkin pie," or perhaps the most obvious answer since the advent of steamed milk - "pumpkin spice lattes." For me, it's none of those things. The reason why I get uncomfortably excited every year when November rolls around is because the DFP release & deprecation schedule aligns perfectly so that the last release of the year happens right about now. So without further ado, I present you with the latest and greatest version: v201511.

Trafficking Updates

We've been going back and cleaning up our APIs to make them simpler and easier to use. Remember that target platform unification change we made? Now that you've switched over to using TargetPlatform.ANY (and why should you miss out on that sweet mobile traffic because of a pesky ENUM?) we've removed it entirely from the LineItem and AdUnit objects. On the creatives front, Template and Custom creatives now use CreativeAssets for associated assets.

Sales Manager Updates

On the sales manager front, we've exposed a few reporting dimension attributes: PROPOSAL_FLAT_FEE and PROPOSAL_LINE_ITEM_FLAT_FEE, which represent the billing setting for the flat fee checkbox in the UI. In addition, if setting deliveryRateType and roadblockingType are things that you have been wishing for, consider your wish granted. In v201511, you can now set DeliverySettings on ProductTemplates.

See full release notes here.

As a reminder, with each new release comes a new deprecation. If you're using v201411 or earlier, it's time to look into upgrading. v201408 will be sunset at the end of November 2015, and v201411 will be sunset at the end of February 2016. If you have any questions about upgrading, let us know on the developer forum.

 - , DFP API Team

Fetching invalid product offers in Content API

The Shopping Content API now supports the retrieval of invalid product offers. This means that offers such as those with an invalid category or a mismatched URL can now be retrieved and reviewed via the API. This will enable you to more easily view invalid product offers and debug API requests. Going forward, invalid product offers that are newly inserted via the API will be available for review in the Diagnostics tab of the Merchant Center.

How should you go about retrieving your invalid offers from the API? You can do this by using a new optional URL parameter that has been added to the products.list method, called includeInvalidInsertedItems. (Yes, it's a long name; we apologize for the extra keystrokes.) If you set this parameter to true, your response will include products that were invalid at the time of insertion. The default value is false, so if you don't include the parameter in your request, you will not have invalid products in your response. This preserves existing behavior, with the exception that if you have invalid product offers from feeds, they will also not be returned in the response. Note that you can still use the 'get' and 'delete' methods to reference product offers directly by ID, even if they are invalid. No additional parameter is needed for those methods.

We are introducing one new error when inserting product offers, called "The item could not be inserted". An invalid offer is inserted only if it does not overwrite an existing valid offer. When there already is an existing valid offer, an additional error is returned, stating "The item could not be inserted". This also means that the product offer will not be available for review from products.list nor in the Diagnostics tab. Product offers are matched based on the full product ID, of the form channel:languageCode:countryCode:offerId.

It's important to remember that the new includeInvalidInsertedItems parameter will only filter between valid and invalid product offers, as determined at insertion time, ignoring whether they were or not later disapproved. This means that it will return invalid product offers inserted both from the API and from feeds. To distinguish between approved and disapproved product offers, use the Productstatuses Service.

To try out this new parameter, add includeInvalidInsertedItems as a query parameter to your products.list request. If you have more questions or feedback, please head on over to our developer forum.
  —Yufeng Guo, Shopping API Developer Relations

Preparing for universal ads in DCM

As you may have heard, universal ads are launching to DCM accounts throughout November and December 2015. The centerpiece of these new ads is a set of unified compatibilities that remove the distinction between in-app and in-page environments. To learn more, visit our DCM user or partner support sites.

What does this mean for DCM/DFA Reporting and Trafficking API users?

Currently, the API does not expose these new compatibilities, although full support is coming in a future release. Until then, the in-app and in-page compatibilities you currently use will remain available. This means that there are no immediate changes necessary to your applications, but you may notice some discrepancies between the values presented by the API and UI:

API compatibility
New UI compatibility
APP
In-app
APP_INTERSTITIAL
In-app interstitial
IN_STREAM_VIDEO
In-stream video
WEB
Display
WEB_INTERSTITIAL
Display interstitial

What can API users do to prepare?

To make your future transition to universal ads easier, we recommend that API users begin transitioning off of in-app placements now. Be aware that it will no longer be possible to traffic in-app placements once universal ads support is added to the API, and existing in-app placements will not be automatically converted to use the new unified compatibilities.

Instead, newly trafficked placements should be created using in-page compatibilities. These placements will be mapped directly to the new unified compatibilities (as seen in the table above), making them immediately eligible to serve in both environments.

Questions about this or anything else DCM API related? Contact us via our support forum.

 - , DCM API Team

Announcing the Google Mobile Ads API Demo apps

The Google Mobile Ads API Demo apps for Android and iOS are now available. These new apps contain advanced examples for both AdMob and DoubleClick for Publishers (DFP) that demonstrate features of the Google Mobile Ads SDK that can help you improve the user experience and maximize ad revenue. Whether you’re a new publisher or a seasoned veteran of the SDK, the API Demo apps showcase new ways to customize ad requests, experiment with multiple ad sizes, and compare AdMob and DFP technologies.

Download the API Demo apps for Android and iOS today and explore new ways to improve your integration with the Google Mobile Ads SDK!

If you have any questions regarding the new API Demo apps, feel free to contact us through our forum.

 - , Mobile Ads Developer Relations

Check out the latest workshop content!

We’ve completed the last round of the AdWords API Workshops, and you can check out all the content online by visiting the official website, www.adwordsapiworkshops.com, and clicking on Resources.

Be sure to also check out our YouTube channel for the recorded presentations.

If you have any questions about the AdWords API Workshops, you can post them on our forums. Check out our Google+ page for Ads APIs updates.

Gustavo M. P. Moreira, AdWords API Team

DoubleClick Ad Exchange Seller REST API Report changes

On November 17th, 2015, we'll be updating the Ad Exchange Seller REST API to make it consistent with the user interface. Specifically, we'll remove the ability to download saved reports or retrieve the dimensions we retired in April.

Requests made after this date for these dimensions will result in that dimension being ignored and requests for saved reports will result in an error.

As a reminder, the dimensions we retired in April are:

  • AD_FORMAT_CODE
  • AD_UNIT_ID
  • AD_UNIT_CODE
  • DSP_ID
  • EXPANSION_TYPE_CODE
  • PLATFORM_TYPE_CODE

For a full list of available dimensions, please see the AdX Seller REST API documentation.

Follow our Google+ page for other announcements and updates.

-- Dean Lukies, Ads Developer Relations

Multiple scenes and ads in Unity

When developing with AdMob in Unity, it is a common practice to make your banner ads persist across multiple scenes. This blog post will highlight best practices to accomplish this with the Google Mobile Ads Unity Plugin.

The most straightforward approach is to link the lifecycle of ads to that of the scenes they’re displayed in. When transitioning from one scene to another, existing ads are destroyed before leaving the first scene. New ads can then be created and displayed in the next scene.

The downside of this approach is that every scene transition would result in a new banner request. This may not be desirable if scene transitions are frequent and occur quickly.

An alternative is to use a GameObject as a wrapper for banners or interstitials. By default, each GameObject in a scene will be destroyed once the new scene is loaded (unless you use additive scene loading). However, you can make a GameObject survive across scenes by marking it with DontDestroyOnLoad. You can then use the GameObject.Find method to obtain references to the wrapper GameObject from scripts in other scenes.

Here is an example of how to use a GameObject to wrap banner ads:


// FirstSceneScript.cs
void Start() {       
  // Create a wrapper GameObject to hold the banner.
  GameObject myGameObject = new GameObject("myBannerAdObject");
  myGameObject.AddComponent<BannerWrapper>();
  // Mark the GameObject not to be destroyed when new scenes load.
  DontDestroyOnLoad(myGameObject);
}
The BannerWrapper GameObject is a wrapper for a BannerView. 

// BannerWrapper.cs
using System;

using UnityEngine;
using GoogleMobileAds;
using GoogleMobileAds.Api;

public class BannerWrapper : MonoBehaviour {
    
    public BannerView bannerView;
    
    void Start()
    {
        bannerView = new BannerView(
                "your_ad_unit_id", AdSize.SmartBanner, AdPosition.Bottom);
        AdRequest request = new AdRequest.Builder().Build();
        bannerView.LoadAd (request);
        
        bannerView.Show();
    }
}

In SecondSceneScript.cs, which is attached to the second scene, you can find a GameObject by name, get the BannerWrapper component, and access the BannerView:


// SecondSceneScript.cs
void Start () {
    GameObject myGameObject = GameObject.Find("myBannerAdObject");
    BannerWrapper bannerWrapper = myGameObject.GetComponent();
    bannerWrapper.bannerView.Hide();
}

By managing your ads efficiently and seamlessly across scenes, you are sure to provide a better ad experience for your users. If you have any questions about Unity integration, you can reach us on our forum. You can also find our quick-start guide linked here. Remember that you can also find us on Google+, where we have updates on all of our Google Ads developer products.

 - , Mobile Ads Developer Relations

Announcing v2.3 of the DCM/DFA Reporting and Trafficking API

Today we're releasing v2.3 of the DCM/DFA Reporting and Trafficking API. This release brings a number of enhancements, such as:

Deprecation and sunset reminder

In accordance with our deprecation schedule, this release marks the beginning of the deprecation period for v2.1, which will sunset on February 29th, 2016.

As a reminder, February 29th is also the end of the extended migration window we've provided to users of v2.0 and earlier versions of the API. The current schedule is as follows:

API Version
Deprecation Date
Sunset Date
v1
3 Aug 2015
29 Feb 2016
v1.1
v1.2
v1.3
v2.0
v2.1
4 Nov 2015

To avoid an interruption in service, all users are required to migrate off of these versions by 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!

 - , DCM API Team

Changes to validation for AdWords API iTunes AppConversions

What’s new?

The validation for AppConversions will become stricter starting on November 9, 2015. If you’re using AppConversions in v201509 or v201506 with AppPlatform: ITUNES, you’ll need to make sure that you’re using the correct AppConversionType.

What was the old behavior?

When v201509 was first released, the API would not throw an error if the incorrect value was sent in a request for an iTunes AppConversion. The API automatically converted to the correct AppConversionType. For example, if the value DOWNLOAD was passed into v201509 for an iTunes AppConversion, then that value would automatically be converted to FIRST_OPEN.

What is the new behavior?

In v201509, AppConversionType DOWNLOAD changed to FIRST_OPEN for iTunes apps. Here’s what you will need to do:
  • For v201506 or earlier, you must pass in AppConversionType DOWNLOAD rather than FIRST_OPEN.
  • For v201509 or later, you must pass in FIRST_OPEN instead of DOWNLOAD.
Passing in the incorrect value will result in the error DOMAIN_EXCEPTION from the API starting on November 9.

Note: This only impacts iTunes conversions. There will be no changes to the validation for AppConversions with an AppPlatform of ANDROID.

Where can I learn more?

For more information on mobile apps and conversions, check out these guides: Questions? Visit us on the AdWords API Forum or our Google+ page.

Nadine Sundquist, AdWords API Team