Google Ads Developer Blog: November 2012

Optimization Series: Post-Filtered Bids

Thursday, November 29, 2012

Today we’re launching the Ad Exchange Real-Time Bidding Optimization Series on the developer's blog to share updates, best practices and optimization tips with AdX developers. Our goal is to provide knowledge to our clients to help keep their proprietary bidders healthy, successful and evolving. To start things off the first blog post in the series covers post-filtered bids.

When using Ad Exchange, one of the most important factors is ensuring that your bid response is participating in the auction. If the bid response makes it to the auction, it has a better chance at improving win rate: percent of impressions won out of all bids submitted. However, it’s possible that some of your bids may not be entering the auction due to bid response filtering.

We’ll review bid response filters later in this blog entry: what they are, and how to ensure your bid responses are not filtered out. But before we dive in, let’s define bid response filtering.

What is bid response filtering?
Each real-time bid that is submitted to Ad Exchange undergoes a screening process before it can enter the live auction. During this process, your bid may be filtered due to publisher exclusions or incorrect use of the RTB BidResponse protocol. Among other things, we check for malformed URLs, ads that fall into a category the publisher has blocked, or incompatible elements in the bid response (e.g., a buyer who has declared an expandable ads technology vendor, but who has not actually trafficked an expandable ad).

Here is a basic visual representation of the process a bid goes through, including bid response filtering, to make it into the auction and win:

What are the main bid response filters?
As the bid response progresses through the process illustrated above, it might be filtered out by Google, the publisher, or during the actual auction for many different reasons. Each of the main bid response filtering mechanisms are discussed in detail below.

Google Filtered: First, Google will review the bid response to determine if both the ad creative and bid are compliant with Google’s policies and standards. Here are the most common reasons your bid response will be filtered out by Google:

Disapproved ad means that the ad in the bid response was disapproved due to one of several reasons. In order to determine the exact reason for which your ad was disapproved, review your snippet status report. The snippet-status-report-proto.txt file lists all the issues described in the <DisapprovalReason> section of the report. This is usually the culprit when your bid has been filtered out!
Note: The snippet status report will also show ads that have not been checked and are filtered.
And as a proactive measure, the creative REST API provides methods for submitting a creative for verification, for checking the status of a creative that you have submitted, and for retrieving a list of all your active creatives before bidding on the creative ad.

Max CPM is 0 or negative means the bid (max_cpm_micros) set in the bid response was 0 or a negative value. Change the bid to a positive value. If you are not interested in bidding for a particular bid request, be sure to return an empty bid response with the processing time set, not just an empty (0 bytes) response.

Click through URL is too short means for bid responses where html_snippet is set, the click_through_url is less than eleven characters. For example, the URL http://a.b would be too short. Verify that your click_through_url is more than eleven characters.

Click through URL is unparsable means the click_through_url in the bid response is malformed and cannot be parsed. For example, 'http://myad' will not work, since the domain name has to include at least one '.' (period).

Incorrect use of bid response protocol means that there is an improper setting in the BidResponse. In order to determine the proper protocol, review Building the Response and the realtime-bidding.proto.txt file. The realtime-bidding.proto.txt file defines the appropriate settings that should be included in the BidResponse. Examples of incorrect protocol use include: buyer_creative_id not set in the BidResponse or setting both the html_snippet and video_url fields in the BidResponse (only one should be set).

Poor landing page quality means that the landing page was disapproved by Google. Review the landing page of the ad to make sure the website provides a good user experience as measured by:

Relevant and original content: The site needs to be relevant and have original content, it should not copy text from another site.
Transparency: The site needs to be very clear on what the business model is and what the information will be used for.
Ease of navigation: The site should be easy to navigate and it should not be intrusive to users.

Publisher Filtered: Once the bid makes it through Google’s review, it is reviewed again to ensure it adheres to the publisher’s requirements. For each piece of ad inventory, the publisher can add exclusions. Here is a list of the main reasons a bid could be filtered by a publisher:

Sensitive category URL excluded means that the click_through_url in your bid response was either detected or declared with a sensitive category which was excluded by the publisher for this request. In order to determine the sensitive categories for each publisher, you will need to review the excluded_sensitive_category field in the bid request and the publisher settings report. The publisher-settings-proto.txt file lists the categories that are excluded. Your snippet status report will show the sensitive category with which your snippet’s click_through_url was classified by Google.

