Integrating DealSpot

DealSpot allows your customers to earn virtual currency in exchange for completing top performing deals and brand engagements.

  Note that you can integrate DealSpot either within or outside of your game SWF, but we recommend that you integrate inside your game. You can find instructions for outside the SWF here: Integrating DealSpot outside the SWF

1. Create 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. It only takes 5 minutes to get started! Create your account now! You will only need one merchant account for all of your Facebook apps.

2. Set up your currency on Facebook

Replace your existing currency object (fbpayment:currency) with an og:product object instance. Follow these Facebook instructions to set up the new object: Set up your Open Graph Currency Object 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.
  • Use Facebook's object debug tool to verify that your object has been set up correctly.
  • Make sure that one of the prices that you list is USD. This is what TrialPay will use.
  • We do support a "product:price:amount" of less than 0.01

3. Integrate DealSpot into a game SWF

DealSpot appears as an in-game icon whenever there are offers available for your customer. If no offers are available it will hide itself so your game won't be unnecessarily cluttered. DealSpot 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

3.1 DealSpot Code Snippet (In-SWF)

Load DealSpot in a 100? 100 container using the following code-snippet:
https://s-assets.tp-cdn.com/static3/swf/dealspot.swf?mode=fbdirect&app_id=<app_id>&tp_vendor_id=<tp_vendor_id>&callback_url=<callback_url>&currency_url=<callback_url>&sid=<sid>
Here is an ActionScript example:
import flash.display.Loader;
import flash.net.URLRequest;
import flash.system.Security;

...

Security.allowDomain('*');
var url:String = "http://s-assets.tp-cdn.com/static3/swf/dealspot.swf?mode=fbdirect&app_id=<app_id>&tp_vendor_id=<tp_vendor_id>&callback_url=<callback_url>&currency_url=<callback_url>&sid=<sid>";
var request:URLRequest = new URLRequest(url);
var loader:Loader = new Loader();
loader.load(request);
addChild(loader);

3.2 Required Permissions

You must allow DealSpot to communicate with your SWF’s host page. This ensures that DealSpot will rotate in-game icons correctly, and hide if the customer is ineligible for the promotion. Here are two ways to allow DealSpot to communicate with the host page:
  • set your trustContent flag to true when using the Flex SWFLoader control
  • set your allowScriptAccess flag to always on the parent container .swf
For example, to set your trustContent flag to true:
<mx:SWFLoader id="iconSWF" width="100" height="100" source="{dataSideItem.swf}" trustContent="true">
In addition you must add DealSpot to the same security context as your container SWF. This is done in ActionScript using:
Security.allowDomain("*");

3.3 Required Parameters

Parameter names are case-sensitive. All values must be URL encoded.
Placeholder Sample Value Description
<app_id> abcDEF123 Your Facebook app ID.
<tp_vendor_id> abcDEF123 Your TrialPay vendor ID (available in your account's notification preferences).
<callback_url> http%3a%2f%2fwww.acmesoft.com %2ftastymorsels%2fcallback.php The payment script's URL.
<currency_url> https%3a%2f%2fwww.acmesoft.com %2fvc%2fcoins.php The URL to your Facebook currency OpenGraph object.
<sid> abcDEF123 Your customer's Facebook third-party-ID (not the FB UID).

3.4 Optional Parameters

Parameter names are case-sensitive. All values must be URL encoded. Refer to the "Using the Optional Parameters" section for more details about some of these parameters.
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 into 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 %7b%22item+id%22+%3a+%221a%22%7d 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.

4. Set up a payment callback script

Currently, 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

5. Using the optional parameters

If 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/onOfferUnavailable 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:
<span id="<DOM_ID>"></span> 

<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" : "<DOM_ID>",
      "app_id" : "<app_id>",
      "tp_vendor_id" : "<tp_vendor_id>",
      "mode" : "<mode>",
      "callback_url" : "<callback_url>",
      "sid" : "<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:
<span id="<DOM_ID>"></span>

<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" : "<DOM_ID>",
      "app_id" : "<app_id>",
      "tp_vendor_id" : "<tp_vendor_id>",
      "mode" : "<mode>",
      "callback_url" : "<callback_url>",
      "sid" : "<sid>",
      "onOfferUnavailable" : "<offer_unavailable>",
      "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:
<span id="<DOM_ID>"></span> 

<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" : "<DOM_ID>",
      "app_id" : "<app_id>",
      "tp_vendor_id" : "<tp_vendor_id>",
      "mode" : "<mode>",
      "callback_url" : "<callback_url>",
      "sid" : "<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 integration

6.1 Add private apps to our system

To 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 offer

You 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 notifications

You 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
<app_id> abcDEF123 Your Facebook app ID.
<tp_vendor_id> abcDEF123 Your TrialPay vendor ID (available in your account's notification preferences).
<callback_url> http%3a%2f%2fwww.acmesoft.com %2ftastymorsels%2fcallback.php The payment script's URL.
<currency_url> https%3a%2f%2fwww.acmesoft.com %2fvc%2fcoins.php The URL to your Facebook currency OpenGraph object.
<sid> 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 into 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 %7b%22item+id%22+%3a+%221a%22%7d 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.
Note: Publisher may not implement TrialPay's services or technology on applications that are directed at, or collect data from, children under the age of 13.