Server to Server

From mkMob Developer Wiki
Jump to: navigation, search

API 1.2 - Server to Server Integration Guide

The mkMob Ad-Request API is the publisher interface used for communicating with mkMob. The API is designed to fulfill the needs of mobile applications, mobile games, mobile websites and any other internet-connected platform. Requests to the API are done through calling a specific URL with a query string of certain parameters.



Design overview

mkMob's API uses simple proxified HTTP POST requests to the mkMob servers, with optional and required parameters in the HTTP POST body. The parameters must be encoded as name/value pairs using the standard HTTP URL-encoding guidelines.

A proxied API is normally used for server-side applications, but it can also be used from a client application in advanced scenarios. The name "proxied" implies that the parameters that are passed on to the mkMob server will have to be copied from the original request made to the server-side app. For example, you'll need to encode and pass HTTP headers that were part of the end user's browser request.


Request URL

mkMob's API provides functionality for your live system, and for testing. We recommend using the test mode for functionality and performance debugging.

Server-Side Integration

Type

URL

Ad Server End Point http://ads.mkmob.com/showad.asm

Note: During test mode, the end point will accept all the same parameters as the live mode. However, test mode will return sample ads. Ensure that you test your integration using the ad server's test mode before going live.


Mandatory Request Headers

You need to write server code to set certain required parameters. To request an ad, mkMob's Ad Server requires request parameters to be passed in the HTTP POST body in the x-www-form-urlencoded form. Ads are returned in mkMob-specific XML/HTML formats, which need to be parsed by your system.

All the POST body parameter names must be in lowercase and all the values must be URL encoded. You should pass all x- headers with the POST request as well. Mandatory headers are listed in the below table:

Header Name Type Description Values
Content-Type Mandatory The MIME type of the body of the request. application/x-www-form-urlencoded
x-forwarded-for Optional Originating IP address of a client. X-Forwarded-For: client1, proxy1, proxy2

X-Forwarded-For: 129.78.138.66, 129.78.64.103

x-operamini-phone-ua Optional Opera Mini uses a number of custom, unregistered HTTP headers. This header contains the user agent reported to the client by the device. x-operamini-phone-ua: <user-agent>

Example:

X-OperaMini-Phone-UA: SonyEricssonK750i/R1AA Browser/ SEMC-Browser/4.2 Profile/MIDP-2.0 Configuration/CLDC-1.1

x-device-user-agent Optional The value of this header field is set to the user agent string of the device's native client. x-device-user-agent: <user-agent>

Example:

X-Device-User-Agent: Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420.1 (KHTML, like Gecko) Version/3.0 Mobile/4A93 Safari/419.3

x-original-user-agent Optional The value of this header field is set to the user agent string of the device's native client. x-original-user-agent: <user-agent>

Example:

X-Original-User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_4_11; it-it) AppleWebKit/525.18 (KHTML, like Gecko) Version/3.1.1 Safari/525.18


Mandatory Request Parameters

The mandatory parameters are listed in the tables below for Mobile Web sites, iOS apps, and Android apps. Absence of any of these parameters will result in no ads being served.

Parameter

Value

mk-propertyid Property ID assigned at the time of property registration. This is also referred as API key in some systems, which will enable you to receive ads for your website or app. This can be retrieved by logging in to mkMob's Self Serve UI at https://www.mkmob.com.
mk-ad-slot A unique ID assigned to the ad slot. To retrieve the ad slot ID, you must login to mkMob's Self Serve UI, select the property and then access it's ad slots. If no slots are present, you will have to create one.
mk-carrier Remote IP address of the end user.
h-user-agent User Agent (UA) of the end user device.
mk-ads This parameter should contain the number of ads requested by the publisher. Currently, the value should be "1", for a single ad per API request. Support for multiple ads per API request will be added in newer versions of this API.
mk-format The format to use for the Ad Server response. Must be set to "XML"
mk-version This is the version number of the API integration. Please pass the value as pr-SPEC-API-20140430
mk-mode While testing, the value should be set to test. This will ensure that mkMob always returns test ads. When you are ready to go live, change the value to live. Please note that it may take a couple requests before your first ad is returned.
mk-secure Set the value to true if you want the Ad Server to return secure ads, that is, ads using HTTPS, otherwise, set value to false.

