Google Ads Developer Blog

Embedding Google AdMob Ads Within A UITableView

2012-03-06T13:55:00.000-08:00

We previously talked about docking AdMob ads to the bottom or top of a UITableView. In response to that post, we’ve had a lot of developers asking us about embedding AdMob ads within the UITableView cells, so we wanted to share how this can be best achieved.

Challenge

Placing ads within a Table View in iOS as list items can bring up a number of issues:

Inflated impression numbers because tables in iOS refresh when the user scrolls.
The one-to-one mapping between data in the Table View and the application’s model will usually be lost.

Choosing A Solution

Table Views in iOS are populated by implementing the tableView:cellForRowAtIndexPath: method. Cell objects are often reused so that new ones aren’t instantiated each time the Table View is refreshed (by a scroll for example). There are two ways that ads can be implemented within Table View cells:

Only use one GADBannerView throughout the table. This would mean that the same ad is displayed in different cells in the table (preferred).
Leverage dequeueReusableCellWithIdentifier: so that GADBannerViews are created only when new cells are created.

Using one GADBannerView throughout the table does decrease ad diversity but generally increases the CTR for the ads that are shown because the user will more likely see the ads that are displayed. The example below will show how to implement this approach as it is the better practice.

Solution - Single GADBannerView Method

For the purposes of this example, let’s assume that every 10th element in the list is going to be an ad. This means tableView:cellForRowAtIndexPath: will be set up with a conditional that modifies the placement of the GADBannerView for every tenth cell:

- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {
  int row = [indexPath row];

  // Assume that kFrequencyAdsInCells is 10 so every 10th row is an ad
  // Don't want first item to be an ad so use 10-1=9 instead of 0
  if ((row % kFrequencyAdsInCells) == (kFrequencyAdsInCells)) {
    cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
  
    //Need to create a new cell object
    if (cell == nil) {
        cell = [[[UITableViewCell alloc] initWithFrame:CGRectZero
                                       reuseIdentifier:CellIdentifier]
                autorelease];
    }
    // If bannerView_ has a superview, then it has been added to a cell
    if (!bannerView_.superview) {
      // First ad request made, make the ad request and add it to this cell
      [self requestAd];     
    }
    // The banner will be removed from the other cell and put into here
    [cell.contentView addSubview:bannerView_];


}
…

Since ads are being inserted into the Table View now, any previous mapping to data in the model will be lost. Some quick math is necessary here to figure out how the rows in the Table View line up.

  // Complete in cellForRowAtIndexPath: if not ad
  
  // Make sure we get all of the items from our model
  row = row - floor((float)row/kFrequencyAdsInCells);
  
  cell.textLabel.text = [dataController_ objectInListAtIndex:row];

The methods tableView:NumberOfRowsInSection: and tableView:heightForRowAtIndexPath: will need to be modified as well. The method tableView:NumberOfRowsInSection: would now return the number of elements (including ads in that number) and tableView:heightForRowAtIndexPath: would return the height of an ad for every tenth cell, respectively.

If you have any questions about embedding ads within a UITableView, or even any questions about the SDK in general, feel free to post them in our forum. Keep an eye out for AdCatalog v2 for all kinds of advanced layouts options integrated in the project.

- Raj Parameswaran, AdMob Team

Resources to help with the migration to AdWords API AdHoc reports

2012-03-06T12:32:00.001-08:00

Last week we sunset all versions of the AdWords API prior to v201109. If you have not yet migrated to v201109, you will now receive errors when making calls using previous versions.

For users still working on the transition from v13 to AdHoc reports, we want to remind you of resources available to help you out:

The report migration guide provides a side-by-side mapping between the fields available in the v13 ReportService and those available in v201109.
The mapping report to the UI guide maps the concepts and naming conventions used in the User Interface (UI) and the AdWords API reports.
Report basics covers how to structure and download reports.
This blogpost covers best practices for when to schedule reports, and this post covers how to download reports for multiple clients.

For additional resources visit the AdWords API documentation.

We also encourage you to submit questions to the forum or ask them during office hours.

Post by Katie Miller, AdWords API Team

Discover DFP API v201201: Syncing Up

2012-03-06T11:00:00.000-08:00

In the newest version of the API, v201201, we’ve added a feature to streamline the syncing of information in your DFP network to another system. Previously, this was possible but required repeatedly downloading the same objects to see if they had been modified. Now, a new PQL field exists, lastModifiedDateTime, which can be used to return objects based on their modification dates. Below is a PHP example that uses the latest client library to display all line items modified in the past 30 days.

// Get the LineItemService.
$lineItemService = $user->GetService('LineItemService', 'v201201');

// Calculate time from thirty days ago.
$thirtyDaysAgo = date(DateTimeUtils::$DFP_DATE_TIME_STRING_FORMAT,
    strtotime('-30 day'));

// Create bind variables.
$vars = MapUtils::GetMapEntries(array(
    'thirtyDaysAgo' => new TextValue($thirtyDaysAgo)));

// Create statement object to only select line items that
// have been modified in the last 30 days.
$filterStatement = new Statement(
    "WHERE lastModifiedDateTime >= :thirtyDaysAgo "
    . "LIMIT 500", $vars);

// Get line items by statement.
$page = $lineItemService->getLineItemsByStatement($filterStatement);

You will notice that we utilized a constant, DFP_DATE_TIME_STRING_FORMAT ('Y-m-d\TH:i:s'), from the library to easily format the date/time string. Also, keep in mind that the date and time specified should be in terms of the time zone that is configured for the network and any timezone specified in the string will be ignored by the server.

We hope you'll use this new feature to help save bandwidth and processing time. You can check out a full working example in PHP or other languages in our client libraries.

Feel free to leave us a comment on the forum with any feedback you have for the API or topics you would like to see in the discover series.

- Paul Rashidi, DFP API Team

Frequently Asked Questions for the AdSense Management API

2012-03-06T05:35:00.000-08:00

Since launching the AdSense Management API in October last year, we’ve received a number of questions and feedback from you while coding your applications. Today, we’ll address the most frequently asked questions and share some best practices.

How do I authenticate? Do I need to use OAuth?

Right now, the only authentication method we support is OAuth, but don’t let that intimidate you; OAuth 2.0 supports several authentication methods, for web server, client-side and installed applications and devices, which together cover all use cases.

You can find more information on how to authenticate in your favourite client library language in our client library guide or the more generic OAuth 2.0 documentation.

How do I stop my users from having to authorize my application every time they use it?

If you don’t take steps to store your users’ authentication data or set the appropriate flags on your request, the authentication process will run them through a permission-granting dialog similar to the one below every time:

In order to avoid this and improve the experience for users of your web or installed application, you should store their authentication data.

There are two types of token that we need to know about here: access tokens and refresh tokens. Access tokens give you immediate access to a user’s data, and are short-lived, whereas refresh tokens are long-lived, allowing you to generate new access tokens when you need them, even if the user isn’t present.

For installed or web applications we recommend storing both, and using the refresh token to generate a new access token whenever the one you stored expires.

For client-side applications, things should be a little easier, as all it should take is a redirect. The OAuth 2.0 documentation for client-side applications has all the information you need.

For more information on request tokens, you can check the relevant section in the OAuth 2.0 documentation, or the “Persisting authentication data” section in our client library guide if you’re using one of the client libraries.

How often can I run my report queries?

Every application has different needs, so the answer to this question will no doubt depend on what you’re doing. There are, however, a few guidelines we can give you.

First of all, try to collect data on the same frequency that you analyze it. That is, if you’re interested in daily performance, there’s no need for you to collect data more often than once a day, as our reporting can compile that data for you.

On the other hand, if you’re trying to get data as frequently as possible, bear in mind that we cache our report data for 60 seconds. There’s thus no point in running the same report more often than once a minute; the data you get won’t be any fresher, and you’ll just be wasting your request quota.

How do I get my performance data per country / domain?

Most reports are based on a time dimension such as DATE, WEEK or MONTH, which is to say that they’re grouped by that particular dimension.

Not all reports need to be based on a time dimension, however. In fact, a very useful report for those of you with many international visitors is to get a breakdown of visitors per country. In order to get that, just set your start and end dates and choose COUNTRY_CODE or COUNTRY_NAME as the dimension.

You can combine both approaches as well, to get a breakdown per country for every month, for example.

To get some more background on reports and the concepts behind them, check out our Diving into Reports blog post.

What should I do if my question isn’t answered here?

We’ve got a whole bunch of resources for you, from the reference documentation to our client library guide and code examples for several programming languages.

If that doesn’t help, take a look in our forum, and you might find a similar question or get a chance to post your own. You can also join us in a Hangout during our regular office hours. We’ll be around to give you a hand in either case!

- Sérgio Gomes, AdSense API Team

Effect of Configuring a New Ad Network to an Existing AdWhirl Application

2012-03-01T16:00:00.000-08:00

We’ve received questions asking us what happens new ad networks are added to an existing AdWhirl application. In this post we’ll explain how older versions of your apps will handle a new ad network configuration.

Say you published an application using AdWhirl, configured to use two ad networks. Now it’s time to release the next version, and you’d like to add a third ad network while you’re at it. But how will that affect the ad network request distribution for users running an older version of your application, which doesn’t have the new ad network SDK bundled? Older versions will request the updated configuration for both iOS and Android, but the two SDKs will process the configuration differently.

How the iOS SDK Distributes Ad Network Requests

When the iOS SDK parses the new configuration, it will only consider an ad network valid if it meets certain conditions, including having the corresponding network adapter. If the adapter doesn’t exist, then that network will be ignored. Your ad network percentages will then be normalized based on the total valid percentage of allocations.

Let’s demonstrate this with the above example. Say your original app had two ad networks, Network 1 and Network 2; now you’re adding Network 3 to the next version of your app. If your new ad network configuration sends 30% of requests to Network 1, 10% to Network 2, and 60% to Network 3, users running an app version without Network 3 will send 75% of the total ad requests to Network 1 and 25% of requests to Network 2. Backfill priority will be the same as specified on the server, but it will not include network 3.

How the Android SDK Distributes Ad Network Requests

When the Android SDK parses the new configuration, it will blindly add all networks as valid choices. When it tries to make a request to an ad network whose SDK is not available, the request will fail gracefully. However, AdWhirl will then rollover to your backfill priority. What does this mean for the ad network percentage distribution?

Using the same example configuration, the 60% of requests to Network 3 will fail for users with an older version, and AdWhirl will rollover to your top backfill option. If your top backfill option is Network 2, then Network 2 will consume the Network 3 traffic - you will have 30% of all requests going to Network 1, and 70% to Network 2. This is likely not what you would expect, so be careful when adding new networks to an existing Android application.

In summary, the iOS SDK will respect the percentages given to the valid ad networks (expected), but the Android SDK will send the invalid ad network traffic to the top backfill option (unexpected).

We value your feedback, so please post to our developer forum if you have any questions about AdWhirl.

- Eric Leichtenschlag, AdMob Team

Streamline your coding with AdWords API examples

2012-02-24T12:19:00.000-08:00

Are you getting started with the AdWords API but short on time to read the documentation? Do you need a reference implementation of a particular API operation? Check out our client libraries code examples which have undergone extensive renovations in the last libraries release!

The code examples are one of the best resources to learn the API and understand version changes. It is also helpful to have a working code to troubleshoot issues you may have with your own implementation. You can find the list of the client libraries and the resources for each library on the AdWords API site.

There were a number of changes introduced which we hope will make the examples code base more useful and easy to follow:

The code examples are now oriented around typical use cases rather than the API-specific operations. To get Criteria report look for the getCriteriaReport example, to create text ads - for the createTextAds example.
The number of input parameters was reduced which means you can run more examples as-is now, without adding specific object IDs.
For each example the code is wrapped into a function which can be called with parameters. This makes it easier to find out what parameters are required and improves examples testability.
Some of our Best Practices are now also demonstrated in the examples and described in the comments.

We’ve also changed the example files layout. We’ve noticed developers find it easier to navigate defined sections:

BasicOperations: start here if you are new to the AdWords API. This directory contains examples of basic operations such as creation, updating and deletion of most commonly used objects. The examples demonstrate the principles used in the rest of the API: selectors, predicates, paging, grouping of operations.
Targeting, CampaignManagement: these sections contain more advanced examples on the AdWords API such as geo targeting, location extensions, experiments and ad parameters.
ErrorHandling: examples in the ErrorHandling directory demonstrate how to handle different kind of errors occurring during the API calls. The errors covered here are API-specific (e.g. not network errors) and not transient so they could not be solved by retrying the exact same request.
Reporting: this section includes examples on how to retrieve a report with the client libraries. You can find the list of reports and their fields available on our codesite page.
AccountManagement: examples in the AccountManagement section will be helpful if you manage more than one account via the API. Here you can find code which retrieves accounts’ hierarchy or finds units spent on particular account.
Optimization: If you are looking for keyword or placement ideas or traffic estimations, you can find the examples in this section.
Remarketing: conversion tracker and audience operations are shown in examples in the Remarketing section.
Misc: this section contains examples that don’t fit into any other category and also some library-specific code samples. Check out our OAuth authorization code example here.

Browse updated examples code in: DotNet, Python, Ruby, Perl, PHP. We are working to update examples for Java and JavaScript as well.

As always, please feel free to ask any questions regarding the AdWords API on our forum or during scheduled office hours.

- Danial Klimkin, AdWords API Team

Discover DFP API v201201: PQL Report Filtering

2012-02-24T11:20:00.000-08:00

In the v201201 version of the API, we’ve added the ability to perform PQL filtering in reports. As an example of what you can do with this feature, you can now limit the report to only orders and line items you want to see. This will help shorten the report job processing time and reduces the size of the report generated. The following Java code snippet creates a report job to pull all the line items belonging to an order in your network:

Long orderId = Long.parseLong("INSERT_ORDER_ID_HERE");
// Create statement to filter for an order.
Statement filterStatement = new StatementBuilder(
    "WHERE ORDER_ID = :id").putValue("id", orderId).toStatement();

// Create report job.
ReportJob reportJob = new ReportJob();

// Create report query.
ReportQuery reportQuery = new ReportQuery();
reportQuery.setStatement(filterStatement);
reportQuery.setDateRangeType(DateRangeType.LAST_MONTH);
reportQuery.setDimensions(new Dimension[] {Dimension.LINE_ITEM});
reportQuery.setDimensionAttributes(new DimensionAttribute[] {
DimensionAttribute.ORDER_TRAFFICKER});
reportQuery.setColumns(
    new Column[] {Column.AD_SERVER_IMPRESSIONS, Column.AD_SERVER_REVENUE});
reportJob.setReportQuery(reportQuery);

The ‘ORDER_ID’ field in the WHERE clause is a dimension enumeration name. A full breakdown of the supported filter enumerations can be found in the documentation. We encourage the use of bind variables to build reusable filter statements, much like other services in the API where PQL is used. Whenever possible, try to filter on IDs rather than names (i.e. use CITY_CRITERIA_ID over CITY_NAME) since matching by name is case sensitive.

If you also specify the dateRangeType and dimensionFilters fields on the ReportQuery object, the filter statement will be applied in conjunction (in a logical AND) so that each entry in the report will match all of the filter criteria. You can check out a full working example in Java or language equivalent in our client libraries.

This is the first post in the Discover DFP API in v201201 series; our next post will cover syncing objects with the new lastModifiedDateTime field. Leave us a comment on the forum with any feedback you have for the API or topics you would like to see in the discover series.

- Jeffrey Sham, DFP API Team

Upcoming changes to the Ad Exchange RTB Protocol

2012-02-23T10:59:00.000-08:00

In April 2012, we will be making two changes to the allowed_vendor_type field of the Ad Exchange real-time bidding protocol. Before describing the upcoming changes, let’s review how to use technology vendors on the exchange.

Ad Exchange vendor policies

One of the benefits of buying on the DoubleClick Ad Exchange is the ability to use technology vendors for ad serving, research, remarketing and more. To protect Ad Exchange publishers, we certify vendors before they’re allowed to run on the exchange. And once they’re certified, we divide them into two categories, outlined in our Help Center:

No Declaration Required: Vendors that are whitelisted to run across the exchange, and therefore do not need to be declared in a bid response.

Declaration Required: Vendors that publishers are permitted to block, and therefore must be declared in a bid response.

Google Display Network

GDN Allowed: Vendors that are permitted to run on the Google Display Network. Note that categories 1 and 2 still apply to this subset; that is, some GDN Allowed vendors require declaration, and others don’t.

GDN Allowed vendors are listed in the GDN Requirements for 3rd Party Ad Serving. On this page, navigate to Vendors list (global) under the Requirements on the Google Display Network through the DoubleClick Ad Exchange section. Vendors marked with a + sign are bucket 2, Declaration Required.

An overview of the changes

In April 2012, we will make two simplifications to the allowed_vendor_type field of the Ad Exchange real-time bidding protocol.

Removal of No Declaration Required vendors: In the bid request, the allowed_vendor_type field will only contain vendors from category 2, Declaration Required; you will no longer see any bid requests with vendors from category 1. Accordingly, your bid responses should only contain vendors from category 2 (though your response will not be rejected if it contains a category 1 vendor). We have updated our vendors.txt file to include only the vendors that need to be declared.

Removal of allowed_vendor_type for GDN requests: Because every GDN site has the same set of allowed vendors, we will no longer include allowed vendors in bid requests for GDN sites (denoted by seller_network: “GCN”, soon to be updated to “GDN”). However, if the vendor you’re using falls into the Declaration Required bucket, you must still include it in your bid response. We have listed these vendors - those that are allowed on the GDN, and won’t appear in bid requests, but still require declaration - in gdn-vendors.txt.

As always, please reach out to your Google account team with any questions about this change.

Posted by Eileen Duffy, Ad Exchange Trainer

AdWords API v201109 migration deadline is next week. Make the move today to avoid errors

2012-02-22T11:49:00.000-08:00

We would like to once again remind you that after February 29, 2012, calls made using the following AdWords API versions will return errors:

AdWords API versions v13, v200909, v201003, v201008, v201101

We strongly encourage you to make the move to v201109 before the February 29th deadline. This will give you the opportunity to identify any issues before it is too late to roll back to previous versions.

In addition, check that you have no automated or scheduled scripts running that are using old code.

To ensure that your code uses only v201109, be sure you are using the latest version of our client libraries.

If you have specific migration questions, you can asking them in upcoming office hours or on the forum. Additional migration resources are available here.

Posted by Katie Miller, AdWords API Team

Introducing DFA API v1.17

2012-02-21T11:42:00.000-08:00

The newest version of the DFA API is now available: v1.17. This release includes a variety of bug fixes, many of which resolve issues that you reported on our forum. It also pares down a few outdated and unused operations.

Bug Fix Highlights

Some of the bugs tackled in this release include:

Placement end date validation has been fixed. [Reported on our forum]
The activeFilter field of AdSearchCritera is no longer ignored. [Reported on our forum]
Attempting to save an incorrect DefaultAd now gives a more descriptive error message. [Reported on our forum]
The expectedUrl field of SpotlightActivity is now required. Passing in a null value used to result in a default URL of "http://". It now results in an invalid URL error.

Deprecation and Sunset of v1.15

With this new release, our friend v1.15--the version from two releases ago--is now deprecated. As previously announced, we will continue to support it until March 3rd, 2012 at which time it will be entirely removed from service. Be sure to migrate any applications currently using v1.15 to one of the two supported versions by this time. Come benefit from the v1.17 fixes!

Sunset of v1.16 in Early June

Keeping with our standard release cycle, v1.16 will be sunset in early June. Please use this time window to make arrangements for migrating any v1.16 implementations before it is retired.

Complete Release Notes

This post reflects just some of the changes in the release. Our updated release notes page gives you a more in-depth breakdown of what has changed since the previous version. Please refer to this page when upgrading your applications.

As always, we highly value your feedback and questions. Please join us on our forum whenever you’d like to reach us.

- Joseph DiLallo, DFA API Team

Demographic performance report deprecation

2012-02-17T15:01:00.000-08:00

Demographic reports allow you to see the performance of your ads by age groups and gender on the specific sites in the Display Network that provide this information. As part of a greater effort to simplify AdWords, the DEMOGRAPHIC_PERFORMANCE_REPORT is being deprecated and will no longer be available in the API starting on or around March 21, 2012. You can back up the historical demographic data for your campaigns by downloading these reports before they sunset.

Please be aware that this change doesn’t impact demographic exclusions for your campaigns, which are done via the AgeRange and Gender criteria in the CampaignCriterionService. If you have additional questions about this deprecation, please reach out to us on the AdWords API forum or one of our regular Google+ Hangout office hours.

- Eric Koleda, AdWords API Team

Migrate to AdWords API v201109 in the next 2 weeks to avoid application interruption

2012-02-16T10:00:00.000-08:00

This is a reminder that after February 29, 2012, calls made using the following AdWords API versions will return errors:

AdWords API versions v13, v200909, v201003, v201008, v201101

If you would like your applications to run without interruption, you must migrate to AdWords API v201109 by February 29th. Migration resources are available here. In addition, if you have specific questions, we encourage you to attend office hours or post questions to the forum.

Posted by Katie Miller, AdWords API Team

Welcoming the Ad Exchange developer community

2012-02-16T07:56:00.002-08:00

The DoubleClick Ad Exchange launched five years ago (logging its first impression in June 2007), and it didn’t take long for the product to open up to developers. In 2008, we launched a real-time bidding (RTB) protocol, enabling sophisticated buyers to analyze and bid for impressions in real time. As the Ad Exchange and RTB grew, so did our pool of developers.

Presently, close to 75 percent of all Ad Exchange spend comes via RTB. Some of our largest buyers are agency trading desks and demand-side platforms that were created around the RTB opportunity. Simply put, Ad Exchange thrives thanks to the work of our developer community.

Today, we officially welcome Ad Exchange developers to the Google Ads Developer Blog. We’ll be using the blog to update Ad Exchange developers on news, best practices, and beta features. We’ll also highlight upcoming events like webinars, Google+ Hangouts, and on-site Developer Day workshops.

The Ad Exchange team is excited to engage more with our developer community. To subscribe to Ad Exchange news, click on our ad_exchange feed.

Posted by Ad Exchange Team

Chart tuning: user interactivity

2012-02-16T03:02:00.000-08:00

Welcome back to Chart Tuning! In this second half of the series we will show you how to define the different views for our chart and implement the zooming functionalities.

Before diving into the code explanation, check out the live example and the source code of the example chart if you haven’t yet.

Defining week and month view

Now that all our data is in place, we can get the visualization started. First we create a ChartWrapper by calling getChartWrapper. After setting the data table for our chart, we set the visualization mode to month and we can draw the chart.

The function setMonthView shows:

how to set the view window of the chart so that the values on the X axis (the dates) goes from 0 to the last day of the current month

how to add the required text to points on the X axis

how to visualize the subset of columns that we want in the month view.

The function setWeekView shows how to set the view window so that we show seven points centered on the user’s selection and how to visualize all the columns, as per requirement of the week view.

Handling events

Google charts can fire events for which you can listen. Events can be triggered by user actions: for example a user clicks on a chart. This comes in handy for our zooming functionality, as we need to intercept a user clicking a column in the chart.

To listen for these clicks, we add an event listener on the chart, and call the setWeekView function when the select event occurs.

Job done!

And that’s it, our chart is ready!

Have you noticed the graceful transition of the chart when using the zoom functionality? Transition animations are one of the latest additions to the Google Chart Tools, and you can experiment with different transition behaviors to properly tune your chart!

Some more thoughts on the User Experience

The zooming effect is nice to see, and when we’re in week view, we can use it to scroll the chart without changing a single line of code: if we click on one of the columns, the view centers on the selected point.

Thinking about the user experience, we have to consider that it might not be clear for our user that the zooming effect is activated when clicking on one column, or that they can still scroll the chart by clicking the other columns.

We can provide a better user experience by adding a button to toggle between week and month view; when in week view, we can add two arrow buttons to allow the user to scroll to the previous or the following week.

Why don’t you try to modify the source code to implement this feature request? We will add our solutions to the example chart source code on February 21, and then discuss possible solutions and other improvement ideas during the AdSense Management API Office Hours scheduled for that day.

For any questions or suggestions, don’t hesitate to engage with us in our forums:

Update: our solution has been added to the AdSense API showcase project.

- Silvano Luciani, AdSense API Team

Ship with the latest AdMob SDK every quarter

2012-02-15T10:00:00.000-08:00

You asked for an AdMob SDK release schedule to time your own app releases, and we listened. From here onwards, AdMob will ship an Android and iOS SDK release in the first two weeks of January, April, July and October.

We are excited about adding clarity and predictability to your development cycles, while bringing you powerful features that accelerate your business with each SDK release.

AdMob SDK v6.0 ships in April. Stay tuned!

- Ayush Agarwal, Product Manager, AdMob

Chart tuning: advanced data visualization

2012-02-15T03:11:00.000-08:00

During Chart Tools Week, we showed you how to create a basic dashboard for AdSense reporting using the AdSense Management API and Google Chart Tools.

In this new two-part series, we’ll examine more advanced charting techniques that will improve the look and feel of our chart as well as enable user interactivity.

We’ll also show you how to use the Google Closure Library to ease some of the data manipulation tasks when writing a JavaScript application.

The goal

Our goal is to produce this Column Chart showing the earnings per day for the current month. We also want a zoom feature, with the following requirements:

The chart is initially shown in a month view: standard columns are shown for the days of the current month up to the current day. For the current and future days we draw the columns with a different visualization style, to visually outline the uncertainty of the data measurement. On the X axis we show 4 or 5 titles, for day 1, 8, 15, 22 and 29 (except for non leap year February). The title is the day of the month.

By clicking one of the columns, the user can zoom the chart to a week view. In the week view we show the values over the week centered on the day selected by the user: 7 columns are visualized, and for each data point we show the title on the X axis. We also add two other columns to the data visualization in order to supply more detailed information:
- page views RPM
- ad requests RPM

Finally, we add to the visualization a Zoom Out button to allow the user to go back to the month view. The Zoom Out button will disappear when the user zooms all the way out.

Dive with us into the source code of our example chart to see how easy this task can be! You can find instructions on how to setup the example project to use Closure in the README file.

Getting to the goal: fetching the data

After the Google API JavaScript client has loaded, the OAuth 2.0 flow completes, and the user logs in, makeApiCall is called to start the generation of the chart.

The first thing we do in makeApiCall is fetch our data from the AdSense Management API. We want DATE to be the dimension for our report, and EARNINGS, PAGE_VIEWS_RPM and AD_REQUEST_RPM as our metrics. To determine start date and end date, we can use the Google Closure Library as shown in the getRequestParams function. After that we are ready to send our request.

Formatting the data: using roles

Once we have the data, the next step is to format it into a DataTable that will be consumed by our chart. The addTableHeaders function shows how to add the columns that we need for our chart. Two column declarations might catch your attention:

dt.addColumn({'type': 'string', role: 'tooltip'});
dt.addColumn({'type': 'boolean', role:'certainty'});

For these columns we are using DataTable Roles, an experimental feature of the Google Chart Tools that can be used to describe the purpose of the data in a column. Using the tooltip role we can edit the text to display when the user hovers over data points. Using the certainty role we can indicate whether a data point is certain or not, and have the column visualized in a different way accordingly.

Formatting the data: the content

After defining the columns, we can add rows of data to our DataTable. To do this, we need to keep the following into account:

The AdSense Management API will return a result for a day only if there is a nonzero value for that day. In other words, if one day we had zero views, the API will not return a result for that day. This also means that we will not get results for days in the future.

We want to make the certainty of a data point visible, so that we have a different visualization for measures that are certain and measures that are in progress or not started.

For the first point, we need to iterate through the values returned from the API. If a DATE is not present in the response, we add a row with value zero for all the metrics for that DATE to the table. To satisfy the second point, we need to check if the current day of the iteration is the current day of the month or a day in the future. If it is in the future, we need to flag the row as uncertain.

Remember that the rows part of the API response will be an array similar to:

"rows": [
  ["2012-01-03", "28", "46", "41"],
  ...
  ["2011-11-07", "2", "3", "3"]
]

The function addTableRows implements the data manipulation algorithm, using Closure to help out with dates formatting and days iteration.

The function formatRow shows how to create rows for our DataTable and add data for our tooltip and certainty columns. In the example, we have built the tooltips to show the full name of the day of the week for each data point, to help the user to better contextualize the value.

Enough for today!

At the end of day one, we have all the data ready to be visualized. Tomorrow we’ll see more on how to define our week and month views and implement the zooming functionalities.

In the meantime, don’t hesitate to ask your questions, leave your suggestions, and engage with us in our forums:

- Silvano Luciani, AdSense API Team

Retiring support for v201103, v201104, and v201107 of the DFP API

2012-02-10T12:30:00.000-08:00

Today, we are announcing the deprecation of versions v201103, v201104, and v201107 of the DFP API. In 3 months, on May 11th, these versions will be turned off. We are turning off older versions to make sure that everyone can benefit from the improvements in more recent releases and so that we can focus on releasing new features.

As mentioned in previous deprecation announcements, we will always give at least 3 months notice before turning off a version. Our release notes page also contains changelogs for each version, which will help you migrate to a newer version. If you aren’t using one of our client libraries, now would be a great time to start as well. If you have any feedback or comments about this deprecation, or the API in general, please feel free to leave them on our forum or join us in a future hangout on Feb 28th.

- Adam Rogal, DFP API Team

isocket and Shiny Ads deliver new innovations using the DFP API

2012-02-07T10:00:00.000-08:00

Editor’s note: We’d like to share with you this post from John Park about the growing DFP API ecosystem and a few success stories from our partner directory. -- Adam Rogal, Ads Developer Relations Team

With thousands of publishers using the DFP and DFP Small Business ad serving platforms, we know first-hand that no two publishers are identical. Publishers may use in-house billing systems, have unique approval workflows, or use third-party tools to handle their ad operations.

To give publishers the flexibility to easily integrate their unique processes and systems with their ad server, DFP offers publishers an open API to easily create tools that complement their ad operations.

We’ve seen hundreds of developers build new ad serving innovations using the API, including applications to manage inventory, create orders, pull reports, and more. The API has created a new ecosystem of partner innovations, giving publishers access to new ad serving tools and applications. Two such applications come from isocket and Shiny Ads who have used the DFP API to build applications that help publishers manage and sell their ad space.

isocket uses the API to create tools that streamlines sales

Seeing the need to streamline the manual steps involved with buying and selling inventory, isocket engineered a direct and self-service ad sales tool to simplify sales workflows. By leveraging the DFP API, isocket was able to build an application to automate sales processes and save money. “We were interested in using the API because it allowed us to eliminate the hassle of manually coordinating campaigns, while still keeping the important parts like publisher control and approval. Integrating with the DFP API has allowed us to make things a lot simpler for publishers,” said Ben Trenda, VP of Sales at isocket.

Read more about how isocket integrated with the DFP API.

Shiny Ads builds application to help publishers save time

To help facilitate publishers’ direct ad campaign management, Shiny Ads began using
the DFP API to integrate its self-serve advertising platform with DFP in order to help publishers streamline their sales processes. This integration has helped save publishers time since they no longer need to manually book sales orders. “Our solution needs to support DFP - our customers demand it” said CEO and founder Roy Pereira. “The API made integrating with DFP easy for us, and most importantly, easy for our clients. Without the DFP API, Shiny Ads would not have the fully functional solution we have today.”

Read more about how Shiny Ads integrated with the DFP API.

Over the coming months, we’ll share more stories on how our partners are using the DFP API to deliver exciting ad serving innovations. For a complete list of partners who have built applications using the DFP API, please visit our partner directory.

Posted by John Park, Partner Programs Manager, and Adam Rogal, Developer Relations

Announcing v201201 of the DFP API

2012-02-06T15:00:00.000-08:00

The newest version of the API, v201201, brings some frequently requested features including using date time strings in PQL statements, filtering objects based on last modified date and times, including a PQL statement to limit a report (such as just running a report for one order), and more. A full list of features can be found on our release notes page.

Filtering

In v201201, we’ve focused on improving filtering with PQL statements across the entire API. We’ve introduced a better way to do date time filtering, a new lastModifiedDateTime field to search on, and the ability to filter from within a report.

With the ability to filter by date and time fields directly in the PQL statement, you’ll now be able to limit the objects on the server, rather than fetch all line items and checking their startDateTime property one at a time. For example, if you want to retrieve all line items that started so far in January, include

startDateTime

as a predicate of your filter with a date and time string, e.g.

WHERE startDateTime >= ‘2012-01-01T00:00:00’

. Note here that the date and time are in ISO 8061 format, i.e.

YYYY-MM-DDThh:mm:ss

, and the time zone is assumed to be that of the network’s. You can also bind a DateTime object instead of using a string, i.e.

WHERE startDateTime > :dateTime

, where

:dateTime

is bound to a DateTimeValue.

We’ve also added the new lastModifiedDateTime field to companies, creatives, ad units, line item creative associations, line items, orders, and placements. Using this field, you can now query for objects that have changed recently. Combined with the new date and time filtering feature mentioned above, you will be able to pull all objects changed so far this year, e.g.

WHERE lastModifiedDateTime >= ‘2012-01-01T00:00:00’

. If you are a developing an application that has to keep in sync with changes made through the UI, only pulling down objects that have changed since your last fetch time will speed up your calls and decrease processing time.

Finally, one of the largest requests from our developers was to limit what data is returned from within a report. We’ve add the ability to define a PQL statement in a report definition to do just that. Now when you create a report, you’ll be able to supply statements to limit it to just one order, e.g.

WHERE orderId = :orderId

, or with only one salesperson as well, e.g.

WHERE orderId = :orderId AND salespersonId = :salespersonId

.

Creatives

In v201102, we’ve added three new creative types that are only available to small business networks:

FlashExpandableCreative - an expandable creative where the collapsed size is a Flash SWF file and the expanded size is another Flash SWF file.
FlashPushdownCreative - a creative that pushes page content down when the creative expands.
TextAdCreative - a text-based creative.

Teams

We’ve introduced a new service with this version, TeamService, which lets you group users into teams. Although currently not editable via the API, teams will be used to limit access to entities such as companies, inventory, and orders.

Coming soon

Over the next few weeks, you’ll learn about all of the features a bit more in the Discover v201201 series starting first with a discussion of filtering and syncing best practices. Let us know if you want to see anything else on our forum.

- Adam Rogal, DFP API Team

AdWords API: Retrieving large result sets

2012-02-01T06:31:00.000-08:00

When you need to retrieve a large set of objects, such as a list of criteria for an account, it’s tempting to use one simple query with a paging parameter to pull the data from the server page-by-page.

While this approach is acceptable for most queries, it has some limitations:

The AdWords API does not allow you to retrieve data whose start index is past 50000
Unit cost for the request will depend on the number of pages and will be relatively expensive
A parallel update request may interfere with the process
Error handling and retry logic could be complex

We recommend using one of the following approaches instead:

Use AdHoc reporting to obtain data. With reports, you can still retrieve most fields available through SOAP requests, with the added bonus of AdHoc reporting being faster and free of unit costs.
Try to narrow the query as much as possible with predicates. Group queries by Campaign and AdGroup to retrieve only required data and to fit all results into one response.

Also, you can save bandwidth and retrieve large results faster by enabling transparent gzip compression. Check out our best practices page for more details on this feature and other recommendations.

As always, please feel free to ask any questions regarding the AdWords API on our forum or during scheduled office hours.

- Danial Klimkin, AdWords API Team

30 days left to migrate to AdWords API v201109

2012-01-30T09:43:00.000-08:00

On February 29, 2012, we will be sunsetting the following versions and services:

AdWords API versions v13, v200909, v201003, v201008, v201101

AdWords API version v13 AccountService will only be available on a whitelist basis.

Calls made using these versions will return errors after February 29th. It is therefore critical that you migrate to AdWords API v201109 if you would like your applications to run without interruption.

We encourage you to use the following resources for a successful migration:

Review the resources in the AdWords API client libraries.

Review the “Discover v201109” blog series.

Subscribe to the AdWords API Twitter account, which will share daily migration tips for the next month

Make sure you’ve completed everything on this migration checklist.

Give yourself ample time to migrate from v13 to AdHoc reporting. Resources to help with this migration are available here.

Attend office hours.

Make sure your contact information is up to date in your My Client Center account.

Post questions on the forum.

Posted by Katie Miller, AdWords API Team

Announcing AdCatalog v1 for iOS

2012-01-27T16:36:00.000-08:00

We’re very pleased to announce the release of AdCatalog v1 for the iOS platform. AdCatalog is a sample project that demonstrates how to incorporate banner and interstitial ad units into your application. In particular, AdCatalog showcases implementations for two standard banner ad sizes—320x50 and 300x250—and several use cases for interstitial ad units: basic, app launch splash screen, in-between game levels, and before playing a stored video.

AdCatalog can be downloaded as a zip from our google-mobile-dev project. Additionally, feel free to clone the repository or examine the source from the checkout page. In version 2, we’ll be looking to add even more advanced layout options to our banner scenario, so be sure to stay tuned. As usual, if you have any questions, comments, concerns, or feature requests, we appreciate hearing the feedback on our developer forum.

- Wes Goodman, AdMob Team

Prepare for the sunset with the AdWords API v201109 migration checklist

2012-01-27T09:49:00.000-08:00

As announced in October, we will sunsetting all versions of the AdWords API prior to v201109 on February 29, 2012. To help you prepare to migrate to v201109, we've created a checklist that covers all of the required changes:

Required Changes:

Migrate all API calls to use v201109 services
Migrate all API calls to use clientCustomerId (instead of clientEmail) to identify an account as the target of an operation (Blog post)
Migrate campaign geo target creation and identification to use the new location criterion object (available through the CampaignCriterionService and the LocationCriterionService)
Migrate all other campaign targets (except ad scheduling) from the CampaignTargetService to CampaignCriterionService using the appropriate criterion objects defined within that service*
Migrate cross client reporting to v201109 AdHoc (single account) reports (Blog post)
Provide developerToken as HTTP header in AdHoc report requests
The last few API releases have seen various services migrate to generic selectors, as you update to v201109 you’ll need to migrate from service specific selectors to generic selectors as required. See the Selector Migration Reference for details
Update to the very latest version of the AdWords API client library specific to the programming language(s) that you use for API tool/platform development**
If you generate your own client side stubs from the API Service WSDLs, make sure that your requests strictly adhere to the WSDL definition as we have implemented stricter validation for the SOAP header and envelope (Blog post)

Optional Changes:

You can now use the v201109 CreateAccountService to create AdWords optional-login accounts

Note: If you do not make the required changes, calls made using versions of the AdWords API prior to v201109 will return errors after February 29th 2012

Additional Notes:
*In v201109, most targets become criteria, with each having it’s own ‘type’ of criterion object (see this Blog post for more details)
**This is an important requirement, so do make sure to check the version of the library or libraries that you are using against those available here

- Mandy Waite, AdWords API Team

Getting Started With the PHP Client Library

2012-01-26T11:00:00.000-08:00

Recently, we released our first client library walkthrough video for the DoubleClick for Publishers API. This five-minute video guide shows you how to get up and running with the PHP client library from downloading the code to running one of the examples. All you need to get started is a DFP account (production or sandbox) and a machine with PHP 5.2.x and the SoapClient, OpenSSL, and cURL extensions. For new users to the API, it’s a great way to get acquainted with the documentation pages, project site, and client library features.

The video takes you through an explanation of how the getCreativesByStatement example makes an API call and highlights common usage patterns and best practices for the client library. We also show you what happens when a call returns an error and how you can configure logging to get more information and troubleshoot an issue.

Please let us know about any topics you would like us to cover in a video guide or blog by leaving a comment on our forum. You can also chat with us live at one of our DFP API Office Hours Hangouts.

- Jeffrey Sham, DFP API Team

AdWords SOAP Header validation is being enabled

2012-01-25T11:30:00.000-08:00

Starting with v201109, we enabled stricter validation of the SOAP Body, meaning that XML that did not closely follow the XML Schema defined in the WSDL would be rejected with a SOAP fault. This stricter validation enables developers to detect flaws in their applications, such as sending an unsupported field, at development time rather than later discovering that field was ignored.

In the coming weeks, we will also be enabling stricter validation of the SOAP Headers. Currently, SOAP Headers that don’t validate against the XML Schema are ignored. This includes headers such as clientEmail/applicationToken (both of which do not apply to v201109) or partialFailure, which is case sensitive (will not accept “TRUE” or “True”, only “true”). When clientEmail is ignored, the request will target the authenticating account (often an MCC), which will, for example, return an error message if you attempt to add a Campaign or no results if you make a GET request.

The stricter validation will trigger a SOAP fault for any SOAP Headers that do not match the XML Schema defined in the WSDL. This may cause your application to see more errors such as those referenced in our previous blog post. This validation will enable developers to better detect bugs in their application that were previously silently ignored.

If you have any questions, please post on the forum or attend one of the AdWords API Office Hours Hangouts.

- Kevin Winter, AdWords API Team