ADMAX SSP Integration Guide (Eng.)

ADMAX SSP Integration Guide (Eng.
)
Outline
This document defines click parameters and conversion/event postback, along with campaign offer list API & report API.
1. SSP Integration Process

a. Please contact ADMAX's admin or help@ad-max.co.kr to register & integrate as SSP partner.
b. Please provide the following;
e-mail address to register as SSP partner

Conversion and event postback URL
List of server IP that will send requests to ADMAX API
c. ADMAX's admin will register the provided server IP list as White IP and will issue "partner_key" and "partner_secret_key" for SSP API
use.
d. After "partner_key" and "partner_secret_key" are issued, get campaign offer list (Please refer to “2. Campaign Offer List API” for
more details).
e. If there is any campaign that you wish to run/participate, create URL by following “3. Campaign Pick” guide and generates click and
conversion by following “5. Click Parameters” guide.
f. If conversion occurs, ADMAX system will callback to the provided conversion/event postback URL by following “6. Conversion
Postback”.
2. Campaign Offer List API

SSP partners can get the campaign offer list once registered as SSP partner.
a. Defaults
Integration protocol uses HTTP 1.1.
Request Method supports only GET type and each parameter value needs to be delivered after urlencode processing.
Response will be in HTML and JSON.
Division API URL
Operation server https://ssp.ad-max.co.kr/ssp/campaign/list
b. Request parameters
Parameter Default Required Description Example

Value
timestamp O Unix timestamp second unit value when API 1483196400

is requested
eg) Java Code
long unixTime =
System.currentTimeMillis()
/ 1000L;
pakey O Issued "partner_key" after registering as SSP si.AbCdE

partner on ADMAX
paenc O Converted encrypted SHA1 and result to If "partner_secret_key" is
lower case hexadecimal after
combining "partner_secret_key" from ac03ee93d3f086c10bf819ebfee08516,
ADMAX and timestamp parameter
20b3b80b010cac210d7b26ef5b4fa5d98659dcb5
paenc = sha1(
partner_secret_key +
timestamp )
offset 1 Page number of campaign offer list 1
Minimum value : 1
limit 1000 Number of campaigns per page in campaign 1000

offer list
Minimum value : 1
Maximum value : 1000
c. Request example
Example of requesting campaign offer list
https://ssp.ad-max.co.kr/ssp/campaign/list?timestamp=1483196400&pakey=si.AbCdE&paenc=20b3b80b010cac210d7b
26ef5b4fa5d98659dcb5&offset=1&limit=1000
d. Response parameters
When requested in JSON (Content-Type: application/json; charset=UTF-8);
Parameter Description
retcode Response code
200 : Campaign offer list response
400 : Campaign offer list parameter error
401 : Timestamp, pakey, paenc authentication failure
403 : Request from unregistered IP
5XX : Internal server processing error
total_count Total number of campaigns
offset Requested page number of campaign offer list
limit Requested number of campaigns per page
campaign_list Campaign offer list
campaign_key Campaign identifier
ad_type Campaign type
CPI : Cost Per Install
CPS : Cost Per Sale (Get paid with % of purchase amount )
CPP : Cost Per Purchase (Get paid per number of purchases)
CPA : Cost Per Action (Get paid per user event such as login, registration, etc.)
campaign_name Campaign name

category Campaign category
Game : Category related game
Shopping : Category related shopping
Lifestyle : Category related lifestyle
Movie : Category related movie
Brand : Category related brands
Etc. : Others
None : Uncategorized
kpi KPI information
Specifies condition of conversion if ad_type is CPA
promotion_msg Campaign promotion phrase
icon_url Campaign icon image URL
Recommend SSP partners to DOWNLOAD if they want to use icon image
start_date Campaign start date (yyyy-MM-dd HH:mm:ss)
end_date Campaign end date (yyyy-MM-dd HH:mm:ss)
There is no end_date value in case of campaign with unlimited period. It only ends
upon separate request of advertiser.
total_volume Total volume of a campaign
"Total_volume" value is responded as 0 in case of a campaign with unlimited volume or

of a CPS campaign
total_remain_volume Total remaining volume of a campaign
"Total_remain_volume" value is responded as 0 in case of a campaign with unlimited

volume or of a CPS campaign
day_volume Total daily volume of a campaign
"Daily_volume" value is same as "total_volume" in case of a campaign with unlimited

daily volume
"Daily_volume" value is different from "total_volume" in case of a campaign with

