Ad Server API

From Adfonic Wiki
Jump to: navigation, search

Contents

Getting Started

To get live ads in your site or app you just need to:

Design Overview

Adfonic’s APIs use REST principles and are designed to be easy to work with and flexible for the future. The APIs are simple HTTP GET requests to the Adfonic servers, with optional and required parameters in the query string portion of the URL. The parameters must be encoded as name/value pairs using the standard HTTP URL-encoding guidelines.

Proxied API

The proxied API is typically used for mobile sites and when integrating an ad slot into a server-side application, but it can also be used from a client application in advanced scenarios. The name “proxied” alludes to the fact that many of the parameters that are passed on to the Adfonic server need to be copied from the request made to the mobile site. For example, you’ll need to encode and pass HTTP headers that were part of the end user’s browser’s request if you’re calling the API from a server-side system.

Service URL

The URL format for the proxied API is as follows: 

http://adfonic.net/ad/{adSlotID}?{requiredAndOptionalParameterNameValuePairs}

Request Parameters

There are a number of optional and required parameters that can be processed by the proxied API, as follows. As usual, multiple parameters must be separated by an ampersand (&) character, and all parameter values should be properly URL-encoded.

Parameter name Required? Format Description
r.client No Arbitrary string A arbitrary string identifying the client originating the request. We advise you to include at the miminum company/product name, platform and version e.g. Adfonic/Android/1.0.2.1
d.dpid No 40 chars If you are able to access the iOS UDID or Android Secure.ANDROID_ID it should be sent as a SHA-1 hash and should be used instead of the r.id. If you cannot supply a device identifier then see r.id.
d.ifa / d.hifa No 36 chars / 40 chars If you have access to the advertisingIdentifier on IOS6+ devices, you can send it via the d.ifa parameter (in the string representation of the NSUUID, including hyphens) or the d.hifa parameter (as the SHA1 of the string representation of the NSUUID, including hyphens).
d.udid No 40 chars If you are able to access the iOS UDID but are unable to provide this SHA-1 hashed, you can use this parameter. If you cannot supply a device identifier then see r.id.
d.openudid No 16 chars The current OpenUDID value for this device. If you cannot supply a device identifier then see r.id.
d.odin-1 No 40 chars The ODIN-1 value for this device. If you cannot supply a device identifier then see r.id.
d.atid No 40 chars The Ad Truth ID for this device. We expect you to use the WEB_APP_BRIDGE_2_3_16 recipe. If you don't, please contact us to see how we can resolve the situation.
r.id Yes (if not using any d.* parameters, see above) Varies Used if you are not able to pass the d.dpid. It is a clear text unique identifier for the device or user, either generated by your application or by Adfonic, and typically associated with the user by means of cookies on a site or persistent storage in an application. For applications that have access to a unique device identifier (like the iPhone’s UDID) this value should be used. See the discussion elsewhere in this document.
r.ip Yes, if the ad request is made from a server n.n.n.n IP address of the end user. If not specified, the IP address of the requesting connection is used. It must be an external IP address.

Please note that the X- Forwarded-For HTTP header, if present, will override the IP address specified here.

