# PUBLISHER INTEGRATION GUIDE

## 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

1. Contact our support team (<contact@mobiproud.com>) and register your app in MobiProud's dashboard and retrieve an "App Token" for the integration.
2. 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.
3. 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.
4. Publisher's server needs to parse the response, get related information according to requirements.
5. Test the integration, check if everything works fine.

![](https://2800767489-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M43bu8a04K_iY6z_qj0%2F-M44ZMMLPF6gxOFGqlqS%2F-M44dC7ZO02WvKin16lh%2Ffeed%20request.png?alt=media\&token=0a79ab75-727e-4022-819d-fc23e9e29d81)

## 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       | NO       | The page number you want to fetch (start from 1)                            |
| size       | NO       | The number of campaigns per page                                            |

{% hint style="info" %}

### 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.
{% endhint %}

## 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        | NO       | <p>Google Advertising ID. <br>If <code>device\_id\_required</code> is true, then you must pass this parameter.</p>                         |
| idfa        | NO       | <p>iOS IDFA</p><p>If <code>device\_id\_required</code> is true, then you must pass this parameter.</p>                                     |
| app\_name   | NO       | <p>The name or bundle of the mobile application.</p><p>If <code>app\_name\_required</code> is true, then you must pass this parameter.</p> |
| sub\_param2 | NO       | Any custom value you want to pass in.                                                                                                      |
| sub\_param3 | NO       | 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  | <p>true: available in all countries; <br>false: refer to 'countries' parameter</p> |
| 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 |
| category   | String | App categories such as Games, Life Style, and etc.                                   |
| platform   | String | Mobile Platform (ios, android)                                                       |

#### 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

```bash
{
	"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

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

Missing the Signature

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

Signature Mismatch

```bash
{“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:

1. Is the publisher's server receiving the response correctly?
2. Is the click URL working properly?(=tracked?)
3. Is the AppToken correctly mentioned in the GET method?
4. Is the publisher's server requesting too often (more often than 15 minutes)?
5. 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.
6. 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                                       |