API Documentation
From QuattroWiki
Contents |
Custom API Integration
The Quattro Mobile Ad Platform API documentation is intended to support you should your mobile site or application be unable to use the Quattro-generated ad tags or any of the Quattro SDKs. The documentation also provides additional explanations of the parameters that can be used to further customize the ad tags.
As you customize, make sure that you:
- Decide on your XML vs. XHTML Response Format.
- Understand the Ad Request Format.
- Include the required parameters as listed in Quattro API Required Parameters.
- Consider the optional parameters to Enhance Your Targeting.
- Consider the optional Custom API Parameters listed in the table below.
- Read through the Custom Integration Considerations below.
XML vs. XHTML Response Format
You can request either an XML or XHTML response. The XHTML reponse format is preferred, as it is simpler to implement. Most mobile site integrations can be approached in this manner. Make sure that the XHTML reposnse returned from ad requests are injected directly into the site markup without modification. When no modifications are made, the Quattro Ad Platform formats the ads appropriately so that all specific requirements for serving a given ad are met.
In some scenarios, you may need to user XML. For example, a client application might need to access "parts" of the ad in order to support a platform specific method of rendering. If XML is used, make sure to handle all additional requirements needed to make the integration valid (see Custom Integration Considerations).
Ad Request Format
Ad requests are implemented as HTTP GET requests. The general URL formats for XHTML and XML requests are shown below.
Basic XHMTL Ad Request URL
http://ad.qwapi.com/adserver/render?uip=[USER_IP_ADDRESS]&ua=[USER_AGENT]&pid=[PUBLISHER_ID]&sid=[SITE_ID]&test=0
For example (line spacing added for readability):
http://ad.qwapi.com/adserver/render?uip=206.53.144.45&ua=BlackBerry8330%2F4.5.0.131+Profile%2FMIDP-2.0+Configuration %2FCLDC-1.1+VendorID%2F104&pid=2efd646a24c5414facad7c6d11bd28b2&sid=sample_sitename&test=0
Basic XML Ad Request URL
http://ad.qwapi.com/adserver/render?uip=[USER_IP_ADDRESS]&ua=[USER_AGENT]&pid=[PUBLISHER_ID]&sid=[SITE_ID]&test=0&fmt=xml&fmtver=2.0
For example (line spacing added for readability):
http://ad.qwapi.com/adserver/render?uip=206.53.144.45&ua=BlackBerry8330%2F4.5.0.131+Profile%2FMIDP-2.0+Configuration %2FCLDC-1.1+VendorID%2F104&pid=2efd646a24c5414facad7c6d11bd28b2&sid=sample_sitename&test=0&fmt=xml&fmtver=2.0
Note: As of June 2009, integrations requesting XML format responses should use version 2.0 of the XML format.
Quattro API Required Parameters
There are four basic parameters that are required. If you do nothing, these parameters are either generated or set by default and you will be able to get ads. If you want more control over the types of ads to display as well as the placement of those ads, you can adjust the adm and plc parameters.
| Parameter | Name | Description | Values | Required? |
pid
| Publisher ID | Supplies your unique Quattro Network publisher identifier. Assigned by Quattro when you create your account. | GUID String | Required |
sid
| Site ID | Supplies your unique Quattro Network site name. Assigned by Quattro when you register your site. If you have multiple sites, make sure to indicate the specific site in each ad request to support site-specific analytics. | String | Required |
adm
| Ad Media Type | Defines what kind of ads are served.
| a=any static banner, animated banner, text ad, interstitial or expandable ad b=static or animated banner | Required |
ua
| User Agent | Specifies the user agent of the browser, or client device requesting the ad. Used to determine capabilities of the device, for image optimization, and ad selection (e.g. click to call capable, video capable, etc) | URL-encoded string derived from client device headers | Required (created by default when using ad tags) |
uip
| User IP Address | Specifies the IP address of the client device back to the Quattro Network. Used for click validation. Important: It's crucial that this value always contains the IP address of the device. This may not be a hard-coded value, nor can it be the IP address of your server or mobile website. | URL-encoded string | Required (created by default when using ad tags) |
Enhance Your Targeting
With the Quattro API, you can take advantage of options to enhance the targeting of ads to your site. With these options set, you can make your site more eligible to receive ads that meet advertiser requirements. For example, if an advertiser wants to target a specific geographic region, your site will be qualified to receive that ad if you have set the Geographic Target parameter appropriately. By improving the relevance of ads appearing on your site, the ads will generally have better response rate which in turn will generally improve publisher revenue.
You can increase your site's eligibility by setting the parameters (when applicable) in the table below.
| Parameter | Name | Description | Values | Required? |
geo
| Geographic Target | Supplies values to request ads that target a particular geographic audience. Set to a name=value pair, with a predefined name value followed by a URL-encoded equals sign(%3D) and a numeric value. Multiple name=value pairs can be supplied, with each pair separated by a URL-encoded ampersand (%26).For example, to supply the area code 781 as a geographic target, you enter | URL-encoded Name=value pairs: dma=<Designated market area code> | Optional |
dem
| Demographic Target | Supplies values to request ads that target a particular audience demographic. This parameter supports several demographic categories; a request can include several different demographic targets in one request. This parameter is specified using one or more name=value pairs, with a predefined name value followed by a URL-encoded equals sign ( | URL-encoded Name=value pairs: g=<gender value>
age=<age range>
bday=<yyyymmdd birthdate>
edu=education level
eth=<ethnic group>
| Optional |
cid
| Content ID (Section ID) | Identifies a portion of the site as having common targeting characteristics. A section identifies areas of a site where similarly targeted ads should be displayed. A section may represent one or several parts on a single page in the site, or may include multiple pages. Ads can be targeted to the audience for a particular section within a site: for example, ads for Health and Beauty products can be targeted to the section identified as | String which must be shared with the Quattro Wireless team to enable matching setup on the Quattro Mobile Ad Platform. | Optional |
ond
| On Deck Indicator | Indicates whether the mobile device initiating the ad request call is on deck for the carrier (site accessed by a link on the carrier's main WAP deck) or off deck (site accessed by search engine, direct entry, etc.). Advertisers can specifically target on (or off) deck traffic. If this parameter is not supplied in the request, off deck is assumed. | 0=off deck 1=on deck | Optional |
Custom API Parameters
| Parameter | Name | Description | Values | Required? |
plc
| Placement | Defines the placement of the ad.
| top, middle, bottom | Optional |
fmt
| Format | Defines the format for the ad server's response. Defaults to fmt="xhtml". For expandable ad units, this parameter should equal fmt="xhtml".See Responses for examples. | XML XHTML | Optional |
fmtver
| Format Version | Identifies the version of XML or XHTML to use in the response. If not specified, the default is 1.0 for both XML and XHTML. Integrations requesting XML format responses should use version 2.0 of the XML format. See Responses for examples. | For XML: 1.0 and 2.0. For XHTML: 1.0 | Optional |
incxhtml
| Include XHTML Response Format | In a CDATA section, includes the full XHTML representation of the same ad. This parameter supports the case in which some clients need to query information about an ad via XML, but can inject preformatted XHTML. This is largely to simplify support for interstitial and expandable style ads (which rely on JavaScript and not just markup) for 3rd party mobile web clients. | incxhtml=true | Optional |
Custom Integration Considerations
Make sure to handle these issues when you customize your integration.
Rich Media Ads: Expandable and Interstitial Ads
Rich media ads are special ads that enable more interactivity with the user. Expandable ads enable an ad "microsite" to be loaded upon clicking a banner, without actually leaving the site or application. Interstitial ads display a large, screen-sized image when a page is loaded.
The popup behavior of interstitial ads can frustrate users, so additional code is implemented to limit the number of times this type of ad can be displayed within a given session. To do this on the web, the client passes cookies (via HTTP headers) back to the Quattro Ad Platform. Note that the Quattro-generated ad tags handle this by default; with a custom integration, this is required in order to validate the integration. Interstitial ads are not sent to a publisher's mobile site until it is determined that this capping can be implemented. For SDK clients, the SDK library handles the capping.
On the web, expandable and interstitial ads are implemented with JavaScript, and are currently only supported on Mobile Safari (iPhone/iPod Touch) and Android browsers. The Quattro SDKs can also support these ad types.
Using the incxhtml Parameter
If you are using XML responses, the incxhtml parameter can be used to enable the support for rich media ads. By adding incxhtml=true, the XML returned includes a <content> element that contains a <[CDATA]> section. This <[CDATA]> section contains the full ad that should be injected directly into a mobile page. In the case of rich media ads, the XHTML also includes the necessary JavaScript to support this type of ads. As there is considerable JavaScript code in some ads, this approach of providing the full markup to third-party XML consumers simplifies the ability for these types of clients to handle these types of ads.
Rich media ads returned should only be rendered on Mobile Safari and Android browsers. They do not work correctly on most other browsers.
The incxhtml parameters adds conisderable overhead to the size of the data returned, and it should therefore be used sparingly (e.g. if there is sizeable iPhone / Android traffic).
Tracking Pixels
XML 2.0 responses may include an element called trackingpixels (e.g. <trackingPixels>).
<trackingPixelUrl>http://feed.qwapi.com/static/images/pixel.gif</trackingPixelUrl>
<trackingPixelUrl>http://img.qwapi.com/ckimg_1x1.gif?iid=e2a363b0cb3e48979e6626a69d3e1f75</trackingPixelUrl>
</trackingPixels>
If these elements are included, it's crucial to have the device fetch these URLs in addition to fetching the images within the ad (e.g. banner). Some advertisers require the use of these pixels to validate their ad serving. Failure to fetch these pixels may mean that the ad is deemed not to have been served.
If it isn't possible to fetch the tracking pixels from the client then you can fetch them from the server, but if possible, you should try to mimic making the call from the client to minimize discrepencies. If an advertiser deems that there are too many discrepencies, they may opt to pull an ad from your site.
Identfying the Device
The Quattro Mobile Ad Platform uses the ua (User Agent) parameter to identify the browser and/or device that is accessing the publisher’s mobile website. Based on the device information received, the platform selects the optimal format for returning ads for display. For example, if the phone is incapable of rendering images, it would return text ads only. If the phone is capable of rendering images, the images are optimized for display on the particular device.
In addition to influencing how images are handled, other capabilities of the device may also influence the type of ads that are returned (e.g. ads focused on video, click-to-call ads, expandable ads, etc.). Some advertisers also target ads at specific classes of devices, or devices from particular manufacturers.
Identifying the Carrier
The Quattro Mobile Ad Platform uses the uip (User IP Address) parameter to identify the carrier used by the mobile device. Quattro Wireless is constantly refining and improving the accuracy of its carrier detection mechanisms and expanding them to include new carriers. Traffic that appears to be originating from mobile devices but that cannot be tied to a specific carrier is categorized as “Other Carrier,” while traffic that appears to be originating from desktop browsers is categorized as “Web.”
This method of identifying the carrier may not succeed for the following reasons:
- Some mobile traffic accesses mobile web sites using Wi-Fi, and is therefore not tied to a carrier.
- Some carriers cannot be reliably identified using IP addresses alone. In those cases, the platform uses additional information, including the user agent and carrier-specific HTTP headers to further aid in carrier detection.
It is critical to provide correct carrier information, as many ads can be targeted to specific carriers. Failure to provide accurate carrier data may limit the ads that can be served to your site.
Including HTTP Headers
In addition to the URL, the HTTP headers provided by the client device must also be sent to the Quattro Mobile Ad Platform in an ad request. To do so, the HTTP headers provided by the client device must be copied into new headers prefixed with “ch_” (for client header) and included in the HTTP request for the ad. For example:
| Original HTTP Header | HTTP Header for Ad Request |
Accept
| ch_Accept
|
Host
| ch_Host
|
Referrer
| ch_Referrer
|
x-up-subno
| ch_x-up-subno
|
msisdn
| ch_msisdn
|
There is no need to filter out specific headers, as the variety of headers will vary greatly from carrier to carrier. Requests should simply copy all of the headers sent from requesting devices into “ch_” format and send them along with the API requests.
There are two main reasons for requiring HTTP headers:
- Improved device/carrier detection
- Improved detection can improve the relevance of ads returned to your site and improve yield.
- Implementation of requirements for frequency capping and interstitial capping
- Frequency capping is the limit to the number of times a user sees a given ad over a given period of time, specified by the advertiser. Interstitial capping is the limit to the number of times an interstitial ad can be shown in a given session. Interstitial capping is implemented to avoid frustrating the user, as these ads can be obtrusive.
Responses
See Responses for a full description and examples.
