JUNE 2013

PUBLISHER INTEGRATION

To integrate SupersonicAds monetization solution with your application or site, please

follow this document. For questions or comments about this document, please contact Tali

Pashinsky (tali.p@supersonicads.com).

IMPORTANT NOTICE: SupersonicAds offers unmatched fraud control technology. In order to

avail of it and be notified in real time about any fraudulent activity committed by your users,

you must support the Negative Callback functionality described in Section 3. Failure to do so

may result in users earning and spending invalid virtual goods which do not represent valid

revenue credited to you.

ADDING A NEW SITE/APPLICATION

1. Login to our web site.

2. Approve terms and conditions

3. Press the "Add new" link in order to define each app/site that you wish to

add.

4. For each app/site, please fill in the following fields:

a. Type – Social network application / site / software.

b. Industry –The industry that best describes your application; MMO, Social

App, Casual Game or Virtual World.

c. Name – your app/site title. Please note that the name of your application is

publicly viewable so please make sure to provide a full and clear name (no

initials or internal references).

d. Network –the social network in which your application is bounded to (e.g.

Facebook, MySpace, Bebo, etc.). If your application handles its own user

base and doesn’t share the user IDs with other applications / platforms, or

uses social network user IDs, specify the network as “other”. However, if

your application is hosted or presented within a platform (e.g. a game

network or game platform), where a unique user ID in one application is

applicable in another application, even if it is not a known social network,

please specify a network name in the “custom network” field in order to

apply our cross platform optimization and anti-fraud services.

e. Application Id / Site URL– your application's unique identifier, as given to

you by the social network / your site's URL.

f. Target audiences – a collection of fields which can help our system optimize

your media. This isn't mandatory, but we highly recommend you provide

this information as it will increase your revenue and your user engagement.

g. Currency name – your virtual currency's name, in plural form (e.g. Tokens)

h. Currency conversion rate – the amount of your currency coins awarded per

1 USD. (For example: when choosing the rate 20, 1 USD will be converted to

20 of your currency coins). Since the minimal number of awarded currency

cannot be lower than 1, we strongly recommend setting a conversion rate

which is at least 1:10. You can change this conversion rate later if you are

unsure of the optimal value to use for your application (this can be modified

freely at any given time through your account, without replacing any code in

your game/application).

i. Logo URL – 3 links to your application's logo (small, medium and big).

j. Favicon URL – link to your application's favicon.

k. Private key – a custom string which will be used to hash each callback call

and other sensitive information. You can use it in order to verify the

authenticity of callback events. This is not a mandatory field, but we

recommend using it.

l. Callback URL - the HTTP GET script to be called from our servers in order to

inform you about a commission event. Here is an example for a possible

callback URL string:

http://www.myapplication.com/processCommissions?applicationUserId=[US

ER_ID]&rewards=[REWARDS]&eventId=[EVENT_ID]

The URL must include the following place holders, which can be located

anywhere in your URL, according to your settings:

1. "[USER_ID]" – the identification of the user to be credited. (Note

that the URL-encoded form will be passed in this placeholder (for

example, "123%40abc.com" rather than "123@abc.com").

2. "[REWARDS]" - the amount of points to be credited.

3. "[EVENT_ID]" – a unique identifier of the commission event,

represented as MD5 string (32 alphanumeric characters).

4. Optional place holders:

[COMMISSION_ORIGIN] – values will be "support" if it came from SSA support team, or "real" if it came from an advertiser or direct payment provide

[APPLICATION_ID] - the application id

[ITEM_NAME] - the item that has been granted to the user (in case publisher choose to grant VG and not VC)

If the publisher choose to credit items, the [ITEM_NAME] is mandatory.

m. Admin user id – your personal user Id in this application/site. Offers that are

presented to this particular user id can be manipulated for testing purposes.

This is not a mandatory field. Don't URL-encode this user ID (for example,

enter "123@abc.com" rather than "123%40abc.com").

For more information, please refer to the Callback functionality section in this

document

Click on submit and find the URLs and JS tags

EMBEDDING THE IFRAME

1. In the Setup tab under Code Generator you can find the iFrame url and JS tags for

the offer wall and display ads

a. Offer Wall – a relatively large section for displaying offers associated with

your app/site.

b. Display Ad – a single banner ad size that can be presented on any of your