Product category URL excluded means that the click_through_url in your bid response was either detected or declared with a product category that has been excluded by the publisher for this request. In order to determine the product categories prohibited by each publisher, review the excluded_product_category field in the bid request and the publisher settings report. The publisher-settings-proto.txt file lists the categories that are excluded. Your snippet status report will show the product category with which your snippet’s click_through_url was classified by Google.

Declared vendors excluded means the bid response has declared a vendor_type which has been excluded by the publisher’s ad slot in the bid request. In order to determine the vendor types allowed by each publisher, review the allowed_vendor_type field in the bid request and the publisher settings report. The publisher-settings-proto.txt file will show you the allowed vendors.

Declared attributes excluded means the bid response has declared attributes which were excluded by the publisher’s ad slot in the bid request. In order to determine the allowed_vendor_type per publisher, you will need to review the excluded_attribute field in the bid request and the publisher settings report. The publisher-settings-proto.txt file will list the excluded attributes.

Auction Filtered: After the bid response passes the Google and publisher reviews, it makes its way to the auction. However, the bid may not enter the auction if it was lower than the publisher’s required min CPM. If this is the case, a ‘Max CPM is lower than the publisher’s min CPM’ message will be generated.

Max CPM is lower than the publisher’s min CPM means the bid response contained a max_cpm_micros value that was less than the publisher’s min_cpm_micros setting. Ensure your bidder reviews the min_cpm_micros required by the publisher per bid request in order to bid properly on the impression. The min_cpm_micros value is listed in the AdSlot section of the bid request, you can review more details in the realtime-bidding-proto.txt file.

Remember, each bid response that is filtered out is a valuable impression you’ve missed out on. Therefore, always review the following:

Disapproved ads in the snippet status report
Excluded dimensions in the publisher settings report
Publisher’s min CPM requirement in the bid request

Have questions or want to get a report for your bid response filtering issues? Reach out to your Ad Exchange account team.

Posted by the Ad Exchange Team

Announcing v201211 of the DFP API

Thursday, November 29, 2012

Today, we are pleased to announce the launch of v201211 of the DFP API. The focus of this version is on enhancing our API so that you, as a developer, have more options available when encountering API issues. In particular, we’ve added a number of new objects that will help you avoid nondescript SERVER_ERRORs and help work with new features. We’ve also launched the new creative wrapper service and other smaller features, which can all be found on our release notes page.

Improved error handling

Starting today, we’re offering two new enhancements to the API that will make it easier to handle exceptions when calls don’t go as planned. The first addition is the UnsupportedCreative type. Previously, if you tried to fetch a new type of creative using an older version of the API, you might receive a SERVER_ERROR, a “fault occurred while processing” message, or a 502 HTTP error status code. Now, when the API detects that you are fetching a creative that wasn't defined when your API version was released, it will return the creative as an UnsupportedCreative. The returned creative will expose all the fields of the base type and what the unsupported creative type was. You can then search our release notes for announcements of any new creative types to determine which version you should upgrade to, or use the forum to let us know that you are waiting on a new creative type to be released in the next API version.

The second enhancement is the addition of a new enum choice, UNKNOWN, to all existing ApiError types. When you receive an ApiError with UNKNOWN, you’ll be able to log that exception separately (by examining the error in your try/catch blocks) and then let us know on the forum that you received this error so we can help you narrow down what the true cause was. In the future, we’ll be adding UNKNOWN to a few more enums so that if your API version can’t express the actual enum value, you’ll still be able to process as much as you can about the object without having a severe failure.

Note: Both UnsupportedCreative and the UNKNOWN enum choice have been added to all API versions, thus changing the WSDLs for all versions and services. A failed API call would most likely not give you any information; these new changes give you the option to regenerate your client code or download a new version of our client libraries (available soon) to receive the benefits of these changes on existing versions. In versions prior to v201211, unsupported creatives will be filtered instead of returned.

Deprecation reminder

As we mentioned in September, v201108, v201111, and v201201 have been deprecated and will be turned off on December 10th. If you have not upgraded to a newer version yet, now would be a great time to do so. We’ll be more than happy to help with any specific questions on our forum.

Upcoming DFP Google Developers Live (GDL) sessions