limited daily volume
day_remain_volume Total remaining daily volume of a campaign
"Day_remain_volume" value is same as "total_remain_volume" in case of a campaign

with unlimited daily volume
"Day_remain_volume" value is different from "total_remain_volume" in case of

campaign with limited daily volume
earn Profits (KRW)
It is settlement amount per conversion for CPI, CPP, and CPA campaigns
earn_rate Settlement rate of campaign profit (%)
It is settlement rate that SSP partner will receive for each conversion for a CPS
campaign
allow_platform Platform that is allowed for campaign participation
Android : Android based platform
iOS : iOS based platform
Others : Other platforms (Windows, macOS, etc.)
image_url_list Campaign promotion image list

is_pick_limited Campaign with limited/unlimited participation
If "is_pick_limited" value is true, SSP partner is unable to participate through API and
needs to ask ADMAX's admin separately
is_pick Campaign participation
true : Participated campaign
false : Non-participated campaign
url_list List of campaign's click URL
"url_list" value only exists when "is_pick value" is true. Therefore, if "is_pick" value is
false, SSP partner should participate through API to get the URL
---- name Name of campaign's click URL
DEFAULT : Click URL that is originally issued
ALIAS : Additional click URL other than DEFAULT click URL for the same campaign
Others : Click URL with designated name in addition to DEFAULT click URL for the same
campaign
url Campaign's click URL
Please refer to "5. Click Parameters" for additional parameters
e. Response example
When requested in JSON;
"retcode": 200,
"total_count": 5,
"offset": 1,
"limit": 1000,
"campaign_list": [{
"campaign_key": "1234_5678",
"ad_type": "CPI",
"campaign_name": "Cocorun",
"category": "Game",
"kpi": "",
"promotion_msg": "",
"icon_url": "https://vegas-test-o.s3.amazonaws.com/image/campaign/icon/111.png",
"start_date": "2018-01-01 00:00:00",
"end_date": "2018-12-31 23:59:59",
"total_volume": 1000,
"total_remain_volume": 998,
"day_volume": 1000,
"day_remain_volume": 998,
"earn": 1000,
"allow_platform": [
"Android",
"iOS"
],
"image_url_list": [
"https://vegas-test-o.s3.amazonaws.com/image/campaign/adImage/1234/222.png"
],
"is_pick_limited": false,
"is_pick": true,
"url_list": [{
"name": "DEFAULT",
"url": "http://test.clk.caulyglobal.com/v.aaa"
},
"name": "ALIAS",
"url": "http://bs1n.io/v.bbb"
},
"name": "Test",
"url": "http://bs1n.com/v.ccc"
}]
},
"campaign_key": "1235_5679",
"ad_type": "CPS",
"campaign_name": "Coupeng - Nike basketball shoes",
"category": "Shopping",
"kpi": "",
"start_date": "2018-01-01 00:00:00",
"end_date": "",
"total_volume": 0,
"day_volume": 0,
"earn_rate": 10.05,
"allow_platform": [
"Android",
"iOS",
"Others"
],
"image_url_list": [],
"is_pick": true,
"url_list": [{
"name": "DEFAULT",
"url": "http://test.clk.caulyglobal.com/v.ddd"
}]
},
"campaign_key": "1236_5680",
"ad_type": "CPP",
"campaign_name": "Mabel fighters - Item purchases",
"category": "Shopping",
"kpi": "",
"start_date": "2018-06-15 00:00:00",
"end_date": "2018-12-31 23:59:59",
"day_volume": 100,
"earn": 2000,
"allow_platform": [
"Android"
],
"image_url_list": [
"https://vegas-test-o.s3.amazonaws.com/image/campaign/adImage/1236/555.png",
"https://vegas-test-o.s3.amazonaws.com/image/campaign/adImage/1236/666.png"
],
"is_pick": true,
"url_list": [{
"name": "DEFAULT",
"url": "http://test.clk.caulyglobal.com/v.eee"
},
"name": "ALIAS",
"url": "http://bit.ly/fff"
},
{
"name": "ALIAS",
"url": "http://bit.ly/ggg"
}]
},
"campaign_key": "1237_5681",
"ad_type": "CPA",
"campaign_name": "Home minus (Registration)",
"category": "Lifestyle",
"kpi": "Registration",
"promotion_msg": " Conversion for this campaign would be registration on landed

