Rewarding your Users

Introduction

Fyber provides several systems that you can use to reward your users. Each system is mutually exclusive to one another. You can only select a single rewarding mechanism for your integration.

Choosing the correct method is not always straightforward, as there are tradeoffs for each option. In general, the decision is usually between more security or more speed.

None of these mechanisms are insecure. All will provide rewards in a reliable manner that is difficult to fraud, so long as they are implemented correctly. But some are inherently more secure than others. Your options to reward your users are:

Option 1: Server-Side Rewarding (+ Security)
Option 2: Fyber VCS System (+ Middleground) 

Option 1: Server-Side Rewarding

The most secure of all our rewarding mechanisms, server-side reward callbacks allow user rewards to be sent directly from our servers to yours. Our servers send a real-time notification as soon as a reward is logged in our system. Your servers will then need to be able to process the reward as soon as it comes in, and then populate the reward out to the user in whatever way makes sense for your system. 

Benefits

The main benefit of server-side callbacks is that all traffic directly related to crediting the reward is completely outside the control or visibility of the user. Because there is no sensitive traffic going through the user’s device, there is less chance for fraud.

Important

The main drawback of server-side callbacks is the infrastructure that you need. If you don’t have a server to process the callbacks, you will not be able to use it.

For a full description of Server-Side Callbacks, click here.

Server-side Callbacks - Security

It is possible to add more security in the callbacks by adding the _trans_id_ parameter to the callback, which adds in a universally unique transaction id. This transaction id, due to its unique nature, will also ensure that the sid parameter will also always be unique. A unique sid parameter will make certain that no one can generate a valid callback without the callback security token provided in our dashboard. If you then also whitelist only the IP addresses associated with our Fyber servers, this rewarding mechanism is extremely secure.

Setting Up Server-Side Hosting

Whether you are using the SDK or the REST API to integrate the Offer Wall Edge within your app, you can use your own server to handle virtual rewarding to your users. 

Creating a Callback URL on your Server

  1. Go to the Application tab in the Control panel.

  1. Select the app you want.
  2. Click the cog icon for the app settings.

  1. Scroll down to the Reward Handling section.
    For full details of Reward Handling, click here.

  2. Mark the Receive serverside callbacks checkbox.

 

Creating a Callback URL on your Server

To ensure that users receive their virtual currency or premium service after successfully completing an offer or payment, you must create a callback URL on your server. Fyber requests this callback URL whenever a new transaction is completed.

Callback Structure and Behavior

There are several HTTP GET parameters added to the callback URL whenever we notify you of the payout to a user.

The URL below is an example for a callback request to your system.

Parameter Properties Details
uid Mandatory The ID of the user to be credited.
sid Optional, recommended The request signature, which you should verify to ensure the request's authenticity. It will be included if you have specified a security token when creating your application. The sid is computed as a SHA1 hash of the request parameters:
sid = sha1(security_token + user_id + amount + _trans_id_ + pub0 + pub1 + pub2 + …)
The security token should be stored inside your application in a way that is absolutely inaccessible to users.
amount Mandatory The amount of virtual currency the user gets credited. This may also be a floating-point number. Please convert it into an integer by cutting off the digits after the decimal point. This will ensure consistency between the amount of currency displayed in the Offer Wall Edge and what the user actually should be credited. However, for the calculation of the SID, it is mandatory to use the original floating-point amount as it was sent during the callback request.
_trans_id_ Optional, recommended 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.

Example ID: "82b11630-9623-11de-9207-002084162f67".

To receive it, add ?_trans_id_= to your callback URL when setting up your application.
custom parameters Optional It is possible to pass custom parameters (called pub0, pub1, ... , pub9) to the Fyber platform when requesting the offers, so you can perform any kind of tracking you need. The custom parameters will be passed back to your system during the callback. Just add the parameters when requesting the offers.
payout_net Optional The net payout the publisher receives for this transaction (in USD).
vcs_enabled Optional A flag specifying whether the conversion came from a VCS (value=true) or not (value=false)
placement_id Optional The placement identifier, if you have configured more than one placement in the dashboard

Warning

You must store the security token inside your application in a way that is absolutely inaccessible to users.

Whitelisting Fyber IPs

If your server has restrictive security settings and/or is protected by a firewall, you may have to unblock Fyber’s servers’ IP addresses to receive callback requests.

The IP ranges and addresses that you need to whitelist are provided below.

Fyber IP Address Description
146.0.239.0/24 146.0.239.0/24/24 is a subnet mask. You need to whitelist multiple IP addresses.

For example: from 146.0.239.0 to 146.0.239.255.
85.195.83.44  
 

Implementing your Response

Fyber's server decide 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. Please ensure that you only return a blank HTTP 200 status code if crediting the user was successful.
Redirects Fyber’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, do not send the error message back to us with an HTTP 200 status code. Fyber’s system would interpret the callback as successful and show the user that he received his virtual currency.

Instead, send an HTTP error code (4xx or 5xx) and Fyber’s server resends the request to the callback URL up to 25 times, with increasing delays.
Duplicates If you identify the callback request as a duplicate based on the trans_id, we recommend you to send a HTTP 200 status code response and ignore the request.

Otherwise Fyber’s server would try to resend the callback as indicated above.
 
