inneractive

inneractive
Server to Server
Integration Protocol
Technical Definitions
Rami Citrom (Rami@inner-active.com)

8/11/2010

Version 1.5.2

Server -2-Server Integration Protocol Definitions – partner guide and technical specifications.
2 inneractive Connected Applications Integration Protocol

Contents
1 Table of changes ................................................................................................................................... 3
2 General Description .............................................................................................................................. 4
2.1 Overview ....................................................................................................................................... 4
2.2 Intended usage ............................................................................................................................. 4
2.3 Ad definition.................................................................................................................................. 4
3 Making a Request.................................................................................................................................. 5
3.1 Sample Requests ........................................................................................................................... 6
3.1.1 Client side request: ............................................................................................................... 6
3.2 Required Information.................................................................................................................... 7
3.3 Required Information – Server to Server Requests (requestAd, requestHtmlAd) ....................... 7
3.4 Optional Information .................................................................................................................... 8
3.5 Headers ....................................................................................................................................... 10
4 Response ............................................................................................................................................. 11
4.1 XML Response ............................................................................................................................. 11
4.2 HTML Response........................................................................................................................... 11
5 Appendix A: XML Response Schema ................................................................................................... 12
6 Appendix B: Sample Responses .......................................................................................................... 13
XML Response ................................................................................................................................. 13
6.1 ......................................................................................................................................................... 13
6.2 HTML Response........................................................................................................................... 13
7 Appendix C: Important Headers ......................................................................................................... 14

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

3 inneractive Connected Applications Integration Protocol

1 Table of changes
 Version 1.5
o Added table of different servlet targets
o Updated protocol version string
o Introduced HTML format responses
o Cleared up required fields for client side requests
 Version 1.5.1
o Cleared some inconsistencies
o Introduced support of distribution channels
 Version 1.5.2
o Moved distribution channel parameter to mandatory parameters.
o Added allowed values for Gender parameter
o Added documentation of W/H parameters
o Clarified the role of the Client Id value


http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

4 inneractive Connected Applications Integration Protocol

2 General Description

2.1 Overview
This document describes the protocol for partners to connect to the inneractive system, retrieving
optimized ads for mobile devices.

This protocol enables application developers to monetize their application by embedding ad

presentation functionality within their application.

The protocol is based on simple http requests – either GET or POST methods are supported, with
response in XML format.

This protocol enables application publishers to monetize their applications without embedding one of
the available inneractive SDKs.

2.2 Intended usage

Ad retrieval may be done directly by a client embedded within the application, or by server-to-server
communication – more suitable for always connected applications.

This protocol is intended for real time ad presentation, so batch retrieval is not supported – for each ad
presentation, a separate request must be made, supplying all required information. The life time of ads
delivered by this protocol is measured in minutes, and should not exceed 30 minutes. If an application is
open for longer periods of time, it should refresh the presented ads at regular intervals well under that
period.

2.3 Ad definition
A mobile ad in the scope of this protocol is comprised of either a banner image, an ad text, or a
combination of both, along with a click URL.

The presentation of the creative materials – text or image – is up to the application itself. Once the user
chooses to click an ad, the application should open the click URL in a browser.

Ad images are served according to MMA guidelines