homepage. (Re-registration will be approved) Conversion can be
confirmed the next day. Reference to items that are not sold at Home minus are
prohibited.",
"start_date": "2018-03-22 00:00:00",
"end_date": "2018-12-31 23:59:59",
"day_volume": 10000,
"earn": 2200,
"allow_platform": [
"Android",
"iOS",
"Others"
],
"is_pick_limited": true,
"is_pick": true,
"url_list": [{
"name": "DEFAULT",
"url": "http://test.clk.caulyglobal.com/v.hhh"
}]
},
"campaign_key": "1238_5682",
"ad_type": "CPI",
"campaign_name": "White desert (Pre-registration)",
"category": "Game",
"kpi": "",
"promotion_msg": " Profit will be paid after campaign is ended. Preregister
with invalid phone number will be not paid.",
"start_date": "2018-07-01 00:00:00",
"end_date": "2018-12-31 23:59:59",
"day_volume": 100,
"earn": 1150,
"allow_platform": [
"Android",
"iOS"
],
"is_pick": false,
"url_list": []
}]
3. Campaign Pick
SSP partners can pick & run campaigns that are in the campaign offer list.
Newly picked campaign responses created campaign URL information, and already picked campaign creates additional click URL and
response all of click URL.
a. Defaults
Integration protocol uses HTTP 1.1
Type API URL
Operation server https://ssp.ad-max.co.kr/ssp/campaign/pick

Value

is requested
eg) Java Code
long unixTime =
/ 1000L;

partner on ADMAX

paenc = sha1(
partner_secret_key +
timestamp )
campaign_key O Campaign identifier 1234_5678

pick_url_name Designated name on additional click URL on
already participated campaign
If user participates for the

first time, name will be
created as DEFAULT even
if name is designated
c. Request example
https://ssp.ad-max.co.kr/ssp/campaign/pick?timestamp=1483196400&pakey=si.AbCdE&paenc=20b3b80b010cac210d7
b26ef5b4fa5d98659dcb5&campaign_key=1234_5678
410 : Campaign is not existed / not able to participate through API (Needs to request
admin)
url_list List of campaign's click URL
---- name Name of campaign's click URL
DEFAULT : Click URL that is originally issued
ALIAS : Additional click URL other than DEFAULT click URL for the same campaign
Others : Click URL with designated name in addition to DEFAULT click URL for the same
campaign
url Campaign's click URL
Please refer to "5. Click Parameters" for additional parameters
e. Response example
{
"retcode": 200,
"url_list": [{
"name": "DEFAULT",
"url": "http://test.clk.caulyglobal.
com/v.aaa"
},
"name": "ALIAS",
"url": "http://bs1n.io/v.bbb"
}]
4. Report API
SSP partners can check daily generated click & conversions of picked campaigns.
a. Defaults
Type API URL
Operation server https://ssp.ad-max.co.kr/ssp/campaign/report

Value

is requested
eg) Java Code
long unixTime =
/ 1000L;

partner on ADMAX

paenc =
sha1(partner_secret_key
+ timestamp)
start_date O Start date to search 2018-01-01
The duration of
"start_date" and
"end_date" can not
exceed a maximum of 14
days
end_date O End date to search 2018-01-02

The duration of
"start_date" and
"end_date" can not
exceed a maximum of 14
days
campaign_key Campaign identifier 1234_5678
c. Request example
https://ssp.ad-max.co.kr/ssp/campaign/report?timestamp=1483196400&pakey=si.AbCdE&paenc=20b3b80b010cac210d
7b26ef5b4fa5d98659dcb5&start_date=2018-01-01&end_date=2018-01-02&campaign_key=1234_5678
report_list Campaign report list
---- date Report date (yyyy-MM-dd)
campaign_key Campaign identifier
campaign_name Campaign name
click Number of clicks
conversion Number of conversions
earn Campaign's profit per conversion
e. Response example
{
"retcode": 200,
"report_list": [{
"date": "2018-01-02",
"campaign_key": "1234_5678",
"campaign_name": "COOCOORUN",
"click": 12,
"conversion": 1,
"earn": 1000
},
"date": "2018-01-01",
"campaign_key": "1234_5678",
"campaign_name": "COORUN",
"click": 75,
"conversion": 1,
"earn": 1000
}]
5. Click Parameters
After a campaign is picked and click URL is issued, SSP partner can deliver information with following parameters.
a. DEFAULTS
Request Method supports only GET type and each Parameter value needs to be delivered after urlencode processing.
Parameter Default Value Required Length Description
cp O 250 byte Click ID (unique identifier that is created by SSP partner at click occurrence)
sp_id 32 byte SSP partner's sub-partner identifier
ssp_id 32 byte SSP partner's sub-sub-partner identifier
sssp_id 32 byte SSP partner's sub-sub-sub-partner identifier
gid 36 byte Click generated user device's Google Advertising ID information
idfa 36 byte Click generated user device's Apple identifier for advertiser information
c. Request example
Setting with basic click parameters