app/site pages. All sizes are supported – modified freely by you.

c. Display Ad using JS – please read “Display Ad - JS Delivery” on page 16.

2. When placing those URLs, please replace the "[USER_ID]" place holder with the

given unique identification of the logged in user. This string can contain up to 32

alphanumeric characters, and it will be passed back in its exact form to the callback

URL that you have specified. Please pass us the real user identification in order to

enjoy critical services (such as optimizations, anti-fraud, capping, etc.)

3. applicationUserIdSignature – publishers should add this parameters to the offer

wall iFrame URL - it is the md5 value of [applicationKey] [applicationUserId], and

[YOUR_PRIVATE_KEY] (private key is being set when publisher define a new app) –

For more information and to test your hash value – login to your account->Setup-

>API.

4. For the Single Banner and the Video Banner, it is also required to replace the

[BANNER_SIZE] tag with the requested banner size (for example: 468x60).

CALLBACK FUNCTIONALITY (PLEASE READ CAREFULLY)

1. The system will automatically add two parameters to the HTTP callback URL:

a. timestamp – a string representation of the exact timestamp in which this

callback has been called, in the following format: [4 digit year][2 digit

month][2 digit day][2 digit hour][2 digit minute]. (e.g. "201001021455"

stands for January 2, 2010 14:55).

b. signature – an MD5 hash string based on sensitive parameters, which you

can use in order to verify that the callback came from our system. This key is

generated automatically based on the following formula:

md5([TIMESTAMP][EVENT_ID][USER_ID][REWARDS][PRIVATE_KEY]). The

[USER_ID] element is the URL-decoded value of the userID (for example,

"123@abc.com" rather than "123%40abc.com"). The [PRIVATE_KEY]

element is the exact string that you supplied when you defined your

application/site. By generating MD5 hash string using the very same

parameters on your side and comparing it to the value in the signature

parameter that you got from us, you can safely authenticate each callback

event.

2. Whenever a commission event is generated, our server will call your callback URL

and provide you with the necessary information in order to credit the relevant user.

Our server expects to receive a valid HTTP response with status 200 (Ok), where the

"[EVENT_ID]:OK" string appears somewhere in the HTTP response - We will keep

calling this URL periodically for every commission until we received this valid

respond - Please note - you need to rely on the [EVENT_ID] parameter and ignore

multiple calls for the very same commission – please refer to section #4 for more

info.

Here is an example of a typical response:

<xml>

<status> dae8e6cf42b1357f8652ad6ecb5b24f1:OK</status>

</xml>

Thanks to this methodology, temporary communication problems won't prevent

crucial information from reaching its destination. Please note that our server will

stop informing your server about a particular commission after 5 hours of failures.

3. Once a commission notification has been failed three times, the system will

automatically send you an alert with all the details by email. We cap these alert

emails to one per day.

4. Important: If a timeout is reached (60 seconds), the HTTP call will be considered an

error and a follow up callback will be made. In order to prevent situations of faulty

extra credits as a result of timeouts, you need to rely on the [EVENT_ID] parameter

and ignore multiple calls for the very same commission. As a rule, our system will

never call the same commission with the same [EVENT_ID] more than once unless a

previous attempt yielded an HTTP error of any kind or if the "[EVENT_ID]:OK" string

has not been detected somewhere in the HTTP callback response.

5. If you wish to secure callbacks even more, you may reject any calls which are not

originated from the following IP addresses:

79.125.5.179

79.125.26.193

79.125.117.130

176.34.224.39

176.34.224.41

176.34.224.49

6. You can test callbacks by simulating a commission event to your servers, based on

the callback settings that you have filled for each application. To do so, go to the

Setup page and click on the relevant link near the Callback Status field (the first field

on the list).

7. Here is a PHP sample code which demonstrates a typical callback handler. All you

need to do is implement the alreadyProcessed() and doProcessEvent() functions and

set the [YOUR_PRIVATE_KEY] string:

// get the variables

$userId = $_GET['applicationUserId'];

$eventId = $_GET['eventId'];

$rewards = $_GET['rewards'];

$signature = $_GET['signature'];

$timestamp = $_GET['timestamp'];

$privateKey = ‘[YOUR_PRIVATE_KEY]’;

// validate the call using the signature

