Integrating DealSpot Outside the SWF

1. Sign up for a Merchant Account

Your TrialPay merchant account is where you will be able to access reporting, testing, and customization for your integrations. Your merchant account is also where we store your payment information and post your payment history. Sign up now! Note: You will only need one merchant account for all of your Facebook apps.

2. Integrating DealSpot outside of a game SWF

You can integrate DealSpot outside of your game SWF. The DealSpot icon will only appear if there are offers available for your customer — if there are no offers are available it will hide itself. DealSpot icon outside swf When a customer clicks the icon, an overlay appears explaining the offer in detail. The customer can then choose to complete the offer or dismiss the overlay. DealSpot overlay outside game

DealSpot Code Snippet (out of SWF)

Embed the following code snippet in a 100×100 container outside of your game SWF:  
  <script type="text/javascript">
    window.trialpayAsync = window.trialpayAsync || [];
    window.trialpayAsync.push(function() {
      TRIALPAY.social.render_dealspot_swf( {
        "id" : "",
        "mode" : "fbdirect",
        "app_id" : "<app_id>",
        "tp_vendor_id" : "<tp_vendor_id>",
        "callback_url" : "<callback_url>",
        "currency_url" : "<currency_url>",
        "sid" : "<sid>"
      });
    });

    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
    document.getElementsByTagName("body")[0].appendChild(script);
  </script>

Required Parameters

Optional ParametersRefer to the "Using the Optional Parameters" section for more details about some of these parameters. 3. Set up a payment callback scriptCurrently, when a customer completes an offer, we call Facebook who then calls your payment callback script. After the transition, we will call your payment script directly. In order for this to work, you must set up a script that can receive a FORM POST request from us (it will come from the IP range 54.183.233.157, 54.183.231.95, 70.42.249.1 – 70.42.249.255, and 199.68.156.0 - 199.68.159.255). Whenever we call the script, you must:
  • validate the request,
  • issue the reward to the customer, and
  • respond to the request and indicate success or failure.
