Cheetah MediaLink AdServing API...

© MobPartner 2014 – All rights reserved

Cheetah MediaLink AdServing APIServer2Server

Your account manager will be happy to help you better understand or integrate this API. Do not hesitate

to contact our team at [email protected]

1

Revision History Version Date Owner/Contributor Comments

2.0 MobPartner Technical Team First release

2

Table of Contents Revision History ............................................................................................................ 1

1. Introduction to our AdServer API .......................................................................... 3 1.1 What does our API do? ................................................................................................................................... 3

1.2 Introduction to our Ad Units .......................................................................................................................... 4

1.2.1 Banners and interstitial ............................................................................................................................... 4

1.2.2 MobWall ...................................................................................................................................................... 4

1.2.3 MobWidget .................................................................................................................................................. 6

1.2.4 MobSearch .................................................................................................................................................. 7

1.2.5 MobStream .................................................................................................................................................. 8

1.3 Prerequisite: the pool ..................................................................................................................................... 8

2. Implement our Ad-‐server API .................................................................................... 9 2.1 Calling the API ................................................................................................................................................. 9

2.2 API responses ............................................................................................................................................... 10

2.3 Direct links .................................................................................................................................................... 11

2.3.1 Introduction ............................................................................................................................................... 11

2.3.2 Parameters ................................................................................................................................................ 11

2.3.3 Example ..................................................................................................................................................... 11

2.4 Expert mode ................................................................................................................................................. 12

2.4.1 Introduction ............................................................................................................................................... 12

2.4.2 General parameters ................................................................................................................................... 12

2.4.3 Configuring the result ................................................................................................................................ 12

2.4.4 Customizing ad unit response ................................................................................................................... 13

2.4.5 Example ..................................................................................................................................................... 13

2.5 AdUnit specific URL ....................................................................................................................................... 14

2.5.1 Introduction ............................................................................................................................................... 14

2.5.2 General parameters ................................................................................................................................... 14

2.6 Other parameters ......................................................................................................................................... 15

2.6.1 Automatic parameters ............................................................................................................................... 15

2.6.2 Sending unique device information ........................................................................................................... 15

3

1. Introduction to our AdServer API

1.1 What does our API do? The API is here to help you display advertisements for campaigns on your site or application that matches the characteristics of the visitor in order to improve conversion rate. These advertisements can be displayed through different ad units. Please refer to section 1.2 for a description of each ad unit. To use our API, you can use one of the following three methods:

A. Direct link to banner and campaign for quick HTML integration B. Expert mode for complex results C. Ad Unit specific URLs for easy to integrate xHTML results

Each method has its own set of parameters but also use common parameters. Please refer to the each section for corresponding list of parameters.

4

1.2 Introduction to our Ad Units

1.2.1 Banners and interstitial Make your banner space more interesting by using our bespoke banner settings or choose from the most convenient interstitial type for your app Key benefits

• Choose your settings: floating banners, anchor banners, top or bottom. All of these options are available for you to choose from

• High fill rate • Non-‐intrusive: respects every publishers user interface • Big variety of formats: from standard static interstitials to video

or interactive ad units

Example call: Interstitial 300x250 http://api.mobpartner.mobi/?pool=4192&disp_interstitial=1&size=300x250 When requesting a banner or an interstitial, you can select the size by using the parameter called “size”. The value can be a width or a width and height. If the size is set, only banners and interstitial corresponding perfectly to your request will be returned. If only the width is set, all sizes with the corresponding width will be returned, disregarding of their height. Sizes for banners: Sizes for interstitials: • 120x20 • 120x30 • 168x28 • 168x42 • 216x36 • 216x54 • 300x50 • 300x75 • 320x48 • 320x50 • 350x53 • 350x54

• 240x350 • 300x250 • 320x480 • 320x460 • 320x350 • 320x320 • 560x750 • 768x1024

Result:

1.2.2 MobWall

5

A non-‐intrusive ad format presenting a selection of free apps, customized by category, that offers users a choice of targeted offers. Key benefits

• 100% customizable from the number of apps displayed in the recommendations window to the color of buttons next to each app

• 100% remotely managed via our pool system • Non-‐intrusive: displayed as a full screen page once the user has clicked on a specific

button, tab, etc. • Higher eCPM than other ad-‐units • Unlock additional revenue stream: easy to integrate, you can add it to any button or

tab and does not compete with classic banner placement Example call: Mobwall http://mobwall.mobpartner.mobi/?pool=4192 This Ad Unit can’t be accessed by using the api.mobpartner.mobi URL. You have to go through the specific URL to have a result. It will always return an xHTML result that you can simply integrate in your site or application. Result:

6

1.2.3 MobWidget Created with content and editorial publishers in mind, MobWidget offers recommendations of apps based on the editorial content a user is currently reading Key benefits

• 100% customizable from the number of apps displayed in the recommendations window to the color of buttons next to each app

• Contextual: Displays apps from a certain category • 100% remotely managed via our pool system • Non-‐intrusive: ad added value ot the content • Up to 3x the CTR you can get from other standard ad-‐units

