Direct Publisher Integration Guide

From Millennial Media
Jump to: navigation, search


Contents

Overview

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).

Audience

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

Starting with the base URL, add the required request parameters plus any optional parameters that you can provide.

Note that:

  • 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.

http://a.jumptap.com/a/ads?v=&pub=&site=&spot=&a=&url=&ua=&gateway-ip&client-ip=&operator=&l=&ll=&pc=&country=&u=&hid=&mt-gender=&mt-age=&mt-hhi=

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:


Passing IPs

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

Parameter HTTP Header Required Description
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.
hid
hid_sha1
idfa
aaid
Y The unique device ID
  • This parameter is only required for applications, not mobile web sites
  • The parameter definitions and support may vary by operating system. A general summary is below and details are included in the operating system specific sections
    • hid: An operating system specific device ID. See below for the value expected per operating system
    • hid_sha1: A SHA1 hash of the operating system specific ID value
    • idfa: On iOS versions 6 and later, this is the advertisingIdentifier value
    • aaid: Google Play Advertising ID available on Android devices with Google Play 4.0 and above


  • iOS apps: For iOS we currently accept IDFA
    • idfa: The string representation of the advertisingIdentifier for the device. A valid idfa will have a format of 'AEBE52E7-03EE-455A-B3C4-E57283966239'. Note that the value is not hashed and it recommended that you also provide the optional idflag value when passing an idfa
  • Android apps: For Android we currently accept the following device IDs
    • hid: The Android_ID of the device. When using Android_ID, it is recommended that you pass the SHA1 hashed value using the hid_sha1 parameter. For developer documentation on obtaining Android_ID, see the Android Developer Guide
    • hid_sha1: The SHA1 hash of the Android_ID
    • aaid: Google Play Advertising ID available on Android devices with Google Play 4.0 and above. A valid aaid will have a format of 'aebe52e7-03ee-455a-b3c4-e57283966239'. Note that the value is not hashed and it's also required to provide idflag value when passing an aaid
  • BlackBerry apps: For BlackBerry we currently accept the following device IDs
    • hid: The BlackBerry PIN. It is a a 8-character hexadecimal value (digits 0-9 and letter A-F). When using the BlackBerry PIN, it is recommended that you pass the SHA1 hashed value using the hid_sha1 parameter
    • hid_sha1: The SHA1 hash of the BlackBerry PIN
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.
  • This parameter is required when the device ID parameter idfa is used (see above).
  • Values:
    • Set idflag to 'Y' if the device's value for advertisingTrackingEnabled is set to 'True' (default)
    • Set idflag to 'N' if the device's value for advertisingTrackingEnabled is set to 'False'
    • Note: do not alter the value of advertisingTrackingEnabled before sending, simply report whether the OS lists it as True or False.
    • Apple iOS Developer Guide on obtaining advertiserIdentifier and advertisingTrackingEnabled:


On Android devices corresponds to the isLimitAdTrackingEnabled() parameter available in devices with Google Play Services 4.0 and above; indicates wether the user has limited ad tracking

  • This parameter is required when the device ID parameter aaid is used (see above).
  • Values:
    • Set idflag to 'Y' if the device's value for isLimitAdTrackingEnabled() is set to 'False' (default)
    • Set idflag to 'N' if the device's value for isLimitAdTrackingEnabled() is set to 'True'
    • Google Play-Services Developer Guide on obtaining advertising Identifier and isLimitAdTrackingEnabled():
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.
  • Note that this is not the Referer header (which may reference the previous page), but is rather the URL of the page on which the ad will be displayed.
  • The value of this parameter must be encoded.
  • This parameter is required for requests from mobile web sites, but not for requests from applications.
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.
  • When using the ua parameter, the value must be encoded; do not encode the user-agent HTTP header.
  • For Opera Mini, the user agent of the handset is passed in the X-OperaMini-Phone-UA header. If you are passing the user agent in the ua parameter, this is the value you must use for Opera Mini requests. If you are passing the request headers, Millennial Media will automatically resolve the handset for Opera Mini requests.
v Y Version of the Millennial Media API. Currently 'v30' (Version 3.0).

Optional Request Information

Parameter HTTP Header Required Description
mt-mraid Y/N
  • mt-mraid=1 to request an MRAID version 1 compliant ad
  • mt-mraid=2 to request an MRAID version 2 compliant ad
  • mt-mraid=0 if you do NOT want an MRAID ad
  • Millennial Media will send 'X-Adtype: mraid' in the response header
  • This parameter is required in order to receive MRAID rich media
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:
  • mt-jtlib=2.4.0.5
  • mt-jtlib=IPHONE2.0.16.0_NOUDID
idflag N For iOS versions 6 and later, it is recommended that you pass the value of the advertisingTrackingEnabled flag as the idflag value.
  • y: If advertisingTrackingEnabled is set to True
  • n: If advertisingTrackingEnabled is set to False
a N Indicates whether adult ads are allowed to be returned in response to the ad request.
  • By default, adult ads are not returned; they must be specifically requested by the publisher.
  • Valid values include:
  • "notallowed" - indicates that adult ads may not be returned. This is the default value for the parameter.
  • "allowed" - indicates that adult ads may be returned; note that the returned ad may or may not be adult.
  • "only" - indicates that only adult ads should be returned.
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.
  • Country should be passed only if the country of the user originating the ad request is definitively known; it should not be set for a static value for all of your requests.
  • If country is not included in the request, Millennial Media will automatically determine the country based on the user or gateway IP.
  • The country parameter is required if the postal code (pc) parameter is passed.
  • If you are passing latitude/longitude, then the country parameter should not be passed.
