M2M Server-To-Server Protocol Definition v 1.5.2

inneractive

inneractive Server to Server

Integration Protocol Technical Definitions

Rami Citrom ([email protected])

8/11/2010

Version 1.5.2

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

2 inneractive Connected Applications Integration Protocol

http://www.inner-active.com | [email protected] | Follow us on Twitter: @inneractive

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



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



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.mmaglobal.com/mobileadvertising.pdf



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://m2m1.inner-active.com/simpleM2M/

http://m2m1.inner-active.com/simpleM2M/clientRequestHtmlAd

http://m2m1.inner-active.com/simpleM2M/requestAd



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://m2m1.inner-active.com/simpleM2M/clientRequestHtmlAd?aid=3DArts_CapJong&test=true



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)

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


ua The user agent of the client device

cip Client IP – the IP address of the requesting device

po Distribution Channel (portal)

Must be one of pre-defined channels in the system, possible values provided by innerActive. For example, for the Android Market the value should be 559.



3.4 Optional Information


cid

The client id of the specific device, as previously supplied by the Inneractive system in a response.

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.

eid An application specific id – the id of the requesting device in the partner’s domain.

a User’s age

g User’s gender Allowed values: M/m, F/f, Male, Female.

w width

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!

h height

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!

mn User’s mobile number MSISDN format, with international prefix

k Keywords relevant to this user’s specific session.

Comma separated list.

c Category – a single word description of the application.



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

HTML/XML formatted.

l

Location string – comma separated list of country, state/province, city

For example: US, NY, NY

lg GPS location – ISO code location data

In latitude, longitude format.

test Test mode

Will always return a test campaign. Values for activating test mode – case insensitive “true”, “1”.



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



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&oi=1&v=18Ap

p&ci=18043477&s=39280801&ed=2|5|4|1">

<img src="http://m2m1.inner-

active.com/simpleM2M/ClientMedia?ca=39280801&in=banner1.png&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 “&”), and need to be decoded

before use.

view-source:http://m2m1.inner-active.com/simpleM2M/ClientUpdateStatus?cn=3DArts_CapJong&oi=1&v=18App&ci=18043477&s=39280801&ed=2%7C5%7C4%7C1



view-source:http://m2m1.inner-active.com/simpleM2M/ClientMedia?ca=39280801&in=banner1.png&cn=3DArts_CapJong





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"


<element name="Image" type="string" maxOccurs="1"


</sequence>

</complexType>

<complexType name="ClientType">

<attribute name="Id" type="string"></attribute>

</complexType>

</schema>



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&oi=1&v=18App&ci=4172860&s=121

01615&ed=2-5-4-1</tns:URL>

<tns:Image>http://inneActiveWebFrontEnd-1325703548.eu-west-

1.elb.amazonaws.com/simpleM2M/ClientMedia?ca=12101615&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&oi=1&v=18Ap

p&ci=18043477&s=39280801&ed=2|5|4|1"><img src="http://m2m1.inner-

active.com/simpleM2M/ClientMedia?ca=39280801&in=banner1.png&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>









7 Appendix C: Important Headers

x-forwarded-for

x-network-info

x-original-user-agent

Documents

M2M Server-To-Server Protocol Definition v 1.5.2