Category Archives: Google Ads Developer Blog

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

Security enhancements for search users

We’ve long worked to keep your searches on Google secure. We provided SSL encryption for signed-in searches in 2011 and have rolled that out to searches from the omnibox in the Chrome browser. Today, we are extending our efforts to keep search secure by removing the query from the referer on ad clicks originating from SSL searches on Google.com.

Advertisers will continue to have access to useful data to optimize and improve their campaigns and landing pages. For example, you can access detailed information in the AdWords search terms report and the Google Webmaster Tools Search Queries report.

Best practices

The AdWords search terms report (previously known as the search query performance report) lets you see search queries that generated ad clicks along with key performance data. And the Search Queries report available in Google Webmaster Tools provides aggregate information about the top 2000 queries, each day, that generated organic clicks.

If you use the query in the referer for reporting, automated keyword generation or landing page customization, then we suggest using the following alternatives: We understand that some partners may need to make changes to their systems and operations, but we think that this is the right path forward for the security of our users searching on Google.com.

Posted by: Paul Feng, Product Management Director, AdWords

Troubleshooting and error handling – handling exceptions thrown by the DFP API (Part I)

We often get a lot of questions about running into exceptions when using the DFP API and what to do about them. Seeing an exception from time-to-time is a normal part of the API workflow and should be expected. Some exceptions are caused by user errors, others by server issues. We strongly recommend that you write code to handle exceptions early on so that it’s easier to troubleshoot issues when they occur. In this blog post, we’ll go over the first of two major scenarios where adding exception handling will benefit you.

Creating or updating entities

When creating or updating entities with the DFP API, if you forget to supply a required field or set a field to an invalid value, the API throws an ApiException. If you write code to catch this exception, you can print out the error message to show the root cause. The following is an example showing how to do this when using the Google Ads API Java Client Library to create line items.

  // Create a line item.
  LineItem lineItem = new LineItem();
  // lineItem.setSomeThings(...);

  try {
    // Create the line item on the server.
    lineItemService.createLineItems(new LineItem[] {lineItem});
  } catch (ApiException e) {
    ApiError[] apiErrors = e.getErrors();
    for (ApiError apiError : apiErrors) {
      StringBuilder errorMessage = new StringBuilder();
      errorMessage.append(String.format(
          "There was an error of type '%s', on the field '%s',"
          + "caused by an invalid "
          + "value '%s', with the error message '%s'",
          apiError.getApiErrorType(), apiError.getFieldPath(),
          apiError.getTrigger(), apiError.getErrorString()));
      if (apiError instanceof NotNullError) {
        errorMessage.append(String.format(", with the reason '%s'.",
            ((NotNullError) apiError).getReason()));
      } else if (apiError instanceof FrequencyCapError) {
        errorMessage.append(String.format(", with the reason '%s'.",
            ((FrequencyCapError) apiError).getReason()));
      }

      // Append details of other ApiErrors that you are interested in.

      System.err.println(errorMessage.toString());
    }
  }
If you use this code to create a line item, it prints the following if you don’t specify an order ID:
There was an error of type 'NotNullError', on the field 'lineItem[0].orderId',
  caused by an invalid value '', with the error message 'NotNullError.NULL',
  with the reason 'NULL'.
If you provide invalid values for the frequency caps field when creating a line item, you’ll get the following:
There was an error of type 'FrequencyCapError', on the field
  'lineItem[0].frequencyCaps', caused by an invalid value '1000', with the
  error message 'FrequencyCapError.RANGE_LIMIT_EXCEEDED', with the reason
  'RANGE_LIMIT_EXCEEDED'.
There was an error of type 'FrequencyCapError', on the field
  'lineItem[0].frequencyCaps', caused by an invalid value '0', with the error
  message 'FrequencyCapError.IMPRESSIONS_TOO_LOW', with the reason
  'IMPRESSIONS_TOO_LOW'.