r.hw No String e.g. "iPhone1,1", "iPhone2,1", "iPad1,1", etc (mnemonic: request hardware) and expected value is the iOS hardware identifier string e.g. "iPhone1,1", "iPhone2,1", "iPad1,1", etc
s.test No 0 | 1 Test mode (0=false, 1=true). The default is 0.
h.{header-name} (multiple parameters) Yes, if the ad request is made from a server Varies HTTP headers sent by the end user’s browser. The header- name in parameter name should be all lowercase. Most important of these is “h.user-agent” which identifies the user’s device, but all HTTP headers should be proxied in the request as h.* parameters unless the request is coming directly from the user agent.
t.colorScheme No blue|green|orange|purple |red|yellow The background color to use when serving enhanced text ads on high-end devices. This enables you to customize the look and feel of these ads to match your own design template. The default is configurable on the Adfonic site.
t.format No urlencode | xml | json | html The format to use for the response. These are detailed below. The default is urlencode. The "html" format returns only the raw HTML to be shown to the end user; if no ad is available, this will be the string .
t.markup No 0|1 If set to ‘1’ (enabled, the default), the response will contain a chunk of basic HTML code (anchor, href, image etc) that can be rendered on the user’s device. If disabled, you must parse the various ad components in the response in order to present them to the user.
t.pretty No 0|1 If set to '1' (enabled, the default), the response will contain all the elements required to put together a pretty view for text ads to be shown in a banner format, including icons and background image. See below for guidance on how to generate the relevant markup if you prefer not to enable this.
t.beacons No markup|metadata [TESTING ONLY] Only active when t.markup is not set to '0'. If set to 'markup' (the default), the formatted output will include HTML code to call the beacon(s). If it is set to 'metadata', an additional section in the 'components' section of the response will be present listing the details for the beacons. See below for more information on beacons.
t.exclude No RICH_MEDIA Signals that the request must not be served a Rich Media response.
u.gender No m|f The user’s gender (male or female), if known
u.dob No Number in format YYYYMMDD The user’s date of birth, if known
u.age No Integer The user’s age, if known (alternative to u.dob)
u.ageLow, u.ageHigh No Integers The user’s age range, if known (alternative to u.dob)
u.latitude, u.longitude No Decimal The user’s geo location
u.dnt No 1) The user’s Do-Not-Track status. When set to 1 no behavioural targeting will be performed based on the request.

Response Format

The response to this URL request comes in three flavours, depending on the setting of the “t.format” parameter. The contents of the response must be parsed by the application.

The next section gives some examples of the general format of responses in each flavor, followed by a description of what the various items represent.

URL-Encoded

In “urlencode” format, the response contains a set of name-value pairs encoded with the application/x-www-form-urlencoded content type. Here’s an example:

status=success&adId=b44613d1-8dda-4485-938c-6d5152fee2b2&trackingId=086e62ad-d1d8-4d92-b90d-60cab0efcec9&format=banner&destination.type=URL&destination.url=http%3A%2F%2Fadfonic.net %2Fct%2Fb44613d1-8dda-4485-938c-6d5152fee2b2&components=image&component.image.url=http%3A%2F%2Fadfonic.net %2Fas%2F6608c245-51e0-41a9-aa60-928114444b0e&component.image.width=300&component.image.height=50

XML

In “xml” format, the response is a well-formed XML document. Here’s a sample XML response: 

<?xml version="1.0" encoding="UTF-8"?>
<ad>
  <status>success</status>
  <adId>ecbd4c1b-d60d-4e3a-af94-ec5adf92de46</adId>
  <trackingId>086e62ad-d1d8-4d92-b90d-60cab0efcec9</trackingId>
  <format>banner</format>
  <destination type="URL" url="http://adfonic.net/ct/ecbd4c1b-d60d-4e3a-af94-ec5adf92de46"/>
  <components>
    <component type="image">
      <attribute name="url">http://adfonic.net/as/0382f7ba-df69-4f6f-b249-3c61e3a32848</attribute> 
      <attribute name="width">300</attribute>
      <attribute name="height">50</attribute>
    </component>
  </components>
</ad>

JSON

In “json” format, the response is a well-formed JSON string that can be evaluated by a compliant JavaScript engine. Here’s a sample response (with white space added for readability): 

{
  "status":"success", 
  "adId":"ca794c66-981e-49c4-84f5-0799a131e7d2", 
  "trackingId":"086e62ad-d1d8-4d92-b90d-60cab0efcec9", 
  "format":"banner", 
  "destination":{
    "type":"URL",
    "url":"http:\/\/adfonic.net\/ct\/ca794c66-981e-49c4-84f5-0799a131e7d2" 
  },
  "components":{ 
    "image":{
      "url":"http:\/\/adfonic.net\/as\/6608c245-51e0-41a9-aa60-928114444b0e", 
      "width":"300", 
      "height":"50"
    }
   "beacons":{
      "beacon1":"http:\/\/adfonic.net\/bc\/11111111-1111-1111-1111-111111111111\/324f3d58-9537-44c2-b4b6-4c19e71f0db8.gif",
      "numBeacons":"1"
    }
  }
}

Response Parameters

The key values in the response are:

