Direct Publisher Integration Guide
This wiki page describes how publishers and mobile operators retrieve banner ads via Millennial Media's (formely Jumptap) Publisher Ad Server. Millenial Media acquired Jumptap in November 2013 and now has two ad serving APIs. This document applies to pubishers that are integrated into the API previously owned by Jumptap (also refered to as tapLink or tapPub).
This document is intended for software engineers, system architects, product or project managers responsible for the implementation of Millennial Media (formely Jumptap) API for display ads.
Ad Request API
The Millennial Media (formely Jumptap) API allows mobile web publishers and application developers to request display ads via a server-side call mechanism. To request an ad, the publishing server makes a server-to-server invocation of the Millennial Media Ad Service via a REST-style web-interface. The resultant XHTML markup is then displayed in the end user's browser page or application.
Requesting an ad
Ad requests to tapLink must be made on a just-in-time basis; in other words, an ad should be requested as the page on which the ad will be displayed is being built. Millennial Media (formely Jumptap) API does not support pre-fetching of advertising for future display.
Ad requests to the Millennial Media (formely Jumptap) API comprise:
- A simple HTTP GET request of the form:
http://a.jumptap.com/a/ads?<required parameters><optional parameters>
- HTTP headers forwarded from the originating handset.
Structuring the GET Request
- Parameter/value pairs are separated from each other with the '&' character.
- The order of the parameter/value pairs in the query string is not important.
- All parameter values must be URL-encoded.
- It is not necessary to pass parameters for values that you are already sending as headers.
- For example, if you are sending the user-agent header from the device, you do not need to pass the ua parameter.
- You do not need to pass the same parameters with every request.
- For example, if postal code is only available on particular pages of your site, then the requests from those pages would include "&pc=&country=" whereas requests from other pages would not.
- Do not pass a null value or an empty string for parameters for which you do not have values. Instead, leave such parameters out of the query string altogether.
The template of an ad request containing all possible parameters is below. Note that this is not actually a valid request as it does not contain any values for the defined parameters.
Passing Client Headers
In order to perform various functions including handset identification, operator/carrier resolution, geographic targeting, and frequency capping, the HTTP headers from the originating (handset) client must be passed along with each ad request.
With a few specific exceptions, all headers – including the Accept* headers – should be forwarded to Millenial Media. The following headers should be explicitly excluded:
Host: Keep-Alive: Connection: Cookie: Cache-Control: Content-Length:
Millennial Media (formely Jumptap) Ad server uses IP addresses to determine several pieces of information about an ad request, including:
- The mobile operator from whose network the ad request was made. This allows advertisers to carrier-target their campaigns.
- The country from which the ad request was made. This allows advertisers to country-target their campaigns.
If you are able to forward device headers with the ad request and you have the ability to modify the headers, then you will need to manipulate the x-forwarded-for header as if you were a proxy:
- If the x-forwarded-for header is present in the headers from the device and has a non-zero length then append ",<client ip>" to the end of it prior to forwarding it Millennial Media.
- If x-forwarded-for has a zero-length or is not present in the headers from the device, then set it to "<client ip>" without the comma.
If you are able to forward device headers with the ad request but you cannot modify the headers, then:
- Forward the x-forwarded-for header as-is to Millennial Media
- Include the client-ip parameter in the query string of the ad request and set it to "<client ip>".
If you are not able to forward device headers, then:
- Include the gateway-ip parameter in the query string of the ad request and set it to the x-forwarded-for header from the device.
- Include the client-ip parameter in the query string of the ad request and set it to "<client ip>".
In all cases above, <client ip> refers to the IP address of the client invoking you. This IP which can be obtained from the HTTP implementation you are using.
For more information regarding the x-forwarded-for header, please refer to Wikipedia: http://en.wikipedia.org/wiki/x-forwarded-for.
Required Request Information
|gateway-ip||x-forwarded-for||Y||A series of IPs associated with the ad request. Please refer to the Passing IPs section above for further detail.|
|Y||The unique device ID
|idflag||Y/N|| On iOS devices corresponds to the advertisingTrackingEnabled parameter available in iOS 6 (or higher); indicates whether the user has limited ad tracking.
|l||Accept-Language||Y||The user’s preferred language. Valid values are the ISO-639-1 2 letter language codes. http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|
|pub||Y||Your publisher alias as assigned by Millennial Media.|
|site||Y||A site alias assigned by Millennial Media.|
|spot||Y||An ad spot alias assigned by Millennial Media.|
|url||Y/N||The URL of the page requesting the ad.
|ua||User-Agent||Y||The user-agent of the handset making the request. tapLink uses this to identify the handset making the request thus allowing us to serve handset-targeted campaigns and to insure that the correct size ad is returned.
|v||Y||Version of the Millennial Media API. Currently 'v30' (Version 3.0).|
Optional Request Information
|mt-jtlib||N|| This is to identify the SDK version that is being used, and is only necessary on app traffic that utilizes an SDK. The value passed must be the standardized name/version number established by the SDK developer. Examples:
|idflag||N||For iOS versions 6 and later, it is recommended that you pass the value of the advertisingTrackingEnabled flag as the idflag value.
|a||N||Indicates whether adult ads are allowed to be returned in response to the ad request.
|client-ip||N||The IP Address of the device requesting the ad. This is used by tapLink and our Ad Providers for Carrier/Gateway targeting. Please refer to the Passing IPs section above for further detail.|
|country||Y/N||The two letter ISO country code of the originating user’s request. http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
|email_sha1||N||Email address, hashed using SHA1 algorithm. All characters must be lower case prior to hashing. Used to correlate 3rd party, anonymous ad targeting data to increase publisher eCPMs.|
|mt-age||N||The user's age in years, if known. Valid values include any integer from 1-199.|
|mt-gender||N||The user's gender, if known. Valid values are 'm' or 'f'|
|mt-hhi||N||The user's household income in thousands, if known.
|mt-model||N||The manufacturer's model name. Applies to application traffic only and used for device targeting.
|operator||N||For publishers having on-deck instances of their sites, this parameter should be used to indicate the on-deck mobile operator.
|q||N||For search sites or applications, pass the search terms using the q ("query") parameter.
|Referer||N||The Referer HTTP header.
|u||N||The publishers unique id of the end-user. Used if the publisher has a unique way of identifying the user, such as a login.
Must not be a form of PII such as email, phone number or name. Should be some encoded value that is sent consistently for that user.
- Not passing HTTP headers.
- Passing the publishing server's HTTP headers rather than those of the handset.
- Not encoding the user-agent when passing it in the ua parameter.
- Double-encoding the user-agent when passing it in the ua parameter.
- Passing the user-agent of the publisher server rather than the handset.
Latitude / Longitude
- Not comma-separating the latitude and longitude values.
- Not encoding the latitude,longitude.
- Not encoding the postal code.
- Not including the country parameter when the postal code is passed.
- Passing a static value with every ad request.
- Passing the complete name of the country rather than the two-digit code.
- Not accounting for an empty ad response (e.g. not collapsing the placeholder when no ad is returned).
- In an iPhone app, not accounting for both supported ad sizes: 300 x 50, 320 x 50.
- In any application, not setting aside enough vertical space for the banner
Millennial Media uses the count on download (COD) method to calculate the number of ad impressions served to your app or website. This means that Millennial Media counts impressions when it receives confirmation that an ad downloads to a device, not at the time when your app or site requests an ad.
The count on download method provides a more accurate impression count than counting impressions at ad request-time, because it does not count requested ads that failed to display because a user leaves the site or loses coverage before the ad renders. This industry-standard metric, allows Millennial Media publishers to meaningfully compare performance across multiple providers, and can impact revenue potential due to increased buys from advertisers with more confidence in the accuracy of impression count data. Note: While proper implementation to assure accurate impression count is critical for CPM campaigns, inaccurate impression counts issues do not impact click counts for CPC campaigns. Troubleshooting inaccurate impression counts In order for your site to count impressions accurately you must integrate your application or website properly. As part of the ad response, Millennial Media sends one or more 1x1 unique tracking pixels for each ad that confirms successfully displayed impressions. If your system rips out those confirmation pixels from the request, caches ads so that the tracking pixel cannot verify multiple impressions for a single response, or times out before confirmation, your publications will report inaccurate impression counts. The table below describes how to detect and fix inaccurate impression count issues.
Symptoms of inaccurate impression count To detect inaccurate impression count, look at your performance numbers in tapLink for discrepancies between impressions, clicks, and downloads. The following performance trends indicate inaccurate implementation of the count on download solution:
- Zero impressions
- More clicks than impressions
- A discrepancy between downloads and impression counts
Of these symptoms, performance with zero impressions is caused by your implementation stripping the tracking pixel from the ad response. See the table below for complete details on all causes and fixes for inaccurate impression counts.
Causes and fixes for inaccurate impression counts
| 1x1 Pixel Stripping
Your site implementation strips the 1x1 tracking pixel that confirms a successful impression from the Millennial Media ad response.
|A Millennial Media ad response consist of a few HTML tags: an image tag of the ad creative, wrapped in an anchor tag targeting the ad's click-location, as well as one or more ad tracking image tags with a width and height set to one pixel. Some publishers create processes to strip out sections of ad requests.|| Do not strip the 1x1 tracking pixels that confirm successful ad impressions from the ad response when receiving it from Millennial Media and sending it to the mobile device. The pixel looks like this:
<img src="http://pixel.jumptap.com/e/v1/pixel/impression/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" alt="" width="1" height="1" />
where each X represents a hexidecimal value.
Your site implementation caches ads and serves cached ads.
|A Millennial Media ad response sends code that tracks the success of a single impression specific to each ad. This code verifies an impression only once for each ad, so if you display the ad multiple times, subsequent impressions for that ad will not register.||Do not cache Millennial Media ads. Display each ad Millennial Media response only once.|
Ads timeout before they can display
|Geographic location, as well as the number of stops in the ad requests path, increases the download time.||Extend the request timeout to > 250ms for US East Coast traffic and > 500ms for US West Coast traffic.|
| BlackBerry Traffic
Ads served on BlackBerry devices
|The Blackberry server strips the 1x1 pixel from the ad response.||No fix. Your impression count might be inaccurate, but your click numbers will be accurate.|
Ads returned from Millennial Media are valid XHTML. There are a number of benefits to XHTML, each of which makes your inventory more valuable to advertisers:
- Using XHTML allows us to introduce tracking pixels to our ad responses.
- Using XHTML allows us to introduce additional ad types and functionality in the future without requiring a modification to your integration.
Adding Style Information
Style information can be added to the response by wrapping it in <DIV> tags. Common style changes include centering the banner, centering the text below a banner, and changing the color of text below a banner.
Handling the Response
Ad responses are to be displayed in-whole, without modification. Parsing or otherwise modifying the response may lead to unexpected and / or undesired behavior. For example, parsing the image and click may cause you to ignore tracking pixels also contained in the response, thus rendering your site ineligible for third-party tracked campaigns.
tapLink supports banners that conform with the October 2008 revision of the MMA mobile advertising guidelines as well as additional ad sizes such as tablet interstitial and iPhone-optimized banners.
|Banner Type||Example Handsets||Notes|
|iPhone Optimized Banner/XXL Banner||
|iPhone Interstitial Portrait||
|iPhone Interstitial Landscape||
|Tablet Interstitial Landscape||
|Tablet Interstitial Landscape||*Apple iPad/ iPad mini
|Call-to-action text for banners||
The MMA guidelines can be found here: http://mmaglobal.com/mobileadvertising.pdf
Serving an ad into an iFrame
Millennial Media supports serving ads into iFrames. There are two different display options to choose from. You can either 1) configure the landing page to open in a separate window or 2) to take over the outmost window. (Please see the W3C specification for more information: http://www.w3.org/TR/html401/types.html#type-frame-target )
These options can be set up on the site level (for all subsequent ad spots) by informing your account manager or contacting email@example.com. The alternative for iFrame support is to set it up for specific ad spots by adding a parameter on the ad request. The parameter values that can be used are covered below.
Option 1: When a user clicks on the ad, the destination page will render in a new window.
- If you would like to set up support, you can do so by adding "linktarget=blank” as a parameter in your ad request.
Millennial Media will append "target=_blank" to the ad response as an indicator that the response is properly formatted for the iFrame.
Option 2: When a user clicks on the ad, the iFrame will expand and the destination page will take over the current window.
- If you would like to set up support, you can do so by adding "linktarget=top” as a parameter in your ad request.
Millennial Media will append "target=_top" to the ad response as an indicator that the response is properly formatted for the iFrame.
Standard Text Banner
<a href="http://...">Vonage</a><br/> Low Phone Rates!<br/>
Standard Image Banner
<a href="http://..."> <img src="http://..." width="300" height="50" /> </a><br/>
Standard Image/Text Combination Banner
<img src="http://..." width="300" height="50" /><br/> <a href="http://...">Low Phone Rates!</a><br/>
Image Banner with tracking pixel
<div> <img src="http://..." width="300" height="50" /><br/> <a href="http://...">Low Phone Rates!</a><br/> <img src="http://pixelurl.com" height="1" width="1" border="0" alt=""> </div>
Image Banner with two tracking pixels
<div> <img src="http://..." width="300" height="50" /><br/> <a href="http://...">Low Phone Rates!</a><br/> <img src="http://pixelurl.com" height="1" width="1" border="0" alt=""> <img src="http://pixelurl2.com" height="1" width="1" border="0" alt=""> </div>
No Ad Available
A zero-length response body.
Error Handling and Codes
This section describes how Millennial Media responds to error conditions. Errors are reported to the client through the standard list of HTTP status codes.
Requests that return no advertisements are considered normal behavior and not an error. For XHTML responses you will receive a zero-length content body.
HTTP Status Codes
|200||Response indicating that the request completed successfully.|
|201||This response code is returned when activity reporting events are logged successfully with tapLink.|
|400||A bad request status is send when not all the required parameters are provided or if any one of the required parameters contains an invalid parameter.|
|401||Sent when incorrect credentials are sent with the request.|
|403||Sent when IP restrictions are in effect.|
|404||Sent when the ad spot or ad provider does not exist.|
|500||Sent when there is an unexpected server-side error.|
|503||Sent when the service is currently unavailable.|
The publisher is responsible for dealing with errors returned from tapLink. The publisher is also responsible for setting the appropriate socket, connection and read/idle timeout values on their client application to protect themselves from a possible Millennial Media outage.
The publisher should work with Millennial Media to determine the proper timeout values and retry policy based on the type of application the publisher has developed. Setting these timeouts will vary depending on the underlying HTTP client library implementation.