Server-Side Rewarding

Server-side rewarding is a mechanism by which you can reward your users for completing Offer Wall offers. Server-side rewarding involves server-to-server interaction via a dedicated endpoint on your rewards server that receives requests from DT Offer Wall servers.

When a DT Advertising partner notifies us that your user has completed an offer, DT creates and sends a reward callback to your dedicated Offer Wall rewards endpoint. In this reward callback, DT includes basic information about the reward, such as the reward amount in virtual currency and the user to be rewarded.

Once you successfully process the callback, send a successful callback response back to DT. If DT receives a response other than successful, we re-send the reward callback up to 10 times until we receive a successful callback response.

The following diagram provides details about the server-side rewarding process.

sequenceDiagram
 
  box Publisher
  participant App as App
  participant SSR as Reward Server
  end
  participant OFW as DT Offer Wall Server
  participant Advertiser as Advertiser Partner

autonumber
App ->> Advertiser: User taps Offer URL and completes Offer Requirement
(subscribe, sign up, purchase, etc.) Advertiser ->> OFW: Send offer completion OFW ->> OFW: Process offer completion OFW ->> SSR: Send Reward Callback (GET) alt If callback processed unsuccessfully loop up to 10 times SSR ->> OFW: Reward Callback Response fl°°8800¶ß 200 OK OFW ->> SSR: Send Reward Callback (GET) end else If callback processed successfully or
intentionally not processed SSR ->> OFW: Reward Callback Response = 200 OK end SSR ->> App: Reward User in Virtual Currency

To implement server-side rewarding:

Step 1: Create Reward Endpoint

To receive notifications when your user successfully completes an offer, create an endpoint on your reward server where DT can send notifications (reward callbacks). DT sends a reward callback whenever Advertiser Partners confirm that an offer has been completed. Use the information in the reward callback to deliver the reward to your user.

METHOD GET
CONTENT-TYPE application/x-www-form-urlencoded
AUTHENTICATION IP Allowlisting

Default Reward Callback Structure

DT calls your endpoint with a reward callback that includes default parameters, such as user ID and reward amount:

https://game.com/ofw?
&uid=rYtXWZPLKgQOPdDe6Yr8g2UV4AB7
&amount=987654
&currency_name=Coin
&currency_id=coin

The following table describes the parameters that DT always includes in the reward callback:

PARAMETER TYPE DESCRIPTION
uid String The user ID for the user account to be credited with virtual currency.
amount Number The amount of virtual currency to reward the user account.
currency_name String The name of the virtual currency being rewarded as configured in the DT Console.
currency_id String The ID associated with the virtual currency being rewarded.

Additional Callback Parameters

In addition to the default parameters for the reward callback, you can have DT include additional parameters for fraud prevention and payout details. To prevent fraudulent rewards, DT highly recommends including security parameters so that each callback is unique. The following sample reward callback includes all optional parameters.

https://game.com/ofw?
uid=12345
&amount=10.50
&currency_name=Coins
&currency_id=coins
&_trans_id_=f4a7c2d9-1e6b-4f58-9a23-8d7e45bfc012
&sid=f3c1a97be8d52a61b40798fc3e15d6a42f89c550
&pub0=value0
&pub1=value1
&pub2=value2
&offer_title=Default+Offer
&payout_net=5.00
&net_payout_eur=4.50
&payout_gross=6.00
&payout_currency=EUR
&step_index=2
&lpid=123456
&vcs_enabled=false
&placement_id=default

The following table describes the additional parameters that DT can include in the reward callback. To have DT include these parameters in your reward callback, specify them in your Callback URL in the DT Console. For more information, see Setting Up Reward Handling.

PARAMETER TYPE DESCRIPTION
_trans_id_ String

A Universally Unique Identifier (UUID) for the reward transaction. Use this transaction ID to uniquely identify each transaction between your server and ours so that you don't accidentally reward a user twice. We recommend storing all transaction IDs in your system and comparing your known list of transaction IDs to the ID sent in each reward callback.

Due to the universally unique nature of the transaction ID, adding the ID to your callback ensures that the sid parameter is also universally unique. Using these parameters together, you can add in additional security to prevent fraudulent rewards.

If you want have DT include a secure ID (SID) in the reward callback, you must also include the transaction ID as it is part of the SID hash.

sid String The hashed signature for the reward callback.

DT includes this signature only when you also include the Transaction ID (_trans_id_) in your reward callback and specify a security token in your Reward Handling settings. For more information about specifying a security token, see Setting Up Reward Handling.

To ensure the security of reward callbacks, we recommend that you calculate the sid parameter and compare it to the parameter sent in the callback. This allows you to verify that the reward callback originated from DT.

Calculate the sid as a SHA1 hash of the following reward callback parameters:
  • security_token
  • uid
  • amount
  • _trans_id_
  • pub0pub9 (if present)
For an example of the hash calculation process, see Code Example.
pub0pub9 String If you implement custom parameters (pub0…pub9), DT passes these parameters back to you unaltered. For more information about these parameters in SDK implementations, see Show Options. For more information about these parameters in REST API implementations, see the or parameters for feed/v1/offers.
offer_title String Title of the offer that the user completed.
payout_net Number Amount the publisher earns for completion of the offer after revenue sharing and fee payments.
net_payout_eur Number Amount in euros that the publisher earns for completion of the offer after revenue sharing and fee payments.
payout_gross Number Total amount earned for the offer completion before revenue sharing and fee payments.
payout_currency String The currency set for your Offer Wall account in the DT Console.
lpid String Advertiser's unique ID for the offer landing page.
step_index Number For multi-reward offers, this parameter is the index number for the completed step of the offer.
vcs_enabled Boolean Indicates whether a virtual currency sale was active when the user clicked through to the offer. DT assigns the following values:
TRUE = Virtual currency sale was active.
FALSE = Virtual currency sale was not active.
placement_id String The Offer Wall placement ID for the placement that called up the offer.