Please note: All mkMob related URLs will use HTTPS when you request secure ads, however, if the ad contains content from third-party systems, those URLs may not use HTTPS if the third party does not support serving secure ads.

u-uuid This parameter needs to be populated to pass a Universally Unique Identifier. It is a clear text unique identifier for the device or user, generated by your application or website, and typically associated with the user by means of cookies on a mobile site or persistent storage in an application. If you are able to access a unique device identifier (such as the iOS UDID or Android Secure.ANDROID_ID) it should be used instead. The u-uuid parameter should specify the type of ID being passed and should contain a single unique user ID. Please refer to the Passing Unique User Identification table below for more details.


Example: u-uuid=gpid,123e4567-e89b-12d3-a456-426655440000


Note: This parameter is essential for most of the campaigns to work for tracking purposes.


Optional Request Parameters

For improved targeting, you can provide our Ad Server with additional parameters such as content information or user demographics by using the following parameters in your HTTP POST requests:

Parameter

Value

h-referer Value of header Referer in the user's request, if present.
u-latlong-accu This should contain the latitude, longitude, and accuracy, separated by commas. This parameter is required if the request is needed to be considered for geo-targeting. The accuracy value should be "0" if the correct accuracy value is unavailable. Here, the accuracy is the radial accuracy of the lat-long data provided. More information on how to determine accuracy value can be found at http://en.wikipedia.org/wiki/Decimal_degrees.

Example: u-latlong-accu=<Values as Latitude, Longitude, Accuracy>

u-age User's age in years as an unsigned integer between 14 and 100. Values below 14 will be not be used for targeting due to privacy controls.
u-gender User's gender, if known. Accepted values are f or m in lowercase.
p-keywords A comma-separated list of words that will be used to return a contextually targeted ad.
reftag The value is a string used when Reporting/Performance Metrics groupings are needed by the publisher. The reftag may contain a maximum of 32 characters, it will be truncated if longer.


For example, reftag=contact can be used to group Reporting/Performance metrics based on advertisements served on a contact page.


Device-Specific Optional Request Parameters

Parameter Value
d-locale Indicates the user locale.
d-connectiontype Indicates the type of connection the device is connected to the network with. Possible values include:

wifi, 2G, 3G, 4G

d-orientation Indicates the orientation of the app on the device at the time of ad request. Possible values are:

1 - Portrait

3 - Landscape

Note: Ensure that the d-orientation parameter in the ad request is dynamically passed based on the orientation of the user's device. This is to ensure that orientation of the ad displayed on your property matches the orientation of the user's device.


Network/Aggregator Parameters

If you are a network/aggregator you must pass these parameters to us in your ad requests:

Parameter Sample Value Value
tp s_smaato Third-party integration type. For example tp=s_smaato, if the request is originating from the Smaato server-side mediation.

Note: The key name has to be agreed upon with the mkMob Support team and should remain constant for the integration. Absence of this parameter may result in poor supply quality score and therefore having an impact on publisher revenue.

tp-propertyid 2012_2324345 If you are aggregating traffic for multiple Publishers on a single mkMob Property ID, it is highly recommended you pass a unique ID per Site/App in the API so mkMob can optimise your traffic and achieve better eCPMs.
tp-name Clash Royale Provides a custom name for the property, to override the property name set in your mkMob account.
tp-domain company.com Provides a custom domain for the property, to enable DSP partners to identify your site/app to advertisers.
tp-storeurl https://play.google.com/store/apps/details?id=com.supercell.clashroyale Provides an app store url for the property, or - in absence - a web site url for the property.
tp-bundle_id com.supercell.clashroyale Here you can provide your app's bundle id. For example: com.domain.title or 2211285