ll N Latitude/Longitude
  • Latitude and longitude must be comma-separated.
  • The value of this parameter must be encoded.
  • Example, ll=42.369%2C-71.075
  • Latitude/Longitude is preferred to and supersedes the postal code and country parameters.
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.
  • Valid values include
  • 000_015
    • Where household income is less than $15,000
  • 015_020
    • Where household income is $15,000-$19,999
  • 020_030
    • Where household income is $20,000-$29,999
  • 030_040
    • Where household income is $30,000-$39,999
  • 040-050
    • Where household income is $40,000-$49,999
  • 050-075
    • Where household income is $50,000-$74,999
  • 075-100
    • Where household income is $75,000-$99,999
  • 100_125
    • Where household income is $100,000-$124,999
  • 125_150
    • Where household income is $125,000-$149,999
  • 150_OVER
    • Where household income is $150,000 or higher
mt-model N The manufacturer's model name. Applies to application traffic only and used for device targeting.
  • For Android devices - based on attribute: android.os.Build.DEVICE
  • For Blackberry devices - based on attribute: DeviceInfo.getDeviceName
  • For iPhone devices - based on attribute: UIDevice.model
operator N For publishers having on-deck instances of their sites, this parameter should be used to indicate the on-deck mobile operator.
  • This parameter should be passed only for on-deck instances for which the operator/carrier is definitively known.
  • For off-deck requests, Millennial Media will determine the operator based on request header and gateway IP information.
  • See Valid Operators for a list of valid operators.
pc N Postal code
  • If you are passing latitude/longitude, then the pc parameter should not be passed.
  • The value of this parameter must be encoded.
  • If postal code is included in the request, the country parameter is required.
  • Example: pc=02141&country=us
q N For search sites or applications, pass the search terms using the q ("query") parameter.
  • The value of this parameter should be encoded.
Referer N The Referer HTTP header.
  • Note that this is not the URL of the page making the request but rather the previous page.
  • There is not currently a parameter that corresponds to the Referer 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.

Common Errors

HTTP Headers

  • Not passing HTTP headers.
  • Passing the publishing server's HTTP headers rather than those of the handset.

User-agent

  • 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.

Postal Code

  • Not encoding the postal code.
  • Not including the country parameter when the postal code is passed.

Country

  • Passing a static value with every ad request.
  • Passing the complete name of the country rather than the two-digit code.

Display Errors

  • 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

Impression Count

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

Cause Description Fix
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.

Ad Caching
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.
Latency
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.

Ad Responses

Response Format

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 accommodate the richer ad units that advertisers are now requesting, including Javascript and rich media ads for those handsets that support them.
  • 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.

Creative Specifications

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
  • Apple iPhone
  • Google G1
  • Nokia E70
  • Palm Treo 700p/ iTouch
  • Dimensions: 320 x 50 pixels
  • Supported file types: .gif, .png, .jpg
X-Large Banner
  • Apple iPhone/iTouch
  • Google G1
  • Nokia E70
  • Palm Treo 700p
  • Dimensions: 300 x 50 pixels
  • Supported file types: .gif, .png, .jpg
iPhone Interstitial Portrait
  • Apple iPhone / iTouch
  • Samsung Galaxy S3
  • Dimensions: 320 x 480 pixels
  • Supported file types: .gif, .png, .jpg
iPhone Interstitial Landscape
  • Apple iPhone / iTouch
  • Samsung Galaxy S3
  • Dimensions: 480 x 3200 pixels
  • Supported file types: .gif, .png, .jpg
Leaderboard
  • iPad / iPad mini
  • Samsung Galaxy Tab
  • Dimensions: 728 x 90
  • Supported file types: .gif, .png, .jpg
Medium Retangle *iPhone
  • Samsung Galaxy S3
  • Dimensions: 300 x 250
  • Supported file types: .gif, .png, .jpg
Tablet Interstitial Landscape
  • Apple iPad/ iPad mini
  • Amazon Kindle Fire
  • Dimensions: 1024 x 768
  • Supported file types: .gif, .png, .jpg
Tablet Interstitial Landscape *Apple iPad/ iPad mini
  • Amazon Kindle Fire
  • Dimensions: 768 x 1024
  • Supported file types: .gif, .png, .jpg
Large Banner
  • LG VX-8500 Chocolate
  • Samsung MM-A900
  • Dimensions: 216 x 36 pixels
  • Supported file types: .gif, .png, .jpg
Medium Banner
  • LG VX-8000
  • Motorola RAZRs
  • Motorola ROKR E1
  • Dimensions: 168 x 28 pixels
  • Supported file types: .gif, .png, .jpg
Small Banner
  • Motorola V195
  • Dimensions: 120 x 20 pixels
  • Supported file types: .gif, .png, .jpg
Call-to-action text for banners
  • All
  • Dimensions:
    • 24 characters X-Large
    • 18 characters Large
    • 12 characters Medium
    • 10 characters Small
  • Supported: text, accented characters

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, by contacting us at gmstech@millennialmedia.zendesk.com or fill out our support form here. 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.

Sample request:

http://a.jumptap.com/a/ads?format=xhtml&spot=xyz_spot&...&linktarget=blank

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.

Sample request:

http://a.jumptap.com/a/ads?format=xhtml&spot=xyz_spot&...&linktarget=top

Millennial Media will append "target=_top" to the ad response as an indicator that the response is properly formatted for the iFrame.

Sample Responses

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

Status Code Description
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.

Timeouts

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.

Personal tools