http://bs1n.io/v.bbb?cp={SSP Partner's Click ID}
Setting with SSP partner's sub-partner or sub-sub-partner information included
http://bs1n.io/v.bbb?cp={SSP Partner's Click ID}&sp_id={SSP Partner's sub-partner ID}&ssp_id={SSP Partner's
sub-sub-partner ID}&sssp_id={SSP Partner's sub-sub-sub-partner ID}
Setting with SSP partner's sub-partner or sub-sub-partner information and device identifier included
http://bs1n.io/v.bbb?cp={SSP Partner's Click ID}&sp_id={SSP Partner's sub-partner ID}&ssp_id={SSP Partner's
sub-sub-partner ID}&sssp_id={SSP Partner's sub-sub-sub-partner ID}&gid={device ADID}&idfa={device IDFA}
6. Conversion Postback
If SSP partner registers conversion postback URL at ADMAX system, you will receive conversion postback when conversion occurs
through your click URL.
a. Defaults
SSP partner's server should respond Connection Timeout and Read Timeout within 3 seconds when sending postback.
b. Postback Macro
Macro Description Remarks
{cp} Click ID (Parameter value sent by SSP partner at the SSP partner needs to send value in cp parameter at
occurrence of a click) the occurrence of a click
{action} Customized event name
{ip} User device IP collected by Tracker Deliverable only if provided by Advertiser or Tracker
{gid} User device Google Advertising ID collected by Deliverable only if provided by Advertiser or Tracker
Tracker
{idfa} User device Apple identifier for advertisers collected Deliverable only if provided by Advertiser or Tracker
by Tracker
{rev} User in-app purchase amount information for CPS Deliverable only if provided by Advertiser or Tracker
and CPP campaigns
{currency} User in-app purchase currency information Deliverable only if provided by Advertiser or Tracker
{sp_id} Sub-Partner ID SSP partner needs to send sp_id parameter value at

the occurrence of a click
{ssp_id} Sub-Sub-Partner ID SSP partner needs to send ssp_id parameter value

at the occurrence of a click
{sssp_id} Sub-Sub-Sub-Partner ID SSP partner needs to send sssp_id parameter value

at the occurrence of a click
{country} User device country information at the occurrence Deliverable only if provided by Advertiser or Tracker
of a conversion completion
{platform} User device platform information at the occurrence Deliverable only if provided by Advertiser or Tracker
of a conversion completion
{install_time} Timestamp(seconds) at the occurrence of a convers Deliverable only if provided by Advertiser or Tracker
ion completion
c. Request example
Setting with basic click parameters

http://(SSP Partner conversion Postback URL)?cp={cp}
Setting with SSP partner's sub-partner or sub-sub-partner information and conversion postback included
http://(SSP Partner conversion Postback URL)?cp={cp}&sp_id={sp_id}&ssp_id={ssp_id}&sssp_id={sssp_id}
Setting with all information and conversion postback included

http://(SSP Partner conversion Postback URL)?cp={cp}&action={action}&ip={ip}&gid={gid}&idfa={idfa}&rev={rev}&curre
ncy={currency}&sp_id={sp_id}&ssp_id={ssp_id}&sssp_id={sssp_id}&country={country}&platform={platform}&install_tim
e={install_time}
7. Event Postback
If SSP partner registers event postback URL at ADMAX system, you will receive event postback when conversion and event occur
through your click URL.
a. Defaults
SSP Partner's server should respond Connection Timeout and Read Timeout within 3 seconds when sending postback.
b. Postback Macro
Macro Description Remarks
{cp} Click ID (Parameter value sent by partner at the SSP partner needs to send value in cp parameter at the
occurrence of a click) occurrence of a click
{action} Customize event name Deliverable only if provided by Advertiser or Tracker
{ip} User device IP collected by Tracker Deliverable only if provided by Advertiser or Tracker
{gid} User device Google Advertising ID collected by Tr Deliverable only if provided by Advertiser or Tracker
acker
{idfa} User device Apple identifier for advertisers Deliverable only if provided by Advertiser or Tracker
collected by Tracker
{rev} User in-app purchase amount information Deliverable only if provided by Advertiser or Tracker
{currency} User in-app purchase currency information Deliverable only if provided by Advertiser or Tracker
{sp_id} Sub-Partner ID SSP partner needs to send sp_id parameter value at the
occurrence of a click
{ssp_id} Sub-Sub-Partner ID SSP partner needs to send ssp_id parameter value at

the occurrence of a click
{sssp_id} Sub-Sub-Sub-Partner ID SSP partner needs to sssp_id parameter value at the

occurrence of a click
{country} User device country information at conversion Deliverable only if provided by Advertiser or Tracker
completion point
{platform} User device platform information at conversion Deliverable only if provided by Advertiser or Tracker
completion point
{event_tim Timestamp(seconds) at conversion completion Deliverable only if provided by Advertiser or Tracker

e} point
c. Request example
Setting with conversion postback

http://(SSP Partner event Postback URL)?cp={cp}&action={action}
Setting with SSP partner's sub-partner or sub-sub-partner's information and event postback included
http://(SSP Partner event Postback URL)?cp={cp}&action={action}&sp_id={sp_id}&ssp_id={ssp_id}&sssp_id={sssp_id}
Setting with all information and event postback included
http://(SSP Partner event Postback
URL)?cp={cp}&action={action}&ip={ip}&gid={gid}&idfa={idfa}&rev={rev}&currency={currency}&sp_id={sp_id}&ssp_id={s
sp_id}&sssp_id={sssp_id}&country={country}&platform={platform}&event_time={event_time}