Depending on the type of application you’re writing, you may want to show these error messages to your user in a UI or log them. Note that you can find an entity’s required fields and valid field values in our reference documentation, for example, LineItem.

If you’re getting exceptions when creating or updating entities that are not ApiException errors (such as a SERVER_ERROR) and are unclear on how to diagnose them, then you can always write to us on the API forums and include the requestId of the call that failed and we will help you diagnose the issue.

Look forward to part II of this blog post where we will discuss handling exceptions that are thrown when retrieving entities.

 - , DFP API Team

Register Now for the Spring 2014 AdWords API Workshops

We're pleased to announce that the AdWords API Workshops are coming back for another round in April and May of 2014. Registration is now open!

Workshop topics include:
  • Shopping campaigns - how shopping integrates into the AdWords API
  • MCC scripts - The feature that was most requested is now available for beta signup
  • FeedServices updates - including the new location extensions setup
  • Targeting types - DSAs, DomainSetting and AutoTagging
  • Analytics - getting started with the Analytics API and how it fits within your AdWords apps
  • Bid Estimation - the different ways to estimate bids using the API

Not only are the workshops an important way to keep up-to-date with new features and best practices in the AdWords API, they are a great way for you to meet with and ask questions of the Google AdWords API team in person. This is also a key event for members of the community to bring their feedback directly to us. Finally, it’s a great opportunity for you to exchange ideas and best practices with fellow developers.

Register now and join us at a workshop in one of the following cities:
  • London, UK, April 29
  • Hamburg, Germany, May 13
  • Amsterdam, Netherlands, May 15
  • New York City, USA, May 5
  • San Francisco, USA, May 12
  • Shanghai, China, May 20 (in Chinese)
  • Taipei, Taiwan, May 22 (in Chinese)
  • Delhi, India, May 26
  • Sydney, Australia, May 29

Note: The workshops in the USA, Europe, and Australia are technical in nature and best suited to developers. Those in China, Taiwan, and India will have additional sessions accessible to a broader audience, including non-developers.

For more information on the agenda, location and logistics, please visit the AdWords API Workshop website.

- Marc Wandschneider, AdWords API Team

Search Network with Display Select (SNDS) is now supported in v201402

Starting with v201402 of the AdWords API, all newly created Search and Display Network campaigns will automatically be Search Network with Display Select campaigns. This means:
  • If you don't specify displaySelect when creating a Search and Display Network campaign, it will default to true, creating a Search Network with Display Select campaign
  • If you edit the networkSetting of an existing Search only campaign to target Content Network and do not specify displaySelect, we will upgrade the campaign to Search Network with Display Select by setting displaySelect to true
  • If you create a Search and Display Network campaign or edit the networkSetting of an existing Search only campaign to target Content Network, and specify displaySelect as false, you will receive an OPERATION_NOT_PERMITTED_FOR_CAMPAIGN_TYPE error
We encourage you to update your campaigns to Search Network with Display Select by setting the displaySelect property to true. Starting on September 16, 2014, we will start converting all Search and Display Network campaigns to Search Network with Display Select.

Search Network with Display Select uses improved signals and methods of predicting when and where your ads are likely to perform best, and sets a higher bar for when to show them. That means your ads are more likely to be shown to a smaller number of prospective customers, who are more likely to be interested in your offerings.

For more information about creating these types of campaigns, see our previous blog post. For more general information about this AdWords feature, please see here.

If you have any questions about this change, please contact us on the forum or via our Google+ page.

- Michael Cloonan, AdWords API Team

Enforcing Unique Names for Feeds in the AdWords API

Starting on April 29, 2014, the FeedService will start validating that newly added Feeds have unique names within an AdWords account. Once this change goes into effect, you will get a FeedError when you ADD a new Feed with the same name as another active Feed.

Currently it’s possible to have multiple Feeds with the same name. Introducing unique names will improve clarity in the user interface, and it will also allow Feeds to be referenced unambiguously by name, in addition to their ID.