Requesting Interstitials & Video Ads

The mkMob Ad Server can serve interstitials and video ads on your site/app. However, the below two parameters must be set to their defined values in order to successfully show videos and interstitials:

  • Ensure that the ad slot is of type Interstitial or Video
  • Set d-orientation value as 1 for portrait mode, 3 for landscape mode.


Passing Unique User Identification

u-uuid should be populated with a single user ID. The accepted user ID types are listed in the sections that follow.

iOS

Device ID Name Parameter Type Description
ida string Identifier for advertiser without hashing. iOS 6 and above only. For more information, click here.

Android

Device ID Name Parameter Type Description
gpid string Google Play advertising identifier, without hashing. Available for Android (2.3 and above) devices that have Google Play services with JAR above 4.0 on their phone. For more information, click here.

Web

Device ID Name Parameter Type Description
wc string Web cookie identifier. Unique identifier for mobile web requests.
sid string Indicates a user session ID on the publisher property.
lid string Indicates a login ID on the publisher property.


POST Body Structure

This section shows a sample structure of the POST body of an ad request. The POST body structure provided below can be viewed when the ad request is captured using a network packet capture tool.

Mobile Web

mk-propertyid=<Property ID>&mk-ad-slot=<Ad Slot ID>&mk-carrier=<End User IP*>&h-user-agent=<Device User Agent*>
&mk-ads=1&mk-version=<Version Value>&mk-format=<Ad Response Format>

Note: This value should never be hard-coded, but dynamically passed based on the end user’s device and IP address respectively.

iOS

mk-propertyid=<Property ID>&mk-ad-slot=<Ad Slot ID>&mk-carrier=<End User IP*>&h-user-agent=<Device User Agent*>
&mk-ads=1&mk-version=<Version Value>&u-gender=<Gender Value>&u-age=<Age integer>&u-latlong-accu=<Value as Latitude,Longitude,Accuracy>
&u-uuid=<User ID Type,User ID Value>&d-locale=<End User Locale>&d-connectiontype=<End User Network type>&d-orientation=<Value for Device orientation>&mk-format=<Ad Response Format>

Note: This value should never be hard-coded, but dynamically passed based on the end user’s device and IP address respectively.

Android

mk-propertyid=<Property ID>&mk-ad-slot=<Ad Slot ID>&mk-carrier=<End User IP*>&h-user-agent=<Device User Agent*>
&mk-ads=1&mk-version=<Version Value>&u-gender=<Gender Value>&u-age=<Age integer>&u-latlong-accu=<Value as Latitude,Longitude,Accuracy>
&u-uuid=<User ID Type,User ID Value>&d-locale=<End User Locale>&d-connectiontype=<End User Network type>&d-orientation=<Value for Device orientation>&mk-format=<Ad Response Format>

Note: This value should never be hard-coded, but dynamically passed based on the end user’s device and IP address respectively.


Ad Response Templates

The mkMob Ad Server responses come in UTF-8 encoding and the HTTP body contains all the ads. mkMob's XML responses follow the format shown here:

  • The root element is <AdResponse> followed by grouping element <Ads number="n">.
  • Inside <Ads>, each <Ad> is described with its type as attribute and other parts in the child nodes.


XML Response Templates

This section shows templates of XML responses.

Response for Ads

<?xml version="1.0" encoding="UTF-8"?>
<AdResponse>
   <Ads number="n">
      <Ad type="{ADTYPE}" actionType="{ACTIONTYPE}" actionName="{ACTIONNAME}" pricingModel="{MODEL}" payout="{PAYOUT}" width="{SLOTWIDTH}" height="{SLOTHEIGHT}">
          <AdURL>{LANDINGURL}</AdURL>
          <![CDATA[{CDATACONTENT}]]>
      </Ad>
   </Ads>
</AdResponse>

Response for No Fills