ADMAX SSP Integration Guide (Eng.)

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

ADMAX SSP Integration Guide (Eng.)

Încărcat de

Drepturi de autor:

Formate disponibile

ADMAX SSP Integration Guide (Eng.

1. SSP Integration Process

b. Please provide the following;

e-mail address to register as SSP partner

2. Campaign Offer List API

Integration protocol uses HTTP 1.1.

Response will be in HTML and JSON.

Division API URL

Operation server https://ssp.ad-max.co.kr/ssp/campaign/list

Parameter Default Required Description Example

timestamp O Unix timestamp second unit value when API 1483196400

eg) Java Code

pakey O Issued "partner_key" after registering as SSP si.AbCdE

offset 1 Page number of campaign offer list 1

limit 1000 Number of campaigns per page in campaign 1000

Maximum value : 1000

Example of requesting campaign offer list

When requested in JSON (Content-Type: application/json; charset=UTF-8);

retcode Response code

200 : Campaign offer list response

400 : Campaign offer list parameter error

401 : Timestamp, pakey, paenc authentication failure

403 : Request from unregistered IP

5XX : Internal server processing error

total_count Total number of campaigns

offset Requested page number of campaign offer list

limit Requested number of campaigns per page

campaign_list Campaign offer list

campaign_key Campaign identifier

ad_type Campaign type

CPI : Cost Per Install

CPS : Cost Per Sale (Get paid with % of purchase amount )

CPP : Cost Per Purchase (Get paid per number of purchases)

campaign_name Campaign name

Game : Category related game

Shopping : Category related shopping

Lifestyle : Category related lifestyle

Movie : Category related movie

Brand : Category related brands

kpi KPI information

Specifies condition of conversion if ad_type is CPA

promotion_msg Campaign promotion phrase

icon_url Campaign icon image URL

Recommend SSP partners to DOWNLOAD if they want to use icon image

start_date Campaign start date (yyyy-MM-dd HH:mm:ss)

end_date Campaign end date (yyyy-MM-dd HH:mm:ss)

total_volume Total volume of a campaign

"Total_volume" value is responded as 0 in case of a campaign with unlimited volume or

total_remain_volume Total remaining volume of a campaign

"Total_remain_volume" value is responded as 0 in case of a campaign with unlimited

day_volume Total daily volume of a campaign

"Daily_volume" value is same as "total_volume" in case of a campaign with unlimited

"Daily_volume" value is different from "total_volume" in case of a campaign with

day_remain_volume Total remaining daily volume of a campaign

"Day_remain_volume" value is same as "total_remain_volume" in case of a campaign

"Day_remain_volume" value is different from "total_remain_volume" in case of

earn Profits (KRW)

earn_rate Settlement rate of campaign profit (%)

allow_platform Platform that is allowed for campaign participation

Android : Android based platform

iOS : iOS based platform

Others : Other platforms (Windows, macOS, etc.)

image_url_list Campaign promotion image list