PUBLISHER INTEGRATION GUIDE

Version 1.4

INTRODUCTION

The MobiProud Bulk API is designed for publishers who want to receive offer metadata in an aggregated format. By using the bulk API, the publishers can easily serve appropriate campaigns to their audience.

INTEGRATION FLOW

Contact our support team ([email protected]) and register your app in MobiProud's dashboard and retrieve an "App Token" for the integration.
The Publisher's server needs to send out an HTTP GET request to MobiProud's server, with the App Token provided for a list of campaigns.
The MobiProud API returns a list of relevant campaigns in JSON format. Each campaign includes its basic information such as title, description, set of images, click URL etc.
Publisher's server needs to parse the response, get related information according to requirements.
Test the integration, check if everything works fine.

THE BULK API INTEGRATION

Request Format

The Request method is a simple GET request in the following format:

http://feed.mobiproud.com/api/v1/offers/list.json?app_token={AppToken}&platform={AppPlatform}&page={page}&size={PageSize}

Request Parameters

Name

Required

Description

app_token

YES

The app token generated for the publisher given by MobiProud's Support Team

platform

YES

OS the application is running on (ios/android)

page

The page number you want to fetch (start from 1)

size

The number of campaigns per page

Request Frequency

We recommend requesting campaigns on an hourly basis, ideally at an arbitrary time (not exactly at the top of every hour). DO NOT send requests more often than 15 minutes.

Tracking Link

Appending Parameters

Append the parameter in one of the available sub params(sub_param1 ~ sub_param5) at the end of the click_url.
The only available sub_params for your use are: sub_param1, sub_param2 and sub_param3.
If device_id_required is true, it means you have to pass your IDFA and GAID.
If app_name_required is true, it means you have to pass app name.

Parameters in Tracking Link

Name

Required

Description

sub_param1

YES

Your custom value passed, normally click ID

sub_aff

YES

Your sub source's ID

gaid

Google Advertising ID. If device_id_required is true, then you must pass this parameter.

idfa

iOS IDFA

If device_id_required is true, then you must pass this parameter.

app_name

The name or bundle of the mobile application.

If app_name_required is true, then you must pass this parameter.

sub_param2

Any custom value you want to pass in.

sub_param3

Any custom value you want to pass in.

Click URL Examples

http://track.mobiproud.com/data/click?cid=6AZbeg2vTfemvpQ6fnnI5g&affid=H3IsEiyiQMOoE4pIF96YyQ&sub_param1=SAMPLE_CLICK_ID_0001&sub_aff=1234&idfa=ABCD-EFGH-WXYZ&app_name=TestAppName1

http://track.mobiproud.com/data/click?cid=6AZbeg2vTfemvpQ6fnnI5g&affid=H3IsEiyiQMOoE4pIF96YyQ&sub_param1=SAMPLE_CLICK_ID_0002&sub_aff=5678&gaid=WXYZ-OPQR-MNOP&app_name=TestAppName2

RESPONSE

The Content of the Response

The JSON response from MobiProud's server is composed of a list of offers:

Name

Description

app_details

general information about the application.

offers

offer information such as payout, country, devices and etc.

creatives

elements for the advertisement

The above segments are described in detail below as they occur in the exact same order in the JSON response.

`offers` Segment

Name

Type

Description

click_url

String

Tracking link of the offer

countries

String

Countries where the offer is available

devices

String

Mobile device type (iphone, ipad & android)

global

String

true: available in all countries; false: refer to 'countries' parameter

payout

Float

The revenue($) of the offer

device_id_required

Boolean

IDFA or GAID is required to be passed in tracking link

app_name_required

Boolean

App name is required is required to be passed in tracking link

`app_details` Segment

Name

Type

Description

bundle_id

String

Unique ID in the market. App ID for iOS an offer or bundle name for an android offer

creatives Segment

Name

Type

Description

banner_url

String

Banner CDN url

cta_text

String

Call To Action text

description

String

App description

icon_url

String

Icon CDN url

title

String

App tilte

Sample Response