if (md5($timestamp.$eventId.$userId.$rewards.$privateKey) != $signature){

echo "Signature doesn’t match parameters";

return;

}

// check that we haven't processed the very same event before

if (!alreadyProcessed($eventId)){

// grant the rewards

doProcessEvent($eventId, $userId, $rewards);

}

// return ok

echo $eventId.":OK";

FRAUD CONTROL

We strongly recommend sending us the following parameters:

applicationUserCreationDate - the date in which the user has created his account. Must be in the yyyy-mm-dd format

applicationUserCreationDateSignature - the md5 hashing of the following strings: [applicationUserId][applicationUserCreationDate][applicationPrivateKey]

Publishers that send us this info significantly improve fraud detection by helping us identify fraudulent user behavior. We are then able to send advertisers high quality traffic which results in less charge backs and higher eCPMs.

IMPROVED TARGETING We strongly recommend sending us the following parameters:

applicationUserGender – The gender of the user. We accept these values : male|female

applicationUserAgeGroup – The age bracket of the user. We accept these values:

Value Age

0 Unknown

1 13-17

2 18-20

3 21-24

4 25-34

5 35-44

6 45-54

7 55-64

8 65+

Sending us these parameters will allow us to better target your userbase. Delivering more relevant offers which will increase conversions and revenue.

NEGATIVE CALLBACK FUNCTIONALITY (PLEASE READ CAREFULLY)

Publishers interested in being automatically notified about chargebacks and fraud

attempts can provide us with a "negative callback" URL string, which is based on the

same syntax as the regular callback URL. Our system will fire these events whenever

there is fraud, chargebacks or fraud attempts.

As a result, publishers can automatically deduct credits from offending users or take

any means against him/her.

Please note that the [EVENT_ID] passed in the negative callback is identical to the

[EVENT_ID] that has been previously passed on the regular callback of the relevant

completion. When implementing the negative callback, you should save this value

and avoid taking the same action twice if a negative callback call has been fired

more than once with the same [EVENT_ID].

Similar to the regular callback call, your negative callback should return the

[EVENT_ID]:OK string in order to signal SupersonicAds that the chargeback has been

successfully processed.

ADVANCED SETTING (OPTIONAL)

1. Custom parameters – you can append any number of custom parameters to the URL

of each delivery type (Offer Wall, Single Banner, and Video Banner) and have them

included in the callback sent back to you upon a successful commission. You may

include any number of parameters in any length using all type of characters as long

as it is properly encoded based on the standard URL syntax. Each custom parameter

should have the “custom_” prefix, for example: custom_player=flash&

custom_session=a45bcf&custom_key=453fjew59f

2. SSL support – if needed, we can serve the offers via the HTTPS protocol. To do so,

simply change the http://www.supersonicads.com base domain to

https://www.supersonicads.com

3. Custom direct payment steps – you can set custom direct payment price points "on-

the-spot", and overriding any previous preset that has been globally defined. In

order to do so, simply pass the following parameters to our Offer Wall URL:

a. directPaymentCurrency – 3 characters ISO symbol for the currency (e.g.:

USD, EUR, GBP).

b. directPaymentSteps – array of numbers which indicates the actual price

points, separated by underscore (_). For example: 4.99_9.99_20_50_100.

You also have the option to determine which price point will be the default

entry by adding the minus sign near the relevant price. For example, the

following string makes the price 20 the default one: 4.99_9.99_-20_50_100.

c. directPaymentStepsFactors – array of numbers which indicates the 'extra

points' factor for each price point, where 100 indicates the exact conversion

rate (100%) and any other number reflects the bias/factor in percentage of

the relevant price point. For example, the following string (in conjunction

with the previous example of directPaymentSteps) causes the price point

100 to yield an extra 15% points: 100_100_100_100_115.

d. directPaymentStepsSignature – an MD5 signature of the 3 parameter above

along with your application private key, calculated in the following manner

(PHPstyle):md5($directPaymentCurrency.$directPaymentSteps.$directPaym

entStepsFactors.$applicationPrivateKey). For reasonable security reasons, if

the signature doesn't match, the page won't be displayed.

Please note that you can omit the directPaymentCurrency parameter. In this case,

the system will choose the most appropriate currency according to the geographical

region of the end user (based on IP). If you don't pass this value, omit this string for

the signature calculation as well.