Example call: Mobwidget http://mobwidget.mobpartner.mobi/?pool=4192 This Ad Unit can’t be accessed by using the api.mobpartner.mobi URL. You have to go through the specific URL to have a result. It will always return an xHTML result that you can simply integrate in your site or application. Result:

7

1.2.4 MobSearch An innovative and exclusive ad unit which delivers contextually relevant app suggestions displayed below an app’s search field in real time as the user inputs their query. Key benefits

• Exclusive! Only with MobPartner you can now monetize a previously blank, untapped space in your app

• 100% customizable: make it your own! • Contextual app recommendation: apps targeted to what your user wants at

that precise moment • Non-‐intrusive: respects every publishers user interface

Example call: MobSearch http://api.mobpartner.mobi/?pool=4192&disp_mobsearch=1 Result:

8

1.2.5 MobStream A high converting in stream native ad unit which shows contextual app suggestions displayed in the content stream. Key benefits

• Full control on your ad unit • Monetize without compromising your user experience by tailoring the content

to your app • Say goodbye to accidental clicks = High CTR > High eCPM • Fully responsive: automatic device and geo location

Example call: Mobstream in 4x2 http://api.mobpartner.mobi/?pool=4192&disp_mobstream=1&mobstreamFormat=4x2 Result:

1.3 Prerequisite: the pool The first thing you need to do, as a MobPartner affiliate, is to get a valid pool Id from the MobPartner back office to use with the API. A pool is a collection of campaigns you wish to promote. To create one, go to the Traffic sources tab and then click on Create a new Pool.

You’ll have to choose a name and configure your pool before filling it with campaigns. Should you need any help selecting campaigns or configuring the pool to match your needs, please feel free to contact your account manager.

9

2. Implement our Ad-‐server API

2.1 Calling the API To use our API, you can use one of the following three methods:

A. Direct link to banner and campaign for quick HTML integration: This is the easiest and most direct solution:

• r.mobpartner.mobi is the url of the banner • c.mobpartner.mobi is the url of your link, to which you will redirect your traffic

Although it’s easy to integrate, it’s also limited as you can only get a banner with this method.

B. Expert mode for complex results: For a more complete and customizable solution, you can use the following URL: api.mobpartner.mobi This URL will provide an XML or JSON response depending on the value of the parameter output and the ad unit requested.

C. Ad Unit specific URLs for easy to integrate xHTML results:

Except for interstitials and mobstream, each ad unit can also be accessed by calling a URL specific to the ad unit:

• banner.mobpartner.mobi • mobwall.mobpartner.mobi • mobwidget.mobpartner.mobi • mobsearch.mobpartner.mobi

Each of these URLs will provide an XHTML response that you can directly use in your site or app.

10

2.2 API responses The result of an API call in XML or JSON, with the URL api.mobpartner.mobi will follow the following basic organization:

<root>

<promotion>

<click></click>

<banner></banner>

<interstitial></interstitial>

<mobstream></mobstream>

<mobsearch></mobsearch>

<campaign>

<id></id>

<name></name>

<logo></logo>

<category></category>

</campaign>

<app>

<id></id>

<name></name>

<baseline></baseline>

<url></url>

<thumbnail></thumbnail>

<companyName></companyName>

<rating></rating>

<lang></lang>

<price></price>

<priceCurrencyCode></priceCurrencyCode>

<priceCurrencySymbol></priceCurrencySymbol>

</app>

</promotion>

</root>

If you ask for more than one result, there will be one promotion node for each result. The nodes banner, interstitial, mobstream, mobsearch, app and campaign are present only if asked for with the corresponding parameters.

11

2.3 Direct links

2.3.1 Introduction This is the easiest and most direct solution: r.mobpartner.mobi is the url of the banner c.mobpartner.mobi is the url of your link, to which you will redirect your traffic Although it’s easy to integrate, it’s also limited as you can only get a banner with this method.

2.3.2 Parameters If you need to pass some parameters that you expect to get back in your callback after each transaction, please use the TID parameters (tid1 to tid6). You can pass whatever you want in those parameters but keep in mind we won’t calculate statistics on those. However if you would like to pass a specific information on which you expect us to calculate statistics (for example: ad placement, sub-‐affiliate, page name…), you can use the subid parameter.

2.3.3 Example Here is a simple example of an HTML integration: <a href=”c.mobpartner.mobi?pool=4192”><img src=”r.mobpartner.mobi?pool=4192”></a> Make sure to add the pool parameter to both URL with the same value.

Name Description Comment pool ID of your affiliate pool the AdServer will use to

provide campaigns. This parameter is mandatory and its type is an integer.

tid1, tid2, tid3, tid4, tid5, tid6

You can send any value you want in these. It will be stored in MobPartner database and can be returned in your callback if desired. Examples of data you may want to send: click id, offer id in your system, transaction id…

The type is VARCHAR 255 and its value needs to be URL encoded

subid Any value you need to have in MobPartner statistics. For example: sub-‐affiliate value. If you need a unique ID that is returned in your callback, please use one of the tid instead.