Step 2: Configure Reward Handling in the DT Console

Once you have created your reward callback endpoint and decided which parameters you want DT to include in the reward callback, log in to the DT Console to add the Callback URL (endpoint and parameters) along with any security token you want DT to use. For more information, see Setting Up Reward Handling.

Important

Never surface the security token you enter in the DT Console in your client-side integration. To prevent fraudulent rewards, keep the token secret between your servers and ours.

If you think your token has been compromised, update your app configuration with a new token, and enter the new token in the DT Console.

Step 3: Allowlist DT IP Addresses

If your server uses restrictive security settings or a firewall, allow traffic to and from the following IP addresses of DT Offer Wall servers:

  • 34.23.227.47
  • 34.138.146.173
  • 34.139.143.157
  • 34.139.250.247
  • 34.139.252.26
  • 35.185.30.237
  • 35.196.16.124
  • 35.227.32.40
  • 52.51.229.163
  • 52.208.7.124
  • 52.212.4.99
  • 104.196.100.128
  • 104.196.193.31

Step 4: Implement Callback Response

When you receive and process a reward callback, send a response to DT to indicate the status of the reward process.

A blank response with any other status code not listed in the following table indicates an error processing a callback. In response, DT resends the original reward callback up to 10 additional times (with an exponentially increasing delay between each attempt) until we receive a successful response (HTTP 200).

RESPONSE STATUS CODE DESCRIPTION
200 A blank response with this status indicates you have successfully processed the callback and rewarded the user with virtual currency. You can also use this status code to indicate a duplicate transaction (based on _trans_id_) or to intentionally reject a reward callback.
301 or 302 You can use redirects; however, all redirect locations must be absolute URLs, as specified in the W3C standard.

Step 5: Send Test Callbacks

Once you have configured your rewards endpoint and callback structure, send a test callback so that you can validate your rewards setup. For more information, see Sending Test Callbacks.

Note

If your integration specifies custom parameters (pub0pub9), DT includes them in the test callback.

Code Example

The Ruby code example below demonstrates the following aspects of implementing server-side rewarding:

  • Gathering parameter values from the reward callback parameters to calculate the sid hash and compare it to the sid received in the reward callback.
  • Comparing the transaction ID (_trans_id_) from the reward callback to previously processed transaction IDs.
  • Gathering parameter values from the reward callback parameters to reward the user.
  • Setting response status based on processing outcome.
require 'rubygems'
require 'bundler'
require 'sinatra'
require 'digest/sha1'

# For this example we assume that you have another file with the methods necessary to credit the reward to your users.
require File.join(File.dirname(__FILE__), 'reward_processing.rb')

# Your security token should only be present on your server and DT's
$SECURITY_TOKEN = '<YOUR SECURITY TOKEN>'

#### ENDPOINT ####
# Your endpoint for the reward callback should be configured in the DT Console
get '/reward' do
  begin
    #### PARAMETERS ####
    # Gather the parameters that will be used when calculated the sid and for crediting the reward
    user_id = params['uid']
    amount = params['amount']
    # For this example we assume that you have included the transaction id in the DT Console
    # If you have not, you can remove the following line
    trans_id = params['_trans_id_']
    # For this example we assume you are passing custom parameters to assist in rewarding
    # If you are not, you can remove the following two lines
    pub0 = params['pub0']
    pub1 = params['pub1']
  
    # Gather the additional parameters not used for the sid but still used for rewarding
    currency_name = params['currency_name']
    currency_id = params['currency_id']
  
    #### SID ####
    # Calculate the sid from the callback parameters
    sid_string = ''
    sid_string += $SECURITY_TOKEN
    sid_string += user_id
    sid_string += amount
    # For this example we assume you have the transaction id, pub0 and pub1 parameters
    # If you do not, you can remove the following three lines
    sid_string += trans_id
    sid_string += pub0
    sid_string += pub1
    sid = Digest::SHA1.hexdigest sid_string
  
    #### PROCESSING ####
    # Make sure the sid parameter matches what's in the callback
    if (sid == params['sid'])
      
      # Make sure you have not already processed the transaction
      # For this example we assume that get_transactions returns an array of credited transactions
      if !(get_transactions(uid).include? trans_id)
        
        # Reward the user
        # For this example we assume that reward_user credits the user with the reward amount
        reward_user(uid, amount, pub0, pub1, currency_name)
        
        # Set the status to 200 so that DT knows the callback was processed
        status 200
        body 'Callback Successful.'
        
      else
        # If the transaction was already rewarded, you can safely ignore the callback
        # Set the status to 200 so that DT knows the callback was processed
        status 200
        body 'Duplicate transaction id. Callback rejected.'
      end
      
    else
      # If the sid is incorrect, you can safely ignore the callback
      # Set the status to 200 so that DT knows the callback was processed
      status 200
      body 'Bad sid. Callback rejected.'
    end
    
  rescue Exception => e
    # If you ran into any error while processing the callback, you will want DT to try again
    # Set the status to something other than 200 so that DT knows the reward was not processed
    status 500
    body 'Callback failed. Error: ' + e.message
  end
end

 

Back to Top ⇧