4. Custom offer wall settings – you are able to fine tune the offer wall style, layout and

other settings, by adding custom parameters to the URL. The list below describes

the available options:

Parameter name Description Example Default Comments

format Returns output in a

specific format

format=xml

format=json

html Options:html,xml,json

forceHttps Sending this

parameter will

generate ads with

URLS which are

https (and not

standard http).

forceHttps=1

publisherSubId

An integer value

for representing

custom sub IDs.

This value can be

tracked in statistic

reports.

publisherSubId=123456 0 Only integer values are

valid

applicationUserCreationDa The date in which applicationUserCreatio Must be in the yyyy-

te the user has

created his

account.

PLEASE NOTIFY US

IF YOU INTEND TO

USE THIS

PARAMETER.

nDate=2011-12-01 mm-dd format

Please send it with

applicationUserCreatio

nDateSignature

We strongly

recommend sending us

this parameter.

applicationUserCreationDa

teSignature

The md5 hashing

of the following

strings:

[applicationUserId]

[applicationUserCr

eationDate][applic

ationPrivateKey]

currencyName Specifies an

alternative

currency name

(possibly other

than what has

been predefined)

currencyName=Tokens

applicationName Specifies an

alternative

application/site

name (possibly

other than what

has been

predefined)

applicationName=Spac

eVenture

scope Focus on videos scope=6

pageSize Number of offers pageSize=6 In some cases fewer

offers will be served

to serve than the requested

amount.

page Go to a specific

page (refer to the

pageSize

parameter)

Page=3 The first page number

is 1

language Force specific

language for the

static texts.

language=es Pass the standard 2

characters ISO code for

languages. Please note

that the offers

themselves may still be

presented in the

language which is

relevant for the target

country.

suppressStatistics Suppress any

statistic counting

for this impression

suppressStatistics=1 This option can be used

if you wish to test your

production app/site

without having any

influence on the

aggregated statistics.

impressionId Force a specific

unique impression

ID

impressionId=4765356

7

Must be unsigned 32

bit integer

noDirectPayments Prevent showing

any direct payment

options

noDirectPayments=1 Please note that you

can selectively omit

specific direct payment

options per application.

For doing so, please

contact us.

noOffers Prevent showing

any offers

noOffers=1

generateDirectPaymentLin

ks

Generate URLs for

initiating direct

payments

generateDirectPayment

Links=1

Only relevant when

format=xml

directPaymentCurrency Force a specific

currency for direct

payments

directPaymentCurrency

=EUR

Pass the standard 3

characters ISO code for

international

currencies.

globalConversionFactor **

Modify the

conversion rate

globalConversionFactor

=140

Values can be between

10 to 1000, where 100

means no change (like

100%).

Notice that if this

parameter is specified,

the

globalConversionFactor

Signature and

timestamp parameters

must be specified as

well.

timestamp current UNIX time

in UTC+00:00

Refer to the

globalConversionFactor

parameter

globalConversionFactorSig

nature

an MD5 signature

based on the

following string:

$applicationKey.$a

pplicationUserId.$g

lobalConversionFac

tor.$timestamp.$p

rivateKey

Refer to the

globalConversionFactor

parameter

applicationUserGender User gender applicationUserGender

=male

unknown Possible values: male;

female

applicationUserBirthday User birthday applicationUserBirthda

y=1982-03-27

0000-00-00 yyy-mm-dd

minimumOfferCommission

*

Filters offers by

their commission

payout value

minimumOfferCommiss

ion=1.5

(as defined in the

application settings)

The currency is always

USD. Notice that if this

parameter is specified,

the

minimumOfferCommiss

ionSignature parameter

must be specified as

well.

minimumOfferCommission

Signature*

The MD5 hash of

the value passed

on the

minimumOfferCom

mission parameter

and the application

private key.

minimumOfferCommiss

ionSignature=99561687

cff6aab5e52161d76110

0baa

Refer to the

minimumOfferCommiss

ion parameter. This

parameter is case

insensitive.

maximumOfferCommission

*

Filters offers by

their commission

payout value.

maximumOfferCommis

sion=40

(as defined in the

application settings)

The currency is always

USD. Notice that if this

parameter is specified,

the

maximumOfferCommis

sionSignature

parameter must be

specified as well.

maximumOfferCommission