Please ensure that your application is both uniquely naming Feeds and able to handle a potential naming conflict before this change goes into effect.

Shortly after this change is rolled out, we will append a unique value to the names of any remaining duplicates. For example, the following pair of Feeds on the left would be renamed as follows:

Old Names
New Names
My Sitelinks Feed
My Sitelinks Feed-1
My Sitelinks Feed
My Sitelinks Feed-2


- Adam Ohren, AdWords API Team

Step Inside AdWords on April 22 and be the first to see the newest innovations

It’s an exciting time to be a performance marketer. When we combine the creative magic of marketing with technology that’s available anytime, anywhere, and on any device, we can connect with customers in more innovative and relevant ways than ever before.

We are constantly working to improve AdWords, and on Tuesday, April 22, 2014 at 9am PT, Jerry Dischler, VP of Product Management for AdWords will share a brand new set of innovations with you live on the Inside AdWords blog. Register for the livestream here.

Building on the success of enhanced campaigns, Jerry will announce a number of new features that help you use context to reach customers in even more effective ways. We’ve designed new tools so you can increase awareness and engagement everywhere your customers are online – from the web, to the mobile web, to mobile apps. And when it’s time to manage your campaigns and measure performance, we want to help you do so efficiently in AdWords with new functionality designed for the multi-screen world.

These AdWords innovations are the result of countless conversations we’ve had over the past year with advertisers, both large and small. Based on your feedback, hundreds of product managers and engineers worked hard to build these new products. Simply put, we built these new products for you.

We hope you’ll join the April 22 livestream of our announcements featured here on the Inside AdWords blog. Register for the livestream here. Until then, follow us on our +GoogleAds page for sneak previews of what’s to come. Use hashtag, #StepInsideAdWords, to join in on the conversation.

Posted by Your Inside Adwords Team

Monetizing Unity Mobile Apps Just Got Easier

Calling all Unity app developers! We are excited to announce the launch of version 2.0 of the Google Mobile Ads Unity Plugin. The new version comes with a completely rewritten, but much more flexible, API. It includes the following new features:

  • A single package supporting both Android and iOS
  • Support for running apps in the Unity editor
  • Ability to create multiple banner instances
  • Ability to create banners of any size
  • Flexible ad request targeting
  • and much more!

Taking a closer look at how to integrate the plugin, a typical banner request in v2.0 looks like this:


BannerView bannerView = new BannerView(
    "YOUR_AD_UNIT_ID", AdSize.Banner, AdPosition.Top);
AdRequest request = new AdRequest.Builder().Build();
bannerView.LoadAd(request);

For custom banner sizes, simply pass in an AdSize object into the BannerView constructor:


AdSize adSize = new AdSize(250, 250);
BannerView bannerView = new BannerView(
    "YOUR_AD_UNIT_ID", adSize, AdPosition.Top);

Want to pass additional targeting parameters? No problem! Set your custom targeting when building the AdRequest:


AdRequest request = new AdRequest.Builder()
        .AddTestDevice(AdRequest.TestDeviceSimulator)
        .AddTestDevice("0123456789ABCDEF0123456789ABCDEF")
        .AddKeyword("unity")
        .SetGender(Gender.Male)
        .SetBirthday(new DateTime(1985, 1, 1))
        .TagForChildDirectedTreatment(true)
        .Build();

Listening for ad events is also extremely straightforward. Register for the callbacks you care about:


bannerView.AdLoaded += HandleAdLoaded;
bannerView.AdFailedToLoad += HandleAdFailedToLoad;
bannerView.AdOpened += HandleAdOpened;
bannerView.AdClosing += HandleAdClosing;
bannerView.AdClosed += HandleAdClosed;
bannerView.AdLeftApplication += HandleAdLeftApplication;

…

public void HandleAdLoaded()
{
    print("HandleAdLoaded event received.");
}

You can also manage the lifecycle of each BannerView by calling show(), hide(), or destroy().

