Category Archives: Google Ads Developer Blog

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

Announcing v201509 of the AdWords API

Today we’re announcing the release of AdWords API v201509. Here are the highlights:

  • Improved batch processing. The new BatchJobService supports all of the same operations as MutateJobService, but offers additional features such as support for creating dependent objects using temporary IDs, better error reporting, improved performance, and a much higher limit on the number of operations per job. Check out the accompanying guide to get started.
  • AdWords for video and TrueView video campaigns in reports. The AdWords API now supports TrueView campaigns that have migrated from AdWords for video, and several reports now include statistics and new metrics for these campaigns. See the release notes for the complete list of changes and additions.
  • New reporting columns for multi-channel advertisers are available on multiple reports making it easier to track interactions vs. clicks.
  • Customer Match. Build and target user lists from email addresses using the new CrmBasedUserList.
  • Structured snippets can now be created using extension setting services.
  • Conversion column changes. Conversion columns have been modified, added, or removed on multiple reports to coincide with the upcoming conversion reporting changes in AdWords. See the release notes for the complete list of changes.
  • HTML5 ads can now be added as TemplateAds using template ID 419. In addition, MediaService now supports uploading media bundles for use with this new template.
  • Geo targeted ad customizers. Target each ad customizer feed item to a specific geographic location.
  • Gmail sponsored promotions. The AdWords API now fully supports the Gmail image, single promotion, and multi-product ad formats via template ads.
  • Dynamic remarketing ads have new placeholder fields for setting upgraded URL attributes such as tracking templates, custom parameters, and final URLs.
  • Active View reporting. New fields for Active View viewable impressions, measurable impressions, measurable cost, and measurability are now available in multiple reports.

If you’re using v201502 of the AdWords API, please note that it’s being sunset on November 12th, 2015. We encourage you to skip v201506 and migrate straight to v201509. If you’re using v201506, be aware it’s now marked deprecated and will be sunset on April 11th, 2016.

As with every new version of the AdWords API, we encourage you to carefully review all changes in the release notes and the v201509 migration guide. The updated client libraries and code examples will be published shortly. With this release, we’ve also updated the Required Minimum Functionality document to include some of the newly added features. If you have any questions or need help with migration, please post on the forum or the Ads Developers Plus Page.

A note on ad size and mediating smart banners

Smart banners are a handy thing for publishers. You can drop an AdMob smart banner into a layout or storyboard, and it’ll stretch or squeeze itself at runtime until it’s just the right size for the device, then request an ad to match. They’re a great feature with all the extra work hidden under the hood.

If you’re building an Android mediation adapter or custom event, though, things aren’t quite as simple -- after all, you’re under that hood, too! A common rough spot for developers is retrieving a smart banner’s size. Because the Google Mobile Ads SDK uses constants to internally represent a smart banner’s height and width, the getHeight and getWidth methods of a smart banner’s AdSize will return those constants (they’re negative numbers, so they’re quite hard to miss). That means relying on calls to getHeight and getWidth to determine a smart banner’s true size isn’t a workable strategy.

So how should adapter and custom event developers calculate sizes correctly? By avoiding getHeight and getWidth, and instead asking for pixel counts using getHeightInPixels and getWidthInPixels, two other methods offered by AdSize. You can scale their return values according to the device’s metrics and end up with the same kind of DPI values returned by getWidth and getHeight for other ad sizes. Here’s a code snippet that shows how it’s done:


// Get the raw pixel counts.
int widthInPixels = size.getWidthInPixels(context);
int heightInPixels = size.getHeightInPixels(context);

// These metrics include screen density, which is what we’re after.
DisplayMetrics displayMetrics = Resources.getSystem().getDisplayMetrics();

// These are values you can send to your mediated network’s SDK.
int widthInDpi = Math.round(widthInPixels / displayMetrics.density);
int heightInDpi = Math.round(heightInPixels / displayMetrics.density);

Once you finish the math, you’ll have proper DPI values that can be sent to whichever network you’re mediating. The calls to getHeightInPixels and getWidthInPixels require a valid Context, but you can use the one provided as a parameter to the requestBannerAd methods in MediationBannerAdapter and CustomEventBanner.

Now you know the best way to gauge the size of a smart banner! Use this approach and it’ll help keep your mediation running smoothly.

If you have technical questions about this (or anything else relating to the Google Mobile Ads SDK) stop by our forum.