On December 5th, we’ll be hosting another GDL session. We’ll be interviewing a few DFP API developers about their integrations and if they have any tips for other developers.

If you haven’t yet, follow us on our Ads Developer Google+ page. We'll be publishing some great tips soon there and would love to hear your requests.

- Adam Rogal, DFP API Team

Shared Budgets FAQ

Friday, November 23, 2012

There’ve been many questions posted to the AdWords API forums regarding the new Shared Budgets feature that was introduced into the AdWords API in version v201209. To help, we’ve put together an FAQ which you can find here.

To aid migration, we've also re-introduced the v201206 behavior that allowed the mutating of budgets via the CampaignService. After v201209 this functionality will be removed.

If you can’t find the answer to your specific question, please post it on the forum or attend one of the AdWords API Office Hours Hangouts. You can also follow our Google+ page for updates about the AdWords API.

- Mandy Waite, AdWords API Team

Sunsetting the AdWords API Sandbox. Introducing Test Accounts

Friday, November 16, 2012

We know that you depend on having a free, easy-to-use and robust test environment to test AdWords API clients. We had created the AdWords API sandbox, but it differed enough from the production environment to affect your development and testing. We listened to your feedback of wanting the same versions, features and error messages as the production environment.

As a result, we are introducing test accounts on the production system in place of the AdWords API Sandbox.

The AdWords API Sandbox is now deprecated and will be sunset on Dec 15, 2012. We strongly encourage all developers to obtain a test account to continue testing.

AdWords API Test Accounts

Calls made using a test account will be free, so you can develop and debug your applications without spending API units.
There will be identical error handling for test and production accounts and hence less time spent troubleshooting bugs or working around differences between the two systems.
Test account campaign data has no effect on live campaigns, so you can test campaign management without affecting live campaign data and without serving ads to users.
Test accounts do require a developer token. However, an approved token is not a prerequisite to using a test account. So if you are a new developer, you can start experimenting with the AdWords API even while your token is being reviewed.

Getting Started with your Test Account

If you already have an AdWords API developer token, or have recently applied for one, you can obtain a test account, and start testing on the production system. You can find more details about how to get a test account on the AdWords API Developers site.

If you are a new developer and don't have a developer token yet, please apply for a token first. You don't need to wait for your developer token to be approved before using it with a test account.

Again, the AdWords API sandbox will be sunset on Dec 15, 2012. After this date, you will need a developer token, either approved or pending, to test your API clients.

So don't wait, go get your test account, and get on with developing great apps!

- The AdWords API Team

Create Your Own Version of loadAndDisplayRequest:usingWindow:initialImage:

Tuesday, November 6, 2012

