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 ([email protected]). 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
22
Embed
JUNE PUBLISHER INTEGRATION - …documents.supersonicads.com/SupersonicAds - Publisher Integration.pdf · Facebook, MySpace, Bebo, etc.). If your application handles its own user base
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
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
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.
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