To get access to these awesome features, check out the source code. Also stay tuned for upcoming support for interstitial ads.

If you have any feature requests or bug reports against the plugin, track it! If you have questions about how to use the plugin, speak up! And if you just want the latest news on what’s going on in the wonderful world of Google Ads, circle us!

 - , Mobile Ads Developer Relations

Changes Required for Creating New Campaigns in the AdWords API v201402

With v201402 of the AdWords API, it is now necessary to set the advertisingChannelType when you create a new Campaign. As part of this change, the networkSetting attribute is now used to define in more detail where you want your ads to appear.

All newly created campaigns, or campaigns that are switched into targeting both Search and Display using v201402, will automatically be SNDS campaigns. This behavior is the same as you will see in the AdWords User Interface, bringing that and the API into closer alignment. Existing applications are unaffected. As we continue to invest in Search Network with Display Select (SNDS) and see strong adoption from advertisers, we will over time be upgrading Search & Display Network campaigns to Search Network with Display Select.

With the introduction of both SNDS and Shopping campaigns, the new advertisingChannelType field allows you to state which kind of Campaign you're building. The field is an enumeration, which can be set to:
  • SEARCH, for the Search Network, including (for campaigns created with older API releases) Search and Display hybrids, and now SNDS campaigns;
  • DISPLAY, for the Google Display Network only;
  • SHOPPING, for Shopping campaigns serving Product Listing Ads on Google and Google Shopping.
Note that an UNKNOWN value can be returned if the value set isn't supported by the called version of the API. This covers situations where new options are added in newer releases.

This table specifies the only valid combinations of parameters for newly created campaigns on the networks that you intend to target.

Networks Targeted by the settings on the right
advertisingChannelType
displaySelect
Enabled networkSettings
Search Network
SEARCH
false
Search Networks only
Search Network with Display Select
SEARCH
true or unspecified
Search & Content networks
Display only
DISPLAY
false or unspecified
Content Network only
Shopping only
SHOPPING
false or unspecified
Search Network only

Any parameter combination other than the above when creating a new campaign or making targeting changes to existing campaigns will be rejected with an OPERATION_NOT_PERMITTED_FOR_CAMPAIGN_TYPE error.

While you can no longer create Search & Display Network campaigns, existing campaigns of this type will remain unchanged. You can identify them by their displaySelect attribute being false, while both the Search and Content Networks are enabled. These campaigns should be migrated to SNDS by setting displaySelect to true.

The advertiserChannelType and isDisplaySelect fields are also present in reporting, so you can see how your Campaigns are configured.

If you have any questions about this change or the AdWords API in general, you can post them on our developer forum. You can also follow our Google+ page for updates about the AdWords API.
 - , AdWords API Team

Support for v201402 Reports in AdWords Scripts

We are announcing support for AdWords API v201402 reports in AdWords scripts. The following new reports are available for use:
  • BID_GOAL_PERFORMANCE_REPORT
  • PAID_ORGANIC_QUERY_REPORT
  • PRODUCT_PARTITION_REPORT
  • SHOPPING_PERFORMANCE_REPORT
You can refer to https://developers.google.com/adwords/api/docs/appendix/reports for the list of supported columns and other details for these new reports.

If you use API versioning in your reports, then you need to modify your code to use v201402 as shown below. If you don’t use API versioning, no code changes are required.


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

Anash P. Oommen, AdWords Scripts Team

AdWords API users – don’t wait to migrate from ClientLogin to OAuth 2.0!

ClientLogin authentication support for the AdWords API will sunset along with v201309 on July 21st, 2014. But it doesn’t mean you should wait till the last minute to migrate!

We have plenty of resources to help you migrate. It might take longer than expected to migrate to OAuth2, especially if you don't already use a single top-level MCC to manage your AdWords accounts.

Start your migration as soon as possible and reach out to us early on the AdWords API Forum with any questions.

- Ray Tsang, AdWords API Team