Recently, we started cautioning publishers against using GADInterstitial’s loadAndDisplayRequest:usingWindow:initialImage: method with mediation. We saw some odd behavior occurring when publishers used that method. This blog post outlines a way to implement the functionality of this method while avoiding the problems that had been associated with it.The original method replaced the rootViewController of the window temporarily while the splash image was being shown. Since you have control of your view controllers as the publisher, this step is unnecessary. Assuming you want to show the splash image on app startup, you can place your interstitial code in your rootViewController’s viewDidLoad: method. This method is called after the view hierarchy is loaded into memory.On a high level, all you need to do is initialize a UIImageView and add it into your view hierarchy in the viewDidLoad: method. To be extra careful, you may also want to hide the status bar while your splash image is being shown.- (void)viewDidLoad { [super viewDidLoad]; interstitial_ = [[GADInterstitial alloc] init]; interstitial_.adUnitID = @"MY_INTERSTITIAL_ID"; interstitial_.delegate = self; // Remember whether the status bar was hidden or not. hideStatusBar_ = [UIApplication sharedApplication].statusBarHidden; [UIApplication sharedApplication].statusBarHidden = YES; GADRequest *request = [GADRequest request]; request.testing = YES; [interstitial_ loadRequest:request]; // Initialize your splash image and add it to the view. imageView_ = [[UIImageView alloc] initWithImage:[UIImage imageNamed:@"InitialImage"]]; [self.view addSubview:imageView_]; } If you only want to show the splash image and interstitial the first time the app is loaded, you can write a boolean into NSUserDefaults and check that boolean before you present the interstitial in viewDidLoad:.As a final step, you must remove the imageView_ from the view hierarchy once the interstitial comes in. Remember that you also need to remove it if the interstitial fails. To reduce code duplication, you can put this logic into it’s own method.- (void)restoreController { [imageView_ removeFromSuperview]; // Restore status bar to state it was before hiding. [UIApplication sharedApplication].statusBarHidden = hideStatusBar_; } #pragma mark GADInterstitialDelegate - (void)interstitialDidReceiveAd:(GADInterstitial *)ad { NSLog(@"Received ad successfully"); [interstitial_ presentFromRootViewController:self]; } - (void)interstitial:(GADInterstitial *)ad didFailToReceiveAdWithError:(GADRequestError *)error { NSLog(@"Failed to receive ad with error: %@", [error localizedFailureReason]); [self restoreController]; } - (void)interstitialWillDismissScreen:(GADInterstitial *)ad { // Remove the imageView_ once the interstitial is dismissed. [self restoreController]; } If you have any questions about the AdMob SDK, reach out to us on the forum or join us for our upcoming AdMob office hours. You can also follow us on the Google Ads Developer plus page.

- Raj Parameswaran, AdMob Developer Relations

DoubleClick Ad Exchange Buyer: Upcoming SSL Requirement

Monday, November 5, 2012

We value our partnership and want to notify you of an important upcoming change for third party ad serving (3PAS) to Google owned and operated properties, including YouTube.

To provide greater security and ensure the privacy for our users, all ads, whether display or in-stream video, that are served to signed-in Google users must be Secure Socket Layer (SSL) compliant no later than January 15, 2013. After this date, the amount of inventory available on Google properties to non-SSL compliant buyers will be limited.

KEY REQUIREMENTS

DoubleClick Ad Exchange (AdX) buyers must declare that a 3PAS ad is SSL-compliant via Real-Time Bidding (RTB) in the BidResponse or the AdX UI
All 4th-party calls to other technologies must be made from SSL-compliant vendors that have been certified by Google
All video companion banner ads must be SSL-compliant

Note that if an ad is declared as SSL-compliant but makes any non-SSL-compliant responses, the ad will be disapproved.

SUMMARY OF CHANGES
RTB Protocol
To identify inventory requiring an SSL-compliant response, the excluded_attribute field (BidRequest.AdSlot.excluded_attribute) will include the value 48, which represents the RichMediaAdsVendor: RichMediaCapabilityNonSSL creative attribute from the dictionary file creative-attributes.txt. If the creative attribute value 48 is not present in the excluded_attribute field, both SSL-compliant and non-SSL-compliant ads can be returned. You should use this field to ensure that your ad serving technology responds properly to bids. This field will be present in BidRequests for both display and in-stream video ads.

User Interface
For 3PAS ads, there will be an additional checkbox in the Ad Exchange UI to declare that an ad is capable of serving both SSL and non-SSL ads. This checkbox will be available soon for both display and in-stream video 3PAS ads and will be un-checked by default.

For non-3PAS ads, there are no changes in the UI.

In-Stream Video
In addition to the above changes, there are specific changes that must be made for In-Stream Video ads to be eligible for SSL inventory:

VAST: All VAST (Inline and Wrapper) URLS must serve over HTTPS when the ad request is made with HTTPS.
Media and tracking URLs: All tracking pixels and creative assets (including media files) must serve over HTTPS when the VAST URL is served over HTTPS.
Companion ads: All Companion banners, including any 4th-party calls, must serve over HTTPS when the VAST URL is served over HTTPS.

We understand that this change places additional burden on your team and we will do our best to help you through this process. In the interim, please do not hesitate to contact your Google technical account manager with any questions.

Posted by the Ad Exchange Team

Understanding AdWords API TargetingIdeaService and user interface numbers

Friday, November 2, 2012

Some API users have noticed a difference between the search volume numbers returned by the TargetingIdeaService in versions v201206 and later compared to earlier versions and the user interface.

When running a query of 'STATS' request type with the latest API version, you will typically get a higher number for search volume compared to the user interface. The reason for the difference is that the volume returned by the latest API includes Search Partners data in its calculation, while the UI and the older API versions don’t have this metric available.

We understand this change may have caused confusion for some customers and we plan to include an option to choose which networks to account for in future API versions.

- Danial Klimkin, Ads Developer Relations Team.

Ads Developer Blog