Signature*

The MD5 hash of

the value passed

on the

maximumOfferCo

mmission

parameter and the

application private

key.

maximumOfferCommis

sionSignature=1280196

378146187101119107

Refer to the

maximumOfferCommis

sion parameter. This is

case insensitive

parameter.

hideOffersHeader Hides Offer wall

header (offer wall

will appear w/o

tabs)

hideOffersHeader=1 Use only when focusing

on specific scope

Ip – please let us know if

you plan to use this

parameter

Control the

country

(user will see offers

bases on the the ip

address)

ip= 61.198.213.83 *Please add accessKey

and secretKey

parameters (their

values can be found in

the Setup | API form).

country - please let us

know if you plan to use this

parameter

Control the

country

(user will see offers

based on the

country code)

country=US passing the explicit

country ISO code

*Please add accessKey

and secretKey

parameters (their

values can be found in

the Setup | API form)

*WARNING: THIS PARAMETER IS DEPENDENT ON ANOTHER PARAMETER. IF MISSING, VALUE WILL REVERT TO

THE APPLICATION DEFAULT.

* PLEASE LET US KNOW IF YOU USE THESE PARAMETERS – WE NEED TO ENABLE THIS OPTION ON OUR SIDE AND

FOR SAFETY REASONS – DON’T EXPOSE THESE PARAMETERS TO USERS AND IMPLEMENT IT ON THE SERVER SIDE.

** THE SYSTEM WILL RESPECT THIS VALUE ONLY IF THE SIGNATURES MATCH AND THE TIMESTAMP VALUE IS UP TO

10 MIN DIFFERENCE THAN OUR SYSTEM TIME.

DISPLAY ADS – JS DELIVERY

To get started:

1. Place HTML div tags that will contain our ads anywhere in your html

