Step 1: Create an Endpoint on your Server
To ensure that users receive their virtual currency or premium service after successfully completing an offer or payment, you must create an endpoint on your server that we can request to notify you of the user reward. Once you receive the notification, it is up to you to deliver that reward to the user.
Our system expects an HTTP 200
response to indicate that you have successfully processed the callback. All other HTTP response codes indicate a failure.
Callback Structure and Behavior
We call your endpoint with an HTTP GET
request. When we request your endpoint, we add in several parameters.
Parameter | Added Automatically | Details |
---|---|---|
uid |
Always | The ID of the user to be credited |
sid |
Only if security_token is set |
The request signature, which you should verify to ensure the request's authenticity. The sid is computed as a SHA1 hash of the request parameters:sid = sha1(security_token + user_id + amount + _trans_id_ + pub0 + pub1 + pub2 + …)
|
amount |
Always | The amount of virtual currency the user should be credited |
currency_name |
Always | The name of the virtual currency being rewarded as it appears in the DT dashboard |
currency_id |
Always | The ID of the virtual currency being rewarded as it appears in the DT dashboard |
_trans_id_ |
Only if configured in the dashboard | The unique transaction ID in the form of a UUID (“Universally Unique Identifier”). Use this to check whether the transaction has already been processed in your system |
pub0 - pub9
|
Only if added in the API request | It is possible to add custom parameters (called pub0, pub1, ... , pub9) to your API request for offers. These parameters are passed back, completely unchanged, in the reward callback |
offer_title |
Only if configured in the dashboard | Encoded offer title |
payout_net |
Only if configured in the dashboard | |
net_payout_eur |
Only if configured in the dashboard | |
payout_gross |
Only if configured in the dashboard | |
payout_currency |
Only if configured in the dashboard | |
lpid |
Only if configured in the dashboard | Landing page ID, ID of the Offer |
vcs_enabled |
Only if configured in the dashboard | Whether VCS was enabled when the click happened - True or False |
placement_id /span> |
Only if configured in the dashboard |
Best Practice Check
To ensure the security of your 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 callback came from DT.
Step 2: Whitelist DT IPs
If your server has restrictive security settings and/or is protected by a firewall, you may have to unblock DTs servers’ IP addresses to receive callback requests.
The IP ranges and addresses that you must whitelist are provided below.
DT IP Address |
---|
52.51.229.163 |
52.208.7.124 |
52.212.4.99 |
35.196.16.124 |
34.23.227.47 |
34.139.250.247 |
34.139.143.157 |
35.227.32.40 |
104.196.193.31 |
35.185.30.237 |
34.139.252.26 |
34.138.146.173 |
104.196.100.128 |
Step 3: Implement Your Response
DT's server decides whether the callback request was successful based on the HTTP status code of your response.
Callback Request Type | Description |
---|---|
Response | A successful callback must return a blank HTTP 200 status code. This indicates to our servers that you have successfully processed the callback. Any other response is interpreted as an Unsuccessful callback (see below). |
[Redirects] | DT's servers follow HTTP redirects (status code 301 / 302), however, all redirect locations must be absolute URLs, as specified in the W3C standard |
Unsuccessful Callbacks | If an error occurs on your side, you may send any status code other than HTTP 200 to indicate to our servers that the callback was not processed successfully. Any response other than HTTP 200 causes our system to resend the callback up to 10 additional times with an exponentially increasing delay between each attempt. |
Duplicates and Rejected Callbacks | If you identify the callback request as a duplicate based on the _trans_id_ , or if you choose to reject the callback intentionally, we recommend you send a HTTP 200 status code response. In this way, you indicate to us that the callback was processed and we do not resend it. |
Step 4: Configuring Your Endpoint in the DT Dashboard
Once you have configured your endpoint, you can configure that endpoint in the Callback URL under Reward Handling in Settings tab of the DT Dashboard.
DT automatically adds in the parameters necessary for you to deliver the reward to the user, so you only need to configure the endpoint itself.
Security Alert
The Security token
you find in the dashboard should never be placed in your client-side integration. This token should be kept secret between your servers and ours. You should ensure that there is no possible way that any of your users can access it.
If you ever feel your token has been compromised, change it in the dashboard and then update your server-side configurations with the new token.
Adding the Transaction ID
It is possible to uniquely identify every callback sent to your system with DT's Transaction ID.
Checking the Transaction ID is a simple way to ensure that you never incorrectly reward a user twice. We recommend storing all transaction IDs in your system and comparing your known list to the id sent in each reward callback.
A Security token
is generated for you to use when calculating the sid
parameter. You can change this token at any time, if necessary.
You can add this parameter by including ?_trans_id_=
at the end of your Callback URL
in the dashboard. If you already have some parameters as part of your URL, you can include the Transaction ID instead by including ?parameter=value&_trans_id_=
.
Best Practice Check
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 make sure that users can not fraudulently misuse your system into providing unearned rewards.
Code Example
Below is an example code showing how to calculate the sid
and process the callback.
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 Fyber's
$SECURITY_TOKEN = '<YOUR SECURITY TOKEN>'
#### ENDPOINT ####
# Your endpoint for the reward callback should be configured in the Fyber dashboard
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 activated the transaction id in the Fyber dashboard
# 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 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 trasaction 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 Fyber 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 Fyber 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 Fyber 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 Fyber to try again
# Set the status to something other than 200 so that Fyber knows the reward was not processed
status 500
body 'Callback failed. Error: ' + e.message
end
end
Testing Callbacks
Click and a Test Server-side Callback window appears
By entering a reward amount and selecting a virtual currency, you can have our system configure a reward callback for you.
Once you hit the Send callback button, our servers send a callback to your configured Callback URL
in the same way that we do for an actual user reward.
Custom parameters (pub0
... pub9
) are included in the callback since they must be sent along from your integration in the request.
You have now successfully set up rewards using Server-Side Callbacks.