{
	"offers": [
	{
		"app_details": {
			"platform": "android",
			"category": "Lifestyle",
			"total_ratings": 66955,
			"developer": "Survey Sampling Intl. LLC", "name": "QuickThoughts",
			"bundle_id": "com.surveysampling.mobile.quickthoughts", "store_rating": 4.1,
			"version": "2.14.2",
			"size": "N/A"
		},
		"click_url": "http://track.mobiproud.com/data/click? cid=Ggi0Ocju4l&affid=12345",
		"device_id_required": false, "app_name_required": true, "min_os_version": "4.0.3", "global": false,
		"devices": ["Android"], 
		"countries": ["NL"],
		"campaign_id": "Ggi0Ocju4l", 
		"creatives": {
			"banner_url": "http://feed.mobiproud.com/assets/27342", "title": "QuickThoughts",
			"description": "",
			"icon_url": "http://feed.mobiproud.com/assets/653778",
			"cta_text": "Install",
			"portrait_banner_url": "http://feed.mobiproud.com/assets/27343"
		},
		"payout": 1.25 
	},
	{
		"app_details": {
			"platform": "android",
			"category": "Lifestyle",
			"total_ratings": 66955,
			"developer": "Survey Sampling Intl. LLC", 
			"name": "QuickThoughts",
			"bundle_id": "com.surveysampling.mobile.quickthoughts", 
			"store_rating": 4.1,
			"version": "2.14.2",
			"size": "N/A"
		},
		"click_url": "http://track.mobiproud.com/data/click?cid=8AKp4JBpA7&affid=12345",
		"device_id_required": true, 
		"app_name_required": true, 
		"min_os_version": "4.0.3", 
		"global": false,
		"devices": ["Android"], 
		"countries": ["FR"],
		"campaign_id": "8AKp4JBpA7", 
		"creatives": {
			"banner_url": "http://feed.mobiproud.com/assets/27342", 
			"title": "QuickThoughts",
			"description": "",
			"icon_url": "http://feed.mobiproud.com/assets/653778", 
			"cta_text": "Install",
			"portrait_banner_url": "http://feed.mobiproud.com/assets/27343"
			},
		"payout": 0.62 
	}],
	"from": 1,
	"to": 2,
	"status": 0,
	"page": 1, 
	"totalCount": 1577, 
	"totalPages": 158, 
	"size": 2
}

Error Response

Missing Required Parameters

{“status”: -6, "msg": "Missing Required Parameters"}

Missing the Signature

{“status”: -8, "msg": "Missing Signature Parameter"}

Signature Mismatch

{“status”: -9, "msg": "Signature Does Not Match"}

POSTBACKS

With postback conversion tracking, you can see conversion reporting without having to rely on browser cookies. Postback conversion tracking uses server-to-server calls to pass information between two systems. In order to pass a certain parameter in postback, you can send your data (example: click_id) to us in the following way:

Append your variable in one of the available sub parameters(sub_param1 , sub_param2 and sub_param3) at the end of the click_url.
The sub_param4 and sub_param5 parameters are reserved for our use. Any data sent through these 2 parameters will be ignored.
If device_id_required is true, the IDFA and GAID must be set.

Postback Placeholders

Placeholder

Description

{sub_param1}

Your click ID

{campaign_id}

The unique ID of the campaign. If developer receives the same order ID, it means the order already exists

{app_id}

Application ID

{app_name}

The name of the campaign

{sub_source}

The sub source or affiliate

{payout}

The revenue($) that developer can earn

{sub_param2}

Custom value 2

{sub_param3}

Custom value 3

{gaid}

Google Advertising ID

{idfa}

iOS IDFA

During the invocation of your callback URL these placeholders will be substituted with the values you provided in the invocation of the MobiProud tracking url.

INTEGRATION TEST

If the server is not responding correctly, please check items listed below:

Is the publisher's server receiving the response correctly?
Is the click URL working properly?(=tracked?)
Is the AppToken correctly mentioned in the GET method?
Is the publisher's server requesting too often (more often than 15 minutes)?
Since there are frequent changes in the available offers list the publisher is responsible to generate the request every hour. In case an offer was returned in a previous response and is no longer in the new response, the offer must have been removed from production.
Contact your account manager to get access to the Reporting Dashboard, where you will be able to monitor the performance of your account.

VERSION HISTORY

Date

Version

Revision Content

2018.06.26

v1.4

Added app_name_required parameter and app_name description

2018.05.20

v1.3

Added description of click URL

2018.03.12

v1.2

Added support for sub_aff parameter in track URL

2018.02.15

v.1.1

Some typo fixes; Added sample response

2017.08.01

v1.0

First published version

Last updated 5 years ago

Was this helpful?

INTRODUCTION

INTEGRATION FLOW

THE BULK API INTEGRATION

Request Format

Request Parameters

Request Frequency

Tracking Link

Appending Parameters

Parameters in Tracking Link

Click URL Examples

RESPONSE

The Content of the Response

offers Segment

app_details Segment

creatives Segment

Sample Response

Error Response

POSTBACKS

Postback Placeholders

INTEGRATION TEST

VERSION HISTORY

`offers` Segment

`app_details` Segment