<?xml version="1.0" encoding="UTF-8"?>
<AdResponse>
   <Ads></Ads>
</AdResponse>

Description

  • ADTYPE: The type of ad contained in the response. Possible values are TEXT and BANNER
  • ACTIONTYPE: Integer value indicating the rendering to be used when parsing the ad response. Possible values are 1 or 2, where 1 means that it should be handled in a hidden browser view (for example, ads of type Click to Call or Click to SMS). 2 means that it should be handled in a normal browser view (for example, Click to Web or Click to Map).
  • ACTIONNAME: The call to action (CTA) of the ad. Possible CTA values are URL, CALL, SMS, IOS_APP, ANDROID_APP, WINDOWS_APP, KINDLE_APP, VIDEO, AUDIO
  • MODEL: The pricing model of the ad. Possible values are CPC, CPM, CPA. (Only applicable to aggregator/mediator platforms.)
  • PAYOUT: The payout price of the ad. The payout price is in USD currency. (Only applicable to aggregator/mediator platforms.)
  • SLOTWIDTH: The width of the ad creative.
  • SLOTHEIGHT: The height of the ad creative.
  • LANDINGURL: The click URL of the ad.
  • CDATACONTENT: This contains render ready HTML code that can be directly used.

Note:

To use the XML format, extract the CDATA block and use it on your website/application. Content parsing from the CDATA block will not be supported, you need to render the content. Do not modify ACTIONTYPE and ACTIONNAME. MODEL and PAYOUT are only applicable to aggregator/mediator platforms working with mkMob. These values will not be attached to the response for other publishers


Video Ad Response Templates

Video ads will be returned as IAB VAST 3.0 compliant XML. Please note that Vast 3.0 is backwards compatible with Vast 2.0.

Response for ads

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="3.0">
   <Ad id="1">
      <InLine>
         <AdSystem">mkMob DSP</AdSystem>
         <AdTitle>mkMob Video Creative</AdTitle>
         <Impression><![CDATA[http://ads.mkmob.com/beacon/c2fae25aa14c2560c47c337fe5af344a]]></Impression>
         <Creatives>
            <Creative sequence="1" id="1">
               <Linear>
                  <Duration>00:00:15</Duration>
                  <TrackingEvents>
                     <Tracking event="complete"><![CDATA[http://www.compleate.com]]></Tracking>
                     <Tracking event="firstQuartile"><![CDATA[http://www.FirstQuartile.com]]></Tracking>
                     <Tracking event="midpoint"><![CDATA[http://www.midpoint.com]]></Tracking>
                     <Tracking event="mute"><![CDATA[http://www.mute.com]]></Tracking>
                     <Tracking event="pause"><![CDATA[http://www.Pause.com]]></Tracking>
                     <Tracking event="resume"><![CDATA[http://www.resume.com]]></Tracking>
                     <Tracking event="start"><![CDATA[http://video_start.com]]></Tracking>
                     <Tracking event="thirdQuartile"><![CDATA[http://www.Thirdquartile.com]]></Tracking>
                     <Tracking event="unmute"><![CDATA[http://www.unmute.com]]></Tracking>
                  </TrackingEvents>
                  <VideoClicks>
                     <ClickThrough>http://ads.mkmob.com/click/ac2931d2c9ca1f1c542c91a7b9061ef4</ClickThrough>
                  </VideoClicks>
                  <MediaFiles>
                     <MediaFile delivery="progressive" width="640" height="360" type="video/mp4"><![CDATA[http://cdn.mkmob.com/VideoData/a5d96c7f0987d2644bdcef11bc24deb4.mp4]]>           </MediaFile>
                  </MediaFiles>
               </Linear>
            </Creative>
         </Creatives>
      </InLine>
   </Ad>
</VAST>

Response for No Fills

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="3.0"></VAST>


Response for errors

Incase of an error, the ad server will respond with a single XML error element.

<!-- We respond with an error xml element if something went wrong -->
<error>Mandatory parameters left unfilled</error>