PUBLISHER INTEGRATION

Transcription

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

2 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:

3 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.

4 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: 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

5 [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

6 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 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. " " stands for January 2, :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

7 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 . We cap these alert s 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:

8 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);

9 // 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

10 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.

11 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 base domain to 3. Custom direct payment steps you can set custom direct payment price points "onthe-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

12 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 format=xml html Options:html,xml,json specific format format=json forcehttps Sending this forcehttps=1 parameter will generate ads with URLS which are https (and not standard http). publishersubid An integer value for representing custom sub IDs. This value can be tracked in statistic reports. publishersubid= Only integer values are valid applicationusercreationda The date in which applicationusercreatio Must be in the yyyy-

13 te the user has ndate= mm-dd format created his account. Please send it with applicationusercreatio PLEASE NOTIFY US ndatesignature IF YOU INTEND TO USE THIS PARAMETER. We strongly recommend sending us this parameter. applicationusercreationda The md5 hashing tesignature of the following strings: [applicationuserid] [applicationusercr eationdate][applic ationprivatekey] currencyname Specifies an currencyname=tokens alternative currency name (possibly other than what has been predefined) applicationname Specifies an applicationname=spac alternative eventure application/site name (possibly other than what has been predefined) scope Focus on videos scope=6 pagesize Number of offers pagesize=6 In some cases fewer offers will be served

14 to serve than the requested amount. page Go to a specific Page=3 The first page number page (refer to the is 1 pagesize parameter) 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 suppressstatistics=1 This option can be used statistic counting if you wish to test your for this impression production app/site without having any influence on the aggregated statistics. impressionid Force a specific impressionid= Must be unsigned 32 unique impression 7 bit integer ID nodirectpayments Prevent showing nodirectpayments=1 Please note that you any direct payment can selectively omit options specific direct payment options per application. For doing so, please contact us. nooffers Prevent showing nooffers=1 any offers

15 generatedirectpaymentlin Generate URLs for generatedirectpayment Only relevant when ks initiating direct Links=1 format=xml payments directpaymentcurrency Force a specific directpaymentcurrency Pass the standard 3 currency for direct =EUR characters ISO code for payments international currencies. globalconversionfactor ** Modify the globalconversionfactor Values can be between conversion rate = 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 Refer to the in UTC+00:00 globalconversionfactor parameter globalconversionfactorsig an MD5 signature Refer to the nature based on the globalconversionfactor following string: parameter $applicationkey.$a pplicationuserid.$g lobalconversionfac tor.$timestamp.$p rivatekey

16 applicationusergender User gender applicationusergender =male unknown Possible values: male; female applicationuserbirthday User birthday applicationuserbirthda y= 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= cff6aab5e52161d baa 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= Refer to the maximumoffercommis sion parameter. This is case insensitive parameter.

17 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= *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

18 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});

19 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',

20 '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: 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.

21 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: [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

22 an 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).