(http://www.mmaglobal.com/mobileadvertising.pdf), using these guidelines to determine the correct
image size to be served to a specific client device.

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

5 inneractive Connected Applications Integration Protocol

3 Making a Request
Requests are made as simple HTTP calls to the inneractive server.

Parameters are passed as name-value pairs, either within the query string for the GET method, or in the
body of a post method. Parameters should be URL encoded once, so that they are passed correctly, but
no additional decoding is required when retrieved.

The content type of the requests should be application/x-www-form-urlencoded.

All input should be encoded in UTF-8 format.

Additionally, when the request is routed through the partner’s server, it is required that the server pass
all HTTP headers received from the application client, on to the inneractive server. These headers are
required to enhance the optimization process with as much data.

The base URL of the request is http://m2m1.inner-active.com/simpleM2M/

The target servlet depends on the requesting entity and the required response format:

XML HTML
Client app request clientRequestAd clientRequestHtmlAd
Server request requestAd requestHtmlAd

Thus, a request made by a client embedded in an application, requiring HTML response, should Be
directed at http://m2m1.inner-active.com/simpleM2M/clientRequestHtmlAd.

A request made by the server of a client/server application, requiring XML response, should be directed
at http://m2m1.inner-active.com/simpleM2M/requestAd.

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

6 inneractive Connected Applications Integration Protocol

3.1 Sample Requests

3.1.1 Client side request:
http://m2m1.inner-active.com/simpleM2M/clientRequestHtmlAd?aid=3DArts_CapJong&test=true

The UA string is taken from the standard header, and the client IP address is taken from the remote
address of the HTTP request.

Server side request

http://m2m1.inner-
active.com/simpleM2M/requestAd.jsp?aid=3DArts_CapJong&aix=0&ua=Mozilla%2F5.0
(SymbianOS%2F9.2%3B Series60%2F3.1 NOKIAN95 8GB%3B Profile%2FMIDP-2.1
Configuration%2FCLDC-1.1) AppleWebKit%2F525 (KHTML%2C like Gecko)
BrowserNG%2F7.1.18124&cip=194.153.110.160&test=1

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

7 inneractive Connected Applications Integration Protocol

3.2 Required Information

Name Description Comments
aid Application Id Provided by inneractive at
application registration
v Version string Currently: Sm2m-1.5.1

3.3 Required Information – Server to Server Requests

(requestAd, requestHtmlAd)
Name Description Comments
The user agent of the client
ua
device
Client IP – the IP address of the
cip
requesting device
Must be one of pre-defined
channels in the system, possible
po Distribution Channel (portal) values provided by innerActive.
For example, for the Android
Market the value should be 559.

For client side requests, these values will be taken from the standard HTTP headers.

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

8 inneractive Connected Applications Integration Protocol
3.4 Optional Information
Name Description
The client id of the specific
device, as previously supplied by
cid
the Inneractive system in a
response.
An application specific id – the id
eid of the requesting device in the
partner’s domain.
a User’s age
g User’s gender
w width
h height
mn User’s mobile number
Keywords relevant to this user’s
k Comma separated list.
specific session.
Category – a single word
c
description of the application.
http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive
Comments
This value is crucial for capping
and variation of ad serving.
The client application should
store the value received on
every response, and serve it as
part of consequent requests.
This allows us to try and serve a
variety of ads to the same client,
rather than the same ad over
and over again.
Allowed values:
M/m, F/f, Male, Female.
The screen resolution width of
the device.
Together with the “h”
parameter, useful for
determining the device type
when no meaningful UA was
found.
May significantly increase fill
rate!
The screen resolution width of
the device.
Together with the “w”
parameter, useful for
determining the device type
when no meaningful UA was
found.
May significantly increase fill
rate!
MSISDN format, with
international prefix
9 inneractive Connected Applications Integration Protocol

Location string – comma

l separated list of country, For example: US, NY, NY
state/province, city
GPS location – ISO code location
lg In latitude, longitude format.
data
Will always return a test
campaign.
test Test mode
Values for activating test mode –
case insensitive “true”, “1”.

These optional parameters may be used with any request type – client/server originated, and
HTML/XML formatted.

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

10 inneractive Connected Applications Integration Protocol

3.5 Headers
As stated above, when the request is made by the partner’s application server, all headers passed in the
original request from the client to the server should also be passed to the inneractive system, with the
exception of two headers:

 User agent, which is passed in its own parameter

 Accept, which should be passed as is, without the prefix noted below.

All such header names should be prefixed with “iA-“, and re-transmitted.

See appendix C for a list of important headers, which may greatly improve ad selection.

This is only valid for server generated requests (requestAd, requestHtmlAd).

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

11 inneractive Connected Applications Integration Protocol

4 Response
The response to an ad request is in either xml format (see Appendix A for a schema definition, Appendix
B for example responses) or an HTML format, according to the target URL.

4.1 XML Response

An XML response has the following format:

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

<tns:Response xmlns:tns="http://www.inner-active.com/SimpleM2M/M2MResponse"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.inner-active.com/SimpleM2M/M2MResponse
M2MResponse.xsd "
Error =" ">
<tns:Client Id=""/>
<tns:Ad>
<tns:Text>tns:Text</tns:Text>
<tns:URL>tns:URL</tns:URL>
<tns:Image>tns:ImageSource</tns:Image>
</tns:Ad>
</tns:Response>

The error attribute of the Response element may hold one of the values: “OK”, “Internal Error”, “House
Ad”, “Invalid Input”, or “Unknown App Id”.

The Text element, when included, will hold the text string to display for this ad.

The URL element holds the click URL.

The Image element, when included, will hold a link to the image.

4.2 HTML Response

A sample HTML Response is in the following form:
<a href="http://m2m1.inner-
active.com/simpleM2M/ClientUpdateStatus?cn=3DArts_CapJong&amp;oi=1&amp;v=18Ap
p&amp;ci=18043477&amp;s=39280801&amp;ed=2|5|4|1">
<img src="http://m2m1.inner-
active.com/simpleM2M/ClientMedia?ca=39280801&amp;in=banner1.png&amp;cn=3DArts
_CapJong" alt="Bring your mobile to life. Games, Themes, and much more."/>
<br/>Bring your mobile to life. Games, Themes, and much more.</a>

Please note that since the output is in XHTML, URLs are encoded (most
significantly, ampersands are represented as “&amp;”), and need to be decoded
before use.

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

12 inneractive Connected Applications Integration Protocol

5 Appendix A: XML Response Schema

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.inner-active.com/SimpleM2M/M2MResponse"
xmlns:tns="http://www.inner-active.com/SimpleM2M/M2MResponse"
elementFormDefault="qualified">

<element name="Response" type="tns:ResponseType"></element>

<complexType name="ResponseType">
<sequence>
<element name="Client" type="tns:ClientType"></element>
<element name="Ad" type="tns:AdType"></element>
</sequence>
<attribute name="Error">
<simpleType>
<restriction base="string">
<enumeration value="OK"></enumeration>
<enumeration value="House Ad"></enumeration>
<enumeration value="Internal
Error"></enumeration>
<enumeration value="Invalid Input"></enumeration>
<enumeration value="Unknown App
Id"></enumeration>
</restriction>
</simpleType>
</attribute>
</complexType>

<complexType name="AdType">
<sequence>
<element name="Text" type="string" maxOccurs="1"
minOccurs="0"></element>
<element name="URL" type="string" maxOccurs="1"
minOccurs="1"></element>
<element name="Image" type="string" maxOccurs="1"
minOccurs="0"></element>
</sequence>
</complexType>

<complexType name="ClientType">
<attribute name="Id" type="string"></attribute>
</complexType>
</schema>

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

13 inneractive Connected Applications Integration Protocol

6 Appendix B: Sample Responses

6.1 XML Response

<?xml version="1.0" encoding="UTF-8" ?>
<tns:Response Error="OK"
xmlns:tns="http://www.inner-active.com/SimpleM2M/M2MResponse"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.inner-active.com/SimpleM2M/M2MResponse
http://www.inner-active.com/Public/XML/SimpleM2M/M2MResponse.xsd ">
<tns:Client Id="4172860"/>
<tns:Ad>
<tns:Text></tns:Text>
<tns:URL>http://uk.inner-active.com/Server-
1.8X/ClientUpdateStatus?cn=test&amp;oi=1&amp;v=18App&amp;ci=4172860&amp;s=121
01615&amp;ed=2-5-4-1</tns:URL>
<tns:Image>http://inneActiveWebFrontEnd-1325703548.eu-west-
1.elb.amazonaws.com/simpleM2M/ClientMedia?ca=12101615&amp;in=banner1.png</tns
:Image>
</tns:Ad>
</tns:Response>

6.2 HTML Response

<a href="http://m2m1.inner-
active.com/simpleM2M/ClientUpdateStatus?cn=3DArts_CapJong&amp;oi=1&amp;v=18Ap
p&amp;ci=18043477&amp;s=39280801&amp;ed=2|5|4|1"><img src="http://m2m1.inner-
active.com/simpleM2M/ClientMedia?ca=39280801&amp;in=banner1.png&amp;cn=3DArts
_CapJong" alt="Bring your mobile to life. Games, Themes, and much
more."/><br/>Bring your mobile to life. Games, Themes, and much more.</a>

http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive

14 inneractive Connected Applications Integration Protocol

7 Appendix C: Important Headers

 x-forwarded-for
 x-network-info
 x-original-user-agent


http://www.inner-active.com | developers@inner-active.com | Follow us on Twitter: @inneractive