Upload
duonganh
View
219
Download
0
Embed Size (px)
Citation preview
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
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 "[email protected]").
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 "[email protected]" 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,
"[email protected]" 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 [email protected] and specify the offer and completion details
(timestamp, applicationKey, applicationUserId).