12

2.4 Expert mode

2.4.1 Introduction This method of integration offers a more complete and customizable solution by using the following URL: api.mobpartner.mobi This URL will provide an XML or JSON response depending on the value of the parameter output and the ad unit requested.

2.4.2 General parameters If you need to pass some parameters that you expect to get back in your callback after each transaction, please use the TID parameters (tid1 to tid6). You can pass whatever you want in those parameters but keep in mind we won’t calculate statistics on those. However if you would like to pass a specific information on which you expect us to calculate statistics (for example: ad placement, sub-‐affiliate, page name…), you can use the subid parameter.

2.4.3 Configuring the result Name Description Comment disp_click Display the click URL for the mobstream or

mobsearch. The type is Boolean.

disp_banner, disp_interstitial, disp_mobstream, disp_mobsearch

Provides a banner, interstitial, the MobStream, or the MobSearch

The type is Boolean. For disp_mobsearch the parameter output has to be set to json.

disp_campaign Provides information about the campaign in your result.

The type is Boolean.








13

disp_campaign_keywords

Provides the keywords associated with the campaign displayed.


disp_campaign_category

Provides the list of categories of the campaign in your result.


disp_payout Provides the payout of the campaign. The type is Boolean.

disp_app If the campaign links to an application, provides information about the application.


disp_app_screenshots Provides screenshots URL of the application. The type is Boolean. disp_config Provides the configuration of each of your ad

units. The data displayed depends of the ad unit.


output Selects the format of the result This parameter can only be used with api.mobpartner.mobi. Values authorized are: JSON, XML

output_nb Sets the number of results expected. Each result will be shown in a distinct promotion tag.

Default value is 1, maximum is 10

2.4.4 Customizing ad unit response Name Description Comment content_lang Force every text to be in specific language. This

only changes the displayed text and won't affect the availability of a campaign.

The expecting value is the two-‐letters code of the language (iso 3166-‐1).

mobstreamFormat Changes the format of the mobstream. Values are: 2x2, 2x3, 4x1, 4x2, or 4x3. Default value is defined by Ad Unit settings.

interstitialDisplayType Changes the type of interstitial. Values are: video, image, interactive. Default value is defined by Ad Unit settings.

It is important to note that not all campaigns have an interstitial for each type (video, image, interactive). Please refer to your account manager or the campaign manager for information on what is available.

2.4.5 Example

14

In this example, we’re requesting both a banner and an interstitial along with the campaign info for the result. We want the result in XML http://api.mobpartner.mobi/?pool=4192&disp_banner=1&disp_interstitial=1&disp_campaign=1&output=xml Here is what you would get:

2.5 AdUnit specific URL

2.5.1 Introduction Except for interstitials and mobstream, each ad unit can also be accessed by calling a URL specific to the ad unit:

• banner.mobpartner.mobi • mobwall.mobpartner.mobi • mobwidget.mobpartner.mobi • mobsearch.mobpartner.mobi

Each of these URLs will provide an XHTML response that you can directly use in your site or app.

2.5.2 General parameters If you need to pass some parameters that you expect to get back in your callback after each transaction, please use the TID parameters (tid1 to tid6). You can pass whatever you want in those parameters but keep in mind we won’t calculate statistics on those. However if you would like to pass a specific information on which you expect us to calculate statistics (for example: ad placement, sub-‐affiliate, page name…), you can use the subid parameter.



15

2.6 Other parameters These parameters can be used for every URL listed above.

2.6.1 Automatic parameters The API will get the following values from the HTTP headers. However if the call is not made by the end-‐user device or if the HTTP headers are unavailable for some reason, you will need to pass those values using the following parameter: Name Description Comment ip Original IP address of the end user The IP must remain in the dotted

format. Example: 46.218.39.170

ua User agent of the end user. This has to be URL encoded. Example: Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%205_0%20like%20Mac%20OS%20X)%20AppleWebKit%2F534.46%20(KHTML%2C%20like%20Gecko)%20Version%2F5.1%20Mobile%2F9A334%20Safari%2F7534.48.3

lang Language setting of the end user The value is the two-‐letters code of the language (iso 3166-‐1)

headers HTTP headers of the end user. This is the URL encoding of a PHP serialized headers array.

Example in PHP: $array=apache_request_headers(); $head=addslashes(urlencode(serialize($array)));

2.6.2 Sending unique device information For tracking purposes, some campaigns may require one of these parameters. Please refer to the campaign description to know more about the tracking solution used.






16

In any case, if you can provide any of these for your visitors, we highly recommended that you do. Name Description Comment macaddress MAC address of the end user device. This can be required for both iOS

and Android campaigns.

idfa IDFA of the end user device. This can only be required for iOS campaign.

androidid Android ID of the end user device. This can only be required for Android campaign.

gaid Google Advertiser ID of the end user device. This can only be required for Android campaign.

Cheetah MediaLink AdServing API...

Documents

Transcript of Cheetah MediaLink AdServing API...