Creating native creatives with the DFP API

Recently, we announced the availability of native ads for apps in DFP. Here, we’re going to introduce you to creating native creatives with the DFP API using the ads Java client library. A native creative consists of a set of assets (headline, image, etc.) which are sent to mobile apps for custom rendering in their own code (see our Android and iOS developer guides for details).

Native creatives are actually just another type of template-based creative. While the DFP UI abstracts this, in the API you create a native creative using a TemplateCreative with the system-defined native template ID. The creative template IDs available in your network can be retrieved by the getCreativeTemplatesByStatement method in the CreativeTemplateService. You can also view these IDs in the UI under Delivery > Creatives > Native ad formats (see the ID below each native ad format name in the table). The native app install template ID is 10004400.


TemplateCreative nativeAppInstallCreative = new TemplateCreative();
nativeAppInstallCreative.setCreativeTemplateId(10004400L);

Because native creatives do not have a predetermined size, you need to set a placeholder size of 1x1.


Size size = new Size();
size.setWidth(1);
size.setHeight(1);
size.setIsAspectRatio(false);
nativeAppInstallCreative.setSize(size);

Finally, specify a name and destination URL; this example is for the Pie Noon app:


nativeAppInstallCreative.setName("Pie Noon native ad");
nativeAppInstallCreative.setDestinationUrl(
"https://play.google.com/store/apps/details?id=com.google.fpl.pie_noon");

Settings specific to native creatives are set via template variables. An app install native creative requires the following unique template variable names to be set:

  • Headline
  • Body
  • Image
  • Price
  • Appicon
  • Calltoaction
  • Starrating
  • Store
  • DeeplinkclickactionURL

Note that creative template variables are case sensitive and those of type AssetCreativeTemplateVariableValue (“Image” and “Appicon”) must have a unique filename.

You can find the full Java example on how to create native creatives in our GitHub repository here. All of our other ads client libraries have similar examples.

As always, if you have any questions, feel free to drop us a line on the DFP API forums or the Ads Developer Google+ page.

Register now for Fall 2015 AdWords API Workshops!

Fall 2015 AdWords API Workshop registration is now open. Access the registration forms on the workshop website at www.adwordsapiworkshops.com.

Once you choose a location we'll send you an email confirming your registration.

Workshops will be held on the following dates and locations:

  • New York City: October 20
  • San Francisco: October 22
  • London: October 27
  • Hamburg: October 29
  • Tokyo: October 29
  • Amsterdam: November 3

These workshops are technical in nature and are ideal for API developers. We hope to see you at these events. Register today!

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

Support for v201506 reports in AdWords Scripts

We have added support for AdWords API v201506 reports in AdWords Scripts. This version adds support for FINAL_URL_REPORT, the Upgraded URLs-compatible replacement for the DESTINATION_URL_REPORT.

This version also introduces several changes to the reporting columns
If you use API versioning in your reports, then you need to modify your code to use v201506 as shown below. If you don’t use API versioning, no code changes are required.

var report = AdWordsApp.report(query, {
apiVersion: 'v201506'
});
If you have any questions about this feature or AdWords scripts in general, you can post them on our developer forum.

Referrer changes for ad clicks