POST body contentsThe POST body will contain a single URL encoded string comprised of the following variables: Validating the requestWe will sign the POST body string with an HMAC-MD5 hash using the string and your notification key and assign the hash to the "TrialPay-HMAC-MD5" header (note that some languages will rename this header to "HTTP_TRIALPAY_HMAC_MD5").You must validate this hash before responding our request. To validate the hash:
  • Plug the POST body string and your notification key (available in your account's notification preferences).
  • Generate your own hash from the above.
  • Compare the two hashes.
If the keys match, the request is valid and you should issue the customer the reward and respond to the request indicating success.If they keys do not match, the request is invalid, so you should not issue a reward. Respond to our request and indicate failure.For sample validation code, please refer to this help article. Responding to the requestAfter you attempt to issue the customer credits, you must respond to our request and indicate if you succeeded or failed.

Indicating Success: To indicate success, respond with success code 200 and the number 1 in the body. For example:HTTP/1.0 200 OK Date: Sat, 04 Apr 2009 23:59:59 GMT Content-length: 8 1

Indicating Failure: To indicate failure, respond with success a 400- or 500-level status code and any human readable text that indicates the nature of the failure.

For example: HTTP/1.0 400 ERROR Date: Sat, 04 Apr 2009 23:59:59 GMT Content-length: 90 Duplicate Transaction 4. Set up your currency on FacebookReplace your existing currency object (fbpayment:currency) with an og:product object instance. Follow these Facebook instructions to set up the new object: https://developers.facebook.com/docs/howtos/payments/definingproducts/#ogproduct_currency

Notes:
  • We do not support dynamic pricing. If your existing currency already uses dynamic pricing, create a new currency object with static pricing for offers.
  • Be sure to use Facebook's object debug tool to verify that your object has been set up correctly.
  • Please make sure that one of the prices that you list is in USD as that is what TrialPay will use
5. Using the optional parametersIf you are implementing our code snippets for the first time, or have not used these features before, use the following instructions to listen for various events.

onOfferAvailable/onOfferUnavailabl - These parameters can only be used with DealSpot.Before the in-game icon appears we check if there are any offers to show the customer. You can listen for the result and call your own functions by assigning the functions to the onOfferAvailable or onOfferUnavailable optional parameters (alternatively you can use ActionScript and listen for the trialpayOfferAvailable or trialpayOfferUnavailable events).

For example, let’s say you want to display an alternative promotion if there are no offers to show the customer. You create a function named alternative_promo, which you define somewhere in your game/page, and assign it to the onOfferUnavailable optional parameter:
<script type="text/javascript">
  function alternative_promo() { 
    // code to show alternative promo 
  } 

  window.trialpayAsync = window.trialpayAsync || []; window.trialpayAsync.push(function() { 
    TRIALPAY.social.render_dealspot_swf({ "id" : "", "app_id" : "", "tp_vendor_id" : "", "mode" : "", "callback_url" : "", "sid" : "",  "onOfferUnavailable" : "alternative_promo" 
  }); 
}); 

var script = document.createElement("script");
script.type = "text/javascript";
script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
document.getElementsByTagName("body")[0].appendChild(script); </script>
onTransactYou can tell when a customer completes an offer by adding the onTransact parameter and object to the code snippet. For example, in DealSpot:
<script type="text/javascript">
  
  function my_ontransact(obj) {
    alert('my_ontransact. completions: ' + obj.completions + ". vc_amount: " + obj.vc_amount + ". vc_name: " + obj.vc_name); }
  
  window.trialpayAsync = window.trialpayAsync || []; window.trialpayAsync.push(function() { 
    TRIALPAY.social.render_dealspot_swf( { "id" : "", "app_id" : "", "tp_vendor_id" : "", "mode" : "", "callback_url" : "", "sid" : "", "onOfferUnavailable" : "",  "onTransact" : "my_ontransact" 
    });
  }); 

  var script = document.createElement("script"); 
  script.type = "text/javascript"; script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
  document.getElementsByTagName("body")[0].appendChild(script); 

</script>
When a customer completes an offer we’ll call the my_ontransact function and you can retrieve the following properties:
  • completions — number of completions (e.g., 1).
  • vc_amount — amount of virtual currency rewarded (e.g. 15)
  • vc_name — the name of the virtual currency rewarded (e.g. Gold Coins).
Note that if we timeout while waiting for a completion notification from the advertiser, we’ll call the function anyway and set both completion and vc_amount to zero.onOpen/onCloseYou can call your own function whenever a customer opens or closes the offer overlay by including the onOpen or onClose parameters in the code snippet.For example, in DealSpot:  
<script type="text/javascript">

function overlay_closed() { 
  // code to execute when customer closes overlay }
  
  window.trialpayAsync = window.trialpayAsync || []; window.trialpayAsync.push(function() {
    TRIALPAY.social.render_dealspot_swf( { "id" : "", "app_id" : "", "tp_vendor_id" : "", "mode" : "", "callback_url" : "", "sid" : "",  "onClose" : "overlay_closed" 
  });
});

var script = document.createElement("script");
script.type = "text/javascript";
script.src = "//s-assets.tp-cdn.com/static3/js/api/payment_overlay.js";
document.getElementsByTagName("body")[0].appendChild(script);
</script>
6. Testing your integration6.1 Add private apps to our systemTo test TrialPay on your private apps, you will need to manually add your private App IDs to our system.
  • Log into your Merchant Account and add your app in your account's Test Settings.
  • If you see "Error: Your App ID already exists in our platform" there is no need to manually add your App ID into our system.
  • You are now ready to integrate TrialPay on your private app!
6.2 Whitelisting your 3rd Party ID for our test offerYou can whitelist your 3rd Party ID for our test offer, which can simulate an offer completion.To gain access to the test offer:
  • Log into your Merchant Account and add your 3rd Party ID/App ID pairing in your account's Test Settings.
  • You will need to add 3rd party IDs for each individual app that you are testing
  • You should now be able to see our test offer, Quick and Simple Survey, in your TrialPay placements
6.3 Viewing failed callback notificationsYou must respond to our callback with an HTTP status code of 200 and a body of 1. You can view all failed responses in your Merchant Account under Failed Notifications

Placeholder Sample Value Description
trialpay_dealspot A unique HTML DOM ID you've chosen for this DealSpot touchpoint.
abcDEF123 Your Facebook app ID.
acdDEF123 Your TrialPay vendor ID (available in your account's notification preferences).
http://www.acmesoft.com/tastymorsels/callback.php Your payment script's URL.
http://www.acmesoft.com/vc/coins.php The URL to your Facebook currency OpenGraph object.
abcDEF123 Your customer's Facebook third-party-ID (not the FB UID).
Parameter Sample Value Description
onTransact my_ontransact An object you can use to tell when a customer completes an offer.
onOfferAvailable offer_available The name of your own JavaScript function that DealSpot will call if there are one or more offers to show the customer.
onOfferUnavailable alternative_promo The name of your own JavaScript function that DealSpot will call if there are no offers to show the customer.
touchpoint 1 Identifies individual DealSpot integrations. This is required if you are integrating more than one DealSpot in your game or app.
onOpen overlay_opened The name of your own JavaScript function that DealSpot will call when a customer clicks the in-game icon.
onClose overlay_closed The name of your own JavaScript function that DealSpot will call when a customer closes the offer overlay.
width 300 Overrides the SWF’s width (default is 100). Only do this if you are using custom in-game icons.
height 250 Overrides the SWF’s height (default is 100). Only do this if you are using custom in-game icons.
position_top 250 Positions the offer overlay X pixels from the top edge of your swf’s host page.
position_left 250 Positions the offer overlay X pixels from the left edge of your swf’s host page.
zIndex 5 Displays the overlay in the specified stack order.
order_info {"item id" : "1a"} Your own custom parameters. This can be any string. We will pass this back to you when we call your payment callback script. Character limit = 100.
Key Sample Value Description
app_id AaBb1234 Your Facebook app ID.
sid CcDd5678 Your customer's Facebook third-party-ID.
oid abcd1234 A unique ID that identifies the transaction in our system.
reward_amount 100 The amount of currency to issue the customer.
callback_url http%3a%2f%2fwww.acmesoft.com%2ftastymorsels %2fcallback.php Your payment script's URL.
currency_url https%3a%2f%2fwww.acmesoft.com %2fvc%2fcoins.php The URL to your Facebook currency OpenGraph object.
order_info %7b%27item_id%27%3a+%271a%27%7d Custom, game-specific information you pass to us when you first launch DealSpot or the Offer Wall.