Parameter Description
Status Either “success” or “error”.
Error An explanation of any error that occurred, if applicable. An error you should expect to get occasionally is “No ad available”; this means Adfonic had no ad to serve for the request.
Ad ID A unique reference code for this specific ad response. You will note that this identifier is used in the clickthrough URL.
Tracking ID The tracking ID that should be issued to the user as a cookie, if any (see explanation of tracking IDs below).
Destination URL The URL that loads when the ad is selected
Destination Type Indicates the expected action for the destination URL. Depending on the device type, possible values are “URL” (this is the most common), “CALL” for URLs that perform click-to-call actions, and, on Apple devices, “AUDIO”, “VIDEO”, “ITUNES_STORE”, and “IPHONE_APP_STORE” for URLs that launch the respective applications. If you are writing a custom ad client, you must ensure that links of this type function correctly.
Format The format of the ad that was returned. The possible formats for the ad slot are configured through the Adfonic site. Current values are “banner” or “text”.
Components These items detail the components of the ad response. The component names vary depending on the ad format. In the “urlencode” response format, the “components” key contains a comma-separated list of components that form part of the response to help you iterate through.

Components for format “banner”

The banner format has one required and one optional component. The required component is called “image” and has three properties, “url”, “width”, and “height”. The optional component is called “tagline” and has a single property, “content”. A tagline is a text link that should be rendered below the banner image.

Components for format “text”

The text format has one required and one optional component. The required component is “content” which is a simple text string that should be rendered as a clickable link. On Apple devices, additional components called “icon” and "backgroundImage" are available. The icon is a small (42x42) image that can be rendered with the text link in a 300x50 box, helping to give a more visual feel to the ad. These items have “url”, “width” and “height” properties. You can suppress these components by specifying "t.pretty=0" in the ad request.

[TESTING ONLY] Components for "beacons"

Beacons are 1x1 pixel images that help us and our advertisers to establish whether an impression occurred. Currently, a maximum of two beacons will be returned. Beacons are returned as a component of type "beacons". The component consists of a list of numbered beacons (beacon1, beacon2, beaconN) containing a URL to a 1x1 pixel image and a value indicating the number of beacons. To render the beacons you can use any method that guarantees (!) that the end user will retrieve the image. We recommend that you render the beacon within the visible area of the screen to ensure the device does not defer loading. Beacons will become an integral part of impression counting and will therefore be essential to securing income from any ad. To automatically render the beacons as part of the HTML output (when using t.markup=1) use the t.beacons=markup flag - be sure to check whether the automated placement influences the performance of the beacons.


Ad Content The HTML content of the ad response that should be shown to the end user. You can suppress this field from the response by specifying “t.markup=0” in the request.

Rendering a Text Banner

The following is a template for rendering a text banner from the raw components (using the Velocity template language -- feel free to adapt to your own technology). If you are making requests with t.markup disabled, we strongly encourage you to render text ads with the optional components noted above in this format. 

<div style="position:relative;width:300px;height:50px;border:0" onclick="location.href='${adComponents.destinationUrl}';">
#if($adComponents.components.backgroundImage)
  <div style="position:absolute;width:300px;height:50px;top:0px;right:0px;border:0px;"><img border=0 alt="" width=300 height=50 src="${adComponents.components.backgroundImage.url}"/></div>
#end
#if($adComponents.components.icon)
  <div style="position:absolute;width:42px;height:42px;top:4px;left:4px;border:0px;"><img border=0 alt="" width="${adComponents.components.icon.width}" height="${adComponents.components.icon.height}" src="${adComponents.components.icon.url}"/></div>
  <div style="position:absolute;display:table;width:200px;height:42px;top:4px;left:50px">
#else
  <div style="position:absolute;display:table;width:246px;height:42px;top:4px;left:4px">
#end
    <div style="position:relative;display:table-cell;font-family:tahoma,verdana,sans-serif;font-size:12pt;text-align:center;vertical-align:middle;color:#000000">${adComponents.components.text.content}</div>
  </div>
</div>

Request Parameter Details

Here’s a little more detail on the parameters described in the tables above, broken down by section.

Identifying and Customizing the Ad Slot

The Ad Slot ID is encoded within the base URL. This is all you need to uniquely identify each ad slot. Adfonic will look up the ad formats associated with the ad slot, as well as the site or app demographics that you configured.