2. Include our script (Copy the script from our website while you are logged into your account. The script can be found under 'Setup'->'Code generator) inside your site html right before the </body> tag (like Google analytics)

3. Configure the display ads through JSON variable

Example code:

<html> <head> … </head> <body> <!—You can place anywhere in the page empty HTML div tags that will eventually contain our ads-->

<div id='ssaAd1'></div> <div id='ssaAd2'></div> <!—Our script can be included at the bottom of the page, even just before the body closes-->

<script type="text/javascript"> var ssa_json = { // the id of the user whom which we will grant the rewarded points by calling your web server with it 'applicationUserId': USER_ID, // the id of your application on our system 'applicationKey': APPLICATION_ID, // an array of Display Ads in that current page, put one or more ads inside that array // give them any id you want as long as you put a div with the same id somewhere in your html body 'ads': [ {'id':'ssaAd1', 'width': 300, 'height': 250}, // display ad 1 will be injected to <div id="ssaAd1"></div> {'id':'ssaAd2', 'width': 728, 'height': 90} // display ad 2 will be injected to <div id="ssaAd2"></div> ] };

(function(d,t){ var g = d.createElement(t), s = d.getElementsByTagName(t)[0]; g.async = true; g.src = '//jsd.supersonicads.com/inlineDelivery/delivery.compressed.gz.js'; s.parentNode.insertBefore(g,s); }(document,'script')); </script> </body> </html>

Advanced configurations

Adding the scope parameter enable you to control the offer type

Example: display video offers only: 'ads': {'id':'ssaAd1', 'width': 300, 'height': 250, ‘scope’:6}

In case there are no offers of the specific scope you chose, we will fallback to the rest of our

offers pull which are relevant for the user.

You can also display our offer wall in an interstitial. To do that please call the following

function:

SSA_CORE.open({id:”SSAOFFERWALL”,width:700,height:500});

The width and height are customizable, and you can call the function from any module

inside the web page of your webside. This can be done also from buttons inside Flash

application. If you do that you need to make sure that you Flash application is embedded

in the page with the following param: <param name="wmode" value="transparent">

This param allows HTML components (e.g the offerwall) displayed on top of Flash

modules (e.g your game/application).

For example, the following code will display a link, which upon clicking on opens an

interstitial with offerwall:

<a onclick="SSA_CORE.open({id:”SSAOFFERWALL”,width:700,height:500});"

href="#">Click to earn more Coinz!!</a>

Please note: you can send custom parameters using the custom_ syntax (please read

Advanced Setting section #1)

For example:

<div id='ssaAd1'></div>

<script type="text/javascript">

var ssa_json = {

'applicationUserId': 'xxxxx', 'applicationKey': xxxx, 'custom_data': 'test customdata',

'ads': [ {'id':'ssaAd1', 'width': 565, 'height': 498} ]

};

Embedding in Google Ad Manager (DFP for small business): Please set the following in the head section of your page before the GAM JS tag

<script type="text/javascript">

var ssa_site_user_id = USER_ID;

var ssa_site_id= APPLICATION_ID;

</script>

And set the following code as the creative of the ad. This code will use the JS variables set on

top, so both must exist in the same HTML frame.

<div id="ssaAd1"></div>

<script type="text/javascript">

var ssa_json = {

'applicationUserId': ssa_site_user_id , 'applicationKey': ssa_site_id, 'ads': {'id':'ssaAd1',

'width': 300, 'height': 250}

};

(function(d,t){

var g = d.createElement(t), s = d.getElementsByTagName(t)[0];

g.async = true;

g.src = '//jsd.supersonicads.com/inlineDelivery/delivery.compressed.gz.js';

s.parentNode.insertBefore(g,s);

}(document,'script'));

</script>

UNLOCK PRODUCT INTEGRATION

1. Login to your account ->Add new App

2. Under Settings ->check the “Use the Unlock offer wall” checkbox

3. Fill the following fields:

a. Unlock call to action – unlock offer wall title and description.

b. Maximum Credits – credits value to be displayed to users.

c. Unlock Total Amount – dollar value of your product.

d. Unlock Redirect URL – once user reached to max credits, product is

unlocked and user will be redirected to the provided URL - for example:

http://www.MyRedirect.com/index.php/applicationUserId=[USER_ID]&

reward&eventId=[EVENT_ID]

Important: Please compare USER_ID and EVENT_ID parameters with

the callback parameters to make sure this is a valid unlock.

e. Currency Name – the currency name in your game/site to be displayed to

the user.

f. Callback URL - The HTTP GET method called to your server in order to

inform you that unlock was completed (our system will fire one callback

once the user reached max credits) . Please add these holders to your

URL:

[USER_ID] - a holder for us to place the identification of the user to be credited.

[EVENT_ID] - a holder for us to place the unique completion id.

Example: http://www.myapplication.com/grant.php?userId=[USER_ID]&eventId=[EVENT_ID]

Please read callback functionally on page 6.

g. Click submit and copy the Unlock iframe code from the code generator

to implement in your game/site.

h. Reports – you will be able to track unlock completions via your account

under Reports tab.

FREQUENTLY ASKED QUESTIONS

Q1: If the callback signature does not match between your server and ours (i.e. a

new parameter was added to the signature hash), what http response do you

expect from us?

A1: If signatures do not match, it means that someone has tried to simulate a false

callback (fraud) or that we do not calculate the signature the same as you do. Both

cases should be very rare and prompt an immediate response. We usually

recommend our publishers to write such situation into a special log (or even trigger

an email alert to someone from your technical team), since it may indicate that legit

users don't get their points.

If you encounter such a situation, please contact us and we'll review with you the

signature calculation. Regarding the HTTP response, we basically don't care, but if

you wish to prevent the repeated callbacks every 15 min, you can send us the valid

response string (HTTP status 200, [EVENT_ID]:OK).

Q2. On the simulate callback page in the Supersonic admin page, is there any way

we could add custom parameters to the callback url to easily test callbacks?

A2. We plan to offer this feature in the near future. For the time being, simply

specify your administrator user id in the setup page and then open our Offer Wall

page with this user id (plus, pass any custom parameter that you wish).

Then, click on one of the offers and click on the "Simulate Callback" link in the upper

toolbar (appears on top of the advertiser landing page). This will trigger a callback

event with the exact custom parameters that you have passed.

Q3. What is the typical time between offer completion to callback received? Is

there a max threshold (i.e. should receive callbacks by N hours after completing

offers)?

A3. Most completions should trigger a callback within 15 minutes (and up to an hour

for some offers). However, our system relies on the advertiser tracking system, and

as such we have little control on delays. If you encounter delays, please report them

to adops@supersonicads.com and specify the offer and completion details

(timestamp, applicationKey, applicationUserId).