Setting Up Offer Wall

Introduction

To set-up Offer Wall via SDK, follow the steps below.

Note

Before you can configure the Offer Wall Edge, you must make sure that you have your virtual currency configured. If you have not already done so, you can modify your App Settings.

Step 1: Enabling Offer Wall Edge

  1. Go to the Dashboard and select the App.

The app window opens.

  1. On the App window click Placements
  1. Click the Placement you want.

The Configuration window opens.

  1. Toggle the status checkmark to ON.
  1. Select the currency you want to use for Offer Wall rewards from the Virtual currency dropdown menu.
  2. In the Exchange rate field enter the number of your virtual currency that equates to one Euro or Dollar (depending on the currency you set in your account settings).
  3. Select the Round up low video rewards to 1 unit of virtual currency (recommended) if you want to show offers that reward less than 1 unit of your virtual currency. In such cases, the reward is rounded up to 1.
  4. Customize the UI including the main color, mobile banner image and tablet banner image, as appropriate.
  1. Click Save to save your Offer Wall Edge configurations.

Note

You can add extra virtual currency, if required, by clicking on the Settings icon:

Step 2: Choosing Your Rewarding Strategy

There are two options for rewarding the users with virtual currency:

  1. Using Virtual Currency Server (VCS)
  2. Using your Own Server

Note

You must choose one of the two options. You cannot have both.

First set-up the developer Dashboard for the option you choose and then add the code necessary on the SDK side. Let's get started.

For more details on Reward Handling, click here.

Note

Read the Rewarding your Users section to discover the advantages of each method.

Option 1: Using the Virtual Currency Server (VCS)

  • VCS rewarding involves integrating the SDK. There is a specific use case where you might be interested in this option. For instance, if you are already using any of our other products or if you do not run your own servers, Fyber can provide you with virtual currency hosting.

Option 2: Using your Own Server (Server Side)

  • If you want to use your own server to handle virtual rewarding to your users, Fyber can interact with it once you have set-up your own server.

VCS Hosting

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

Step 1: 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.

Step 2: 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:

#import "FyberSDK.h"

@interface GemStoreViewController : UIViewController <FYBVirtualCurrencyClientDelegate>
@end

Step 3: Requesting New Rewards

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

// 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.

FYBVirtualCurrencyClient *virtualCurrencyClient = [FyberSDK virtualCurrencyClient];
virtualCurrencyClient.delegate = self;

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

[virtualCurrencyClient requestDeltaOfCoinsWithParameters:parameters];

Step 4: Handling the Response

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

- (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:

[FyberSDK instance].shouldShowToastOnReward = NO;

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.

Step 1: 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.

Step 2: 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)

Extra 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, also ensures that the sid parameter is also always unique.

A unique sid parameter makes 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.

Warning!

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

Step 1: Whitelist 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

Step 2: Implement 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
$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:

Note

iOS developers can also set up Offer Wall via an API. For details of how to do this, click here.

Updated 13 days ago

Setting Up Offer Wall


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.