Code Example
PHP
<?php
$security_token = <INSERT YOUR SECURITY TOKEN HERE>;
$amount = $_GET['amount'];
$userid = $_GET['uid'];
$transid = $_GET['_trans_id_'];

// Transaction ID: Only set/available if requested by attaching the _trans_id_ parameter to the callback url.
// _trans_id_ is always included in the SID calculation, so please ensure to have it as a param of your callback url

// The statement below assumes you don't have any pubX parameters defined.
// These are parameters set when redirecting the user to the Fyber offerwall.
// All pubX (i.e. pub0, pub1, pub2, ...) are passed through unmodified to
// the callback. Note that they are included in numerical order in the sid
// computation, e.g.
// $sha1_of_important_data = sha1($security_token . $userid . $amount . $transid . $_GET['pub0'] .$_GET['pub1'] ....); would be the sid in that case.

$sha1_of_important_data = sha1($security_token . $userid . $amount . $transid);

if ( $_GET['sid'] == $sha1_of_important_data ) {
    //<CALL WAS GOOD, PAYOUT TO USER, SEND HTTP200 CODE AS ANSWER >
}else{
    //CALL WAS WRONG, DO NOT PAYOUT TO USER, SEND HTTP400 CODE AS ANSWER header ("HTTP/1.0 400 Bad Request: wrong SID");
}
?>

Testing Callbacks

Test your callback handling with the callback test available on the Application tab in the Dashboard Control Panel:

58cdf43-Screen_Shot_2020-01-21_at_16.26.52.png

Option 2: Fyber’s VCS System

For those that lack a server-side environment for their apps, and so can't use Server-side Callbacks, or else would rather implement something in their app itself, we offer a Virtual Currency Server for your use.

The VCS system provides a middle ground in terms of security, ensuring that rewards must be valid in our system before they can be credited to the user, but not completely removing the user’s device from the flow of rewarding. 

Benefits

The main benefit of the VCS system is that it requires no server infrastructure to use, and can be implemented easily. VCS also provides as much security as is possible for a rewarding mechanism that does not use a server-side component, making this a good middle-ground between the other options.

Important

The main drawback of the VCS system is that the user’s device is still part of the process of crediting the reward. Precautions can, of course, be taken to reduce any risk associated with this, but it must remain a consideration.

The delays associated with the VCS reward being credited in our system should also be taken into account. VCS requests are made after a reward is credited in our system, which can end up causing some delays to rewarding the user, since there is no positive notification to your app when the reward is actually valid and ready to be claimed.

Setting Up VCS Hosting

Follow the steps below to use the Virtual Currency Server (VCS). 

The Dashboard

VCS is configured by default.

However, it can be turned On or Off by changing the Reward Handling mode in the Settings section at any time.

Now that VCS is configured, the next step is to set-up the SDK side.

Conforming to the VCS Protocol

Handling VCS is based on asynchronous operations.

Make one of your classes conform to the FYBVirtualCurrencyClientDelegate protocol and register it, via its delegate property:

Conforming to Fyber VCS Protocol
#import "FyberSDK.h"

@interface GemStoreViewController : UIViewController <FYBVirtualCurrencyClientDelegate>
@end

Requesting New Rewards

To reward your users after they have engaged with a rewarded ad format, you request the delta of coins:

Requesting Rewards
// Get the Virtual Currency Client
FYBVirtualCurrencyClient *virtualCurrencyClient = [FyberSDK virtualCurrencyClient];

virtualCurrencyClient.delegate = self; // self should conform to the FYBVirtualCurrencyClientDelegate protocol

// Request the delta of coins
[virtualCurrencyClient requestDeltaOfCoins];

Best Practice Check

Some Offer Wall requests can take a few moments longer to load, so it is important that you have configured for a potential 5 second delay.

Although we recommend you call the VCS when returning from the Offer Wall (after a short delay; recommended 5 seconds), you can also call when you're loading the screen that shows currency or after the user comes back from the Offer Wall.

Handling Multiple Currencies

If you have created multiple currencies for your application on your dashboard, the previous usage returns the delta of coins to your default currency.

Requesting Rewards from New Currency
FYBVirtualCurrencyClient *virtualCurrencyClient = [FyberSDK virtualCurrencyClient];
virtualCurrencyClient.delegate = self;

// Specify the currency id parameter
FYBRequestParameters *parameters = [[FYBRequestParameters alloc] init];
parameters.currencyId = @"gems";

[virtualCurrencyClient requestDeltaOfCoinsWithParameters:parameters];

Handling the Response

You must implement the following method which is called once the delta of coins has been requested:

Handling the VCS Response
- (void)virtualCurrencyClient:(FYBVirtualCurrencyClient *)client 
           didReceiveResponse:(FYBVirtualCurrencyResponse *)response
{
    // Process the deltaOfCoins in the way that makes most sense for your application...
    NSLog(@"Received delta of coins: %.2f %@ (currency id: %@)", response.deltaOfCoins, response.currencyName, response.currencyId);
}

You have now completed the set-up Offer Wall via SDK!

If your VCS is returning an error code, you can review the VCS Error Types here.

Optional: Disabling the Toast Message

The Fyber SDK shows a toast notification such as "Congratulations! You have earned 10 gold coins" whenever a reward is received.

To disable the notification, add the following after starting the SDK:

Objective-C
[FyberSDK instance].shouldShowToastOnReward = NO;
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request