Passing Request Properties (proxied requests only)

For proxied requests, the Adfonic service needs to know as much about the original request as possible in order to correctly apply targeting parameters to ensure that the most relevant ads are chosen. You must pass the r.ip parameter, which is the original request’s IP address. The IP address should be in the numeric format – for example, 192.168.0.1. In addition, you should submit as many of the HTTP headers from the request as possible. These include key parameters like h.user-agent which is the key property used to identify the device type. Other headers will contain information about browser-specific settings. HTTP headers can also contain information about proxies between the end user and your servers that may obscure the IP address or device properties. The sample code libraries take the suggested approach of iterating through all available HTTP headers and including them as parameters.

IMPORTANT: User Agent (user-agent)

The user-agent must be the source mobile device user-agent string. The user-agent helps Adfonic return the correct ad format and size for that devices capabilities. If you spoof the user agent you will receive HTTP 401 on the click-through. Example of a valid iPhone 3 user agent: “Mozilla/5.0 (iPhone; U; CPU iPhone OS 3_0 like Mac OS X) AppleWebKit/525.18.1 (KHTML, like Gecko) Version/3.1.1 Mobile/5A345 Safari/525.20”.

IMPORTANT: IP Address

The IP address (r.ip param) must be the source mobile device IP. It should be a valid external IP addresses. If you spoof the IP address the user will receive the correct URL, but it will not be registered as a click.

Identifying Unique Users

Adfonic’s service is designed to track unique users to the extent practical on mobile devices. To do so, each user must be given a unique identifier. You can either use your own unique identifier, if you already have one for the user, or let Adfonic assign one for you. If you use your own identifier, simply pass it in as the r.id value. The only requirement on the Adfonic side is that the unique part of the identifier is 255 characters or less (decoded value length). The identifier must be unique and accessible across all ad slots for a given site or app. If you’d rather have Adfonic generate unique IDs, you’ll need to do a little more work. The first time you get a request from an unrecognized user, omit the r.id value from the request. In the response, you’ll see the trackingId value. This value will need to be associated with the user for subsequent requests. In a web application, this is typically done by setting a persistent user cookie. You can use any name of your choosing for the cookie; by convention, the code templates use “adfonic-tracking- id”. We recommend that the cookie be set to expire no less than 60 days in the future. If you’re working in an application environment and have access to a unique device identifier, like the iPhone’s UDID, this should be used for r.id.

Passing User Profile Data

User profile data can be used to give Adfonic additional demographic details about the user while maintaining anonymity and privacy (Adfonic never stores any personally identifiable information about an end user; for further information, see our end user privacy policy on the site).

The more you know about a user, the more relevant the advertising you’ll be able to supply via Adfonic. This is particularly useful for sites like social networks where users are required to register their details, or applications that may prompt the user for specific details. If supplied, the details you provide in user profile request parameters supersede and override the general audience profile for your site or app that is configured through the Adfonic web site.

You can pass the user’s gender as the u.gender parameter. Use u.gender=m for male and u.gender=f for female.

To determine the user’s age, Adfonic allows various formats to be passed in. If you know the user’s exact birthdate, simply pass this value in the u.dob parameter, formatted as YYYYMMDD (for example, pass u.dob=19750507 for May 7, 1975). If instead you know the user’s age in years only, pass this value as u.age. Finally, if you prefer to only identify users by an age range, pass these values as u.ageLow and u.ageHigh. For example, u.ageLow=25&u.ageHigh=34 means a user between the ages of 25 and 34 (inclusive).

Choosing a Presentation Template

On some high-end devices (currently limited to the iPhone and iPod Touch), text ads will be displayed in an attractive box with a small icon representing the ad’s destination type. For these devices, you can customize the color scheme of the ad display by using the t.colorScheme parameter. Valid values for color scheme are blue (the default), green, orange, purple, red and yellow. You may wish to choose the color scheme that best complements the design of your site or app.

Retrieved from "http://developer.adfonic.com/index.php/Ad_Server_API"
Personal tools
Namespaces
Variants
Actions
App/Site Integration
Ad Campaign Tracking
Adfonic API
Troubleshooting
Toolbox