We are updating the referrer of ad clicks to improve security and system reliability for users searching on Google. Starting within October, the referrer for many ad clicks will only contain the Google domain from which the click occurred (domains like https://www.google.com or https://www.google.ca). This means that we will no longer be communicating specific paths such as “google.com/aclk” or “googleadservices.com/pagead/aclk.”

While the referrer will no longer differentiate Google’s organic search clicks from ad clicks, and in some cases may be absent entirely, there are still multiple strategies to track the origin of your clicks. Recommended strategies include: This change is a continuation of our general user security efforts. Users are safer when sites use HTTPS instead of HTTP, which is why we encourage the use of HTTPS. In fact, in August 2014 we began to use HTTPS as a ranking signal.

By default, browsers do not pass a referrer from HTTPS sites to HTTP sites. To minimize advertiser disruption, we implemented a custom ads solution back when the Google search page migration to HTTPS took place. Now, many modern web browsers provide better control over referrer behavior via the meta referrer tag. This development is an improvement over our previously-implemented custom ads solution both in terms of reliability and latency.

AdWords API Fall 2015 Workshops Announced

The AdWords API Workshops are back, and the registration form and agenda will be available on the website soon: www.adwordsapiworkshops.com. In the meantime, you may review the site Resources section for previous event presentations.

These workshops are a series of technical events, ideal for those who are working with the AdWords API.

Workshops will be held on the following dates and locations:

  • New York City - October 20
  • San Francisco - October 22
  • London - October 27
  • Hamburg - October 29
  • Tokyo - October 29
  • Amsterdam - November 3

Stay tuned and keep an eye on the website for more details on how to register.

--AdWords API Team

Support for shared negatives in AdWords Scripts

AdWords Scripts now support negative keyword and excluded ad placement lists, and the ability to share them across campaigns. Follow these links for implementation details and code examples: We have also released a new solution named Master Negative List that uses this feature to maintain a master list of negative keywords and placements for AdWords accounts. The list of negative criteria can be managed from a spreadsheet. Separate versions are available for AdWords accounts and manager accounts.

Special thanks goes to Terence Nip, who implemented this feature during his summer internship at Google.

Give this feature a try and let us know what you think! You can post your questions and feedback on our developer forum.

Manual Ad Break Playback Part Deux: Welcome Back!

Today we’re expanding on our earlier blog post, Manual ad break playback in the IMA SDKs. One of the major benefits mentioned in that blog post is the ability to let your users skip ads they’ve already seen when they resume a video stream they previously suspended. We’re going to show you how to implement that functionality. For the purposes of this demo, we’ll be using the HTML5 SDK, but the principles outlined here can be used to achieve the same functionality in all four of our SDK flavors.

Prerequisites

If you’d like to follow along with these samples, you’ll need to first:

  1. Get a copy of our simple sample for HTML5.
  2. Modify that sample to disable automatic playback of ad breaks, as outlined in this guide. Be sure to remove the original call to adsManager.start() in onAdsManagerLoaded!
  3. Change the ad tag to a playlist with multiple mid-rolls (like this one) so you can see the behavior in action.

Step 1: Saving the user’s progress

The first step towards our ultimate goal is to save the current time of the video when the user leaves the page. For simplicity’s sake, we’re going to be using HTML5’s built-in localStorage object. We’re going to override window.onbeforeunload to grab the current time of the video element when the user leaves the page and save it in local storage.


function init() {
videoContent = document.getElementById('contentElement');
playButton = document.getElementById('playButton');
playButton.addEventListener('click', requestAds);

window.onbeforeunload = onUserExit;
}

function onUserExit() {
if (videoContent) {
localStorage.setItem('watched_time', videoContent.currentTime);
}
}

Step 2: Restoring the user’s progress

Now that we’re saving the user’s progress, we’ll want to restore the video to that point when the user returns to the page. We’re going to add some code to the init method to grab the stored current time (if it exists) and seek to that time when our video loads.


function init() {
videoContent = document.getElementById('contentElement');
playButton = document.getElementById('playButton');
playButton.addEventListener('click', requestAds);

window.onbeforeunload = onUserExit;

watchedTime = localStorage.getItem('watched_time') || 0;
videoContent.addEventListener('loadedmetadata', function() {
videoContent.currentTime = watchedTime;
});

}

Step 3: Skipping previously viewed ads

Now that we’re keeping track of the user’s progress and restoring that progress when the user returns, we can skip and ad breaks they watched in a previous visit. To do that, we’ll modify our adBreakReadyHandler to call adsManager.start() only when the loaded ad break is set to play after the user’s most recent saved progress. To ensure the video starts after the skipped ad breaks, we’ll also add a call to videoContent.play() when we decide to skip an ad break.


function adBreakReadyHandler(event) {
if (event.getAdData().adBreakTime >= watchedTime ||
event.getAdData().adBreakTime == -1) { // -1 ensures we play post-rolls

adsManager.start();
} else {
videoContent.play();
}

}

That’s all there is to it! Try starting your video and watching the first mid-roll break. When you leave the page and come back, clicking the play button will result in the video playing from where you left off. The first ad break you’ll see is the second mid-roll break.

As always, if you have any questions feel free to contact us via the support forum.

Updated AdWords API remarketing guides

Have you ever wanted to advertise to people who previously visited your site or mobile app? This remarketing strategy can be implemented using the AdWords API. For example, you can target ads to people who left your website without buying anything to encourage them to return and make a purchase.

We recently updated our Remarketing and Rule-based Remarketing guides to more clearly show you how to use the API to get started quickly and implement some of the most common remarketing strategies.

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