Suggest Edits

Integrating via REST API

 

Introduction

There are two different methods to integrate Offer Wall Edge:

  1. Via SDK: Android, iOS or Unity. If you want the quick and simple method to get your Offer Wall Edge up and running.

  2. Via REST API: If you need more flexibility and customization for your integration, and are comfortable working directly with the API.

To proceed with integrating Offer Wall via REST API, continue to Step 1: Enabling the Offer Wall

Suggest Edits

Step 1: Enabling the Offer Wall

 

As with most of our products, you first need to configure the Dashboard before you can start coding.

If you have followed all the steps in Starting the App Creation Wizard, you will have already configured the Offer Wall. If so, you may proceed to Step 2: Activating the REST API.

Note

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

  1. Go to the Dashboard and click through to your selected App.
  2. Go to Placements and click on the Offer Wall tab within your App.
  3. Select placement and make sure Status is set to On.
  4. Select the currency you wish to use for rewards from the Virtual currency dropdown menu.
  5. Fill in the Exchange rate field with the number of your virtual currency that equates to one Euro or Dollar (depending on the currency you have set in your account settings).
  6. Select the Round up low rewards to 1 unit of virtual currency (recommended) if you would like to show offers that reward less than 1 of your virtual currency. In such cases, its reward rounded up to 1.
  7. Click Save to save your configuration.

Remember that you can always add extra virtual currency if you need by clicking on the Settings icon:

Suggest Edits

Step 2: Activating the REST API

 

Requesting Activation

The Mobile Offer REST API must be activated by Fyber.

If you have not done it yet, contact your Fyber's Developer Support representative to enable it for your application:

As soon as this feature is turned on for your application, Fyber will provide you with an API key that you will need for all requests.

Warning!

The API key should not be shared with a third party. It is specific to you and your application. You will be personally responsible for the use of the Fyber Mobile Offer API key.

The next page contains the necessary details of our Mobile Offer Wall REST API, so you can begin to implementing the REST API.

Suggest Edits

Step 3: Implementing the REST API

 
gethttp://api.fyber.com/feed/v1/offers.json
http://api.fyber.com/feed/v1/offers.json?appid=[APP_ID]&uid=[USER_ID]&ip=[IP_ADDRESS]&locale=[LOCALE]&device_id=[DEVICE_ID]&pub0=[CUSTOM]&timestamp=[UNIX_TIMESTAMP]&offer_types=[OFFER_TYPES]&phone_version=[phone_version]&apple_idfa=[IDFA]&apple_idfa_tracking_enabled=[IDFA ENABLED]&google_ad_id=[GA ID]&google_ad_id_limited_tracking_enabled=[GA ID ENABLED]&hashkey=[HASHKEY]
A binary file was returned

You couldn't be authenticated

{
 "code": " OK" ,
 "message": "OK",
 "count": 1,
 "pages": 1,
 "information" : {
  "app_name": "SP Test App" ,
  "appid": 157,
  "virtual_currency": "Coins",
  "country": " US" ,
  "language": " EN" ,
  "support_url": "http://iframe.fyber.com/mobile/DE/157/my_offers"
 },
 "offers": [
  {
    "title": "Tap  Fish",
    "offer_id": 13554,
    "teaser": "Download and START" ,
    "required_actions": "Download and START",
    "link": "http://iframe.fyber.com/mbrowser?appid=157&lpid=11387&uid=player1",
    "offer_types" : [
     {
      "offer_type_id": 101,
      "readable": "Download"
     },
     {
      "offer_type_id": 112,
      "readable": "Free"
     }
    ] ,
    "thumbnail" : {
     "lowres": "http://cdn.fyber.com/assets/1808/icon175x175-2_square_60.png",
     "hires": "http://cdn.fyber.com/assets/1808/icon175x175-2_square_175.png"
    },
    "payout": 90,
    "time_to_payout" : {
     "amount": 1800 ,
     "readable": "30 minutes"
    }
  }
 ]
}
<?xml version="1.0" encoding="utf- 8"?>
<response>
    <code>OK</code>
    <message>OK</message>
    <count>1</count>
    <pages>1</pages>
    <information>
        <app_name>SP Test App</app_name>
        <appid>157</appid>
        <virtual_currency>Coins</currency>
        <country>US</country>
        <language>EN</language>
        <support_url>http://iframe.fyber.com/mobile/DE/157/my_offers</support_url>
    </information>
    <offers>
        <offer>
            <title>Tap Fish</title>
            <offer_id>13554</offer_id>
            <teaser>Download and START </teaser>
            <required_actions>Download and START</required_actions>
            <link>http://iframe.fyber.com/mbrowser?appid=157&lpid=11387&uid=player1</link>
            <offer_types>
                <offer_type id="101">Download</offer_type>
                <offer_type id="112">Free</offer_type>
            </offer_types>
            <thumbnail>
                <lowres>http://cdn.fyber.com/assets/1808/icon175x175-2_square_60.png</lowres>
                <hires>http://cdn.fyber.com/assets/1808/icon175x175-2_square_175.png</hires>
            </thumbnail>
            <payout>90</payout>
            <time_to_payout>
                <amount>1800</amount>
                <readable>30 minutes</readable>
            </time_to_payout>
        </offer>
    </offers>
</response>
Successful request, but no offers are currently available for this user.

Query Params

format
string
required

This parameter defines the format of the response that you will get. Currently, you can choose either json or xml. This parameter is set by the extension after ‘offers’ in the URL, e.g. .../offers.json?....

appid
string
required

This parameter represents the Fyber Application ID of your application. You can find it in the Dashboard

uid
string
required

This parameter represents the unique User ID as used internally in your application. This identifies the user so that virtual currency can later be attributed to their account via the callback request. Please note that the user ID has to remain constant so that users are prevented from completing an offer more than once.

locale
string
required

This parameter represents the language which will be used to describe the offers (e.g. the required actions). Both iOS and Android offer ways to retrieve the preferred language of the user. Note: Do not put country codes here, rather use the language codes, e.g. don’t use US, use EN instead.

os_version
string
required

Current version of the user's Operating System. Implementation hint:
[[UIDevice currentDevice] systemVersion]

timestamp
string
required

This parameter represents the time the request is being sent by the device, using the Unix Timestamp format. It is a security parameter to make sure the request is valid and wasn't processed before. Implementation hint:
[NSString stringWithFormat:@"%lu", (long)[[NSNumber numberWithDouble:[[NSDate date] timeIntervalSince1970]] integerValue]

hashkey
string
required

This parameter represents the Security Hash Key, which signs the entire request. It is a security parameter to make sure the request is valid and no data was tampered with. This parameter is mandatory. See dedicated part below for the steps to generate this hash-key.

apple_idfa
string
required

Apple ID for Advertising. Implementation hint:
[[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString] forKey:@"apple_idfa"]; More info below

apple_idfa_tracking_enabled
string
required

Is user tracking via Apple ID for Advertising enabled by the user?. Implementation hint:
[[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]]

google_ad_id
string
required

Google Advertising ID. Implementation hint: AdvertisingIdClient.getAdvertisingIdInfo(context).getId()

google_ad_id_limited_tracking_enabled
string
required

Is user tracking via Google Advertising ID enabled by the user? Implementation hint: AdvertisingIdClient.getAdvertisingIdInfo(context).isLimitAdTrackingEnabled()

device
string

The type of device. Can be tablet for iOS or Android tablets or phone. If set, this will result in special tablet/phone offers being shown. For iPods, please send phone. Implementation hint:
UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad ? @"tablet" : @"phone" forKey:@"device_id"

ip
string

This parameter represents the IP address of the device of your user. Fyber uses it to filter the offers available to and targeted at your user. If the parameter is not given, the IP address of the request will be used. Note: During integration, please also use valid ‘external’ IP addresses for testing, as responses to requests from reserved IP addresses (e.g. 127.0.0.1, 10.0.0.1, etc.) won’t contain any offers.

offer_types
string

Filter the results based on type of offer. See more details in the Request Section below

page
string

Fyber limits the amount of offers that are returned for a request. If there is more than one page of offers available for your user, an additional parameter will be returned within the response to your first offer request (see below). You can then use this parameter to define which page of the response set you are requesting. By default, page is 1.

pub0
string

By using these, you can pass along custom parameters (e.g. pub0, pub1, …) with each request to your callback URL by attaching these parameters to the API request URL

pub1
string

By using these, you can pass along custom parameters (e.g. pub0, pub1, …) with each request to your callback URL by attaching these parameters to the API request URL

phone_version
string
required

This parameter represents the user's phone model. Fyber uses it to filter the offers available. If the parameter is not provided Fyber considers it as an 'unknown' parameter, and filters the request. Please see below for a full list of values.

gdpr_privacy_consent
string

When passed: 1: yes, user gave consent 2: no, user did NOT give consent

placement_id
string

Placement Identifier. By default is blank, and blank is the same as default . Has to match value defined in the Dashboard, otherwise Offer API won’t return any ads.

 

Phone Version Values

Value
Types

iPhone

"iPhone3,1",
"iPhone3,2", "iPhone3,3",
"iPhone4,1", "iPhone4,2", "iPhone4,3",
"iPhone5,1", "iPhone5,2",
"iPhone5,3", "iPhone5,4",
"iPhone6,1", "iPhone6,2",
"iPhone7,2", "iPhone7,1",
"iPhone8,1", "iPhone8,2", "iPhone8,4",
"iPhone9,1", "iPhone9,2", "iPhone9,3", "iPhone9,4"
"iPhone 10,1", "iPhone 10,2", "iPhone 10,3", "iPhone 10,4", "iPhone 10,5", "iPhone 10,6", "iPhone 11,2", "iPhone 11,4", "iPhone 11,6", "iPhone 11,8",
"iPhone 12,1", "iPhone 12,3", "iPhone 12,5"

iPad

"iPad1,1",
"iPad2,1", "iPad2,2", "iPad2,3", "iPad2,4", "iPad2,5", "iPad2,6", "iPad2,7",
"iPad3,1", "iPad3,2", "iPad3,3",
"iPad3,4", "iPad3,5", "iPad3,6",
"iPad4,1", "iPad4,2", "iPad4,3", "iPad4,4", "iPad4,5", "iPad4,6", "iPad4,7", "iPad4,8", "iPad4,9",
"iPad5,1", "iPad5,2","iPad5,3", "iPad5,4",
"iPad6,3", "iPad6,4", "iPad6,7", "iPad6,8"
"iPad6,11", "iPad6,12",
"iPad7,1", "iPad7,2", "iPad7,3", 'iPad7,4",
"iPad8,1", "iPad8,2", "iPad8,3", "iPad8,4", "iPad8,5", "iPad8,6", "iPad8,7", "iPad8,8"

iPod

"iPod1,1",
"iPod2,1",
"iPod3,1",
"iPod4,1",
"iPod5,1",
"iPod7,1"

Unknown

blank

To handle the response and request is important that you follow the following two steps.

Let's start by the Request: Step 3A: Preparing the Request. Pay special attention to the Hash Key Calculation.

Suggest Edits

Step 3A: Preparing the Request

 

All requests to the API have to use HTTP GET. No other HTTP methods are supported and will result in a HTTP Error 404. You provide Fyber with the needed information to send you all offers available to your user with this request.

Offer Type Filter (offer_types)

This parameter allows the filtering of offers based on their type, so that only offers matching one or more of the specified categories will be returned. This parameter is optional. More than one offer type can be given as a parameter, concatenated with a comma. For filtering, they will be combined using logical OR.

Request Result
...&offer_types=112&... The Response will contain all offers marked as ‘Free’.
...&offer_types=101,112&... Response will contain all offers marked as ‘Download’ or marked as ‘Free’.

Note

If you want to request all offers except one or more categories (blacklisting), please use the filter configuration in the Fyber Publisher Control Panel.

A list of all available offer_type IDs to use in the request filter is found below.

Offers sorted by the fact that it costs the user something:

offer_type_id Readable Description
112 Free Free offers
103 Sale Shopping offers

Offer sorted by user action:

offer_type_id Readable Description
100 Mobile Mobile subscription offers
101 Download Download offers (from Apple Store)
102 Trial Trial subscription offers
104 Registration Information request offers
105 Registration Registration offers
108 Registration Data Generation offers
110 Surveys Survey offers
111 Dating Dating offers
113 Video Video offers
114 Rewarded Action Rewarded action offers

Download offers sorted by gaming category (if applicable):

offer_type_id Readable Description
106 Games Gaming offers
107 Games Gambling offers
109 Games Skill Game offers

Note

One offer will match multiple categories, e.g. one offer can be an app to download from the Apple Store as well as a free skill game.

Hashkey Calculation

This hash key must be generated by the device itself and must follow strict rules:

  1. Get all request parameters and their values (except hashkey).
  2. Order theses pairs alphabetically by parameter name.
  3. Concatenate all pairs using = between key and value and & between the pairs.
  4. Concatenate the resulting string with & and the API Key given to you by Fyber.
  5. Hash the whole resulting string, using SHA1. The resulting hashkey is then appended to the request as a separate parameter.

If some parameters must be url-encoded, the entire hash calculation has to be done before this encoding.

Example

Here's an example of the process:

  1. Gather all request parameters, except the hashkey.

  2. Gather all request parameters:

    • appid = 157
    • google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0
    • google_ad_id_limited_tracking_enabled=true
    • ip = 212.45.111.17
    • locale = de
    • page = 2
    • pub0 = campaign2
    • timestamp = 1312553361
    • uid = player1
  3. Concatenate all request parameters.

appid=157&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=212.45.111.17&locale=de&page=2&pub0=campaign2&timestamp=1312553361&uid=player1
  1. Concatenate the resulting string with your API Key.

Using your API Key: e95a21621a1865bcbae3bee89c4d4f84

appid=157&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=212.45.111.17&locale=de&page=2&pub0=campaign2&timestamp=1312553361&uid=player1&e95a21621a1865bcbae3bee89c4d4f84
  1. Hash the resulting string using SHA1.
68fc8e87db598e2149b4f72379fc2efd69309787

Note

The Mobile Offer API expects the hashkey to be in lower case.

The complete request URL to Fyber’s Mobile Offer API for these parameters would then look like this:

http://api.fyber.com/feed/v1/offers.json?appid=157&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=212.45.111.17&locale=de&page=2&pub0=campaign2&timestamp=1585187676&uid=player1&hashkey=68fc8e87db598e2149b4f72379fc2efd69309787

Example implementation of the code in Ruby

require 'digest/sha1'

api_key = 'e95a21621a1865bcbae3bee89c4d4f84' # your Fyber API key for the application
params = 'appid=157&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=212.45.111.17&locale=de&pub0=campaign2&timestamp=1312553361&uid=player1' # request params
page = 2

params = params.split('&').each_with_object({}) do |item, memo|
  key, value = item.split('=')
  memo[key] = value
end

def to_query(hash)
  hash.to_a.map { |item| item.join('=') }.join('&')
end

params.delete('hashkey')
params['timestamp'] = Time.now.to_i.to_s
params['page'] = page

params = params.sort.to_h # sort by key name
hashkey = Digest::SHA1.hexdigest("#{to_query(params)}&#{api_key}")

url = "http://api.fyber.com/feed/v1/offers.json?#{to_query(params)}&hashkey=#{hashkey}"

Note

To avoid displaying potentially expired offers to the user, please try to keep requests as close to realtime as possible.

Improving Response Times

In order to optimize the communication between servers, dramatically reduce response times and improve the user experience, we recommend the following:

  • Enable Keep-Alive for all requests.
  • Enable compression of the response using Accept-Encoding: gzip headers.

Let's continue to preparing the Response.

Suggest Edits

Step 3B: Parsing the Response

 

Basic Response Body Structure

If your request did not succeed, please check HTTP status and error:

HTTP code
Code
Description

400

ERROR_INVALID_PAGE

A non-existing page was requested with the parameter page.

400

ERROR_INVALID_APPID

An invalid or missing application id (appid) was given as a parameter in the request.

400

ERROR_INVALID_UID

An invalid or missing user id (uid) was given as a parameter in the request.

400

ERROR_INVALID_DEVICE_ID

An invalid or missing unique device identifier (device_id) was given as a parameter in the request.

400

ERROR_INVALID_IP

An invalid IP address (ip) was given as a parameter in the request.

400

ERROR_INVALID_TIMESTAMP

An invalid, expired or missing timestamp was given as a parameter in the request.

400

ERROR_INVALID_LOCALE

An invalid or missing language (locale) was given as a parameter in the request.

400

ERROR_INVALID_CATEGORY

An invalid or non-existing category (offer/mobile_types) was given as a parameter in the request.

400

ERROR_INVALID_ITEMID

An invalid or missing itemid was given in the request.

401

ERROR_INVALID_HASHKEY

An invalid or missing has hashkey for this appid was given as a parameter in the request.

500

ERROR_INTERNAL_SERVER_ERROR

An unknown error happened on the Fyber server.

After successful request HTTP 200 OK, the response body will contain the offers in the format you chose upon requesting.

Fyber will either respond with JSON or XML for a successful response depending on the format. Both formats follow the same structure, detailed in the following, with examples for both formats.

Response Elements
Explanation

response

The complete response will be wrapped inside this element.

code

The code represents the general outcome of your request. See the table below for more details about all possible response codes. This code will be especially helpful during integration and for debugging.

message

This element contains a more humanly readable explanation of the general outcome of your request, helping you to quickly identify possible problems.

Note: Don’t use this element message to evaluate the response of your request, as we may change the texts over time. Only use the above mentioned element code for this.

count

This element contains the total number of offers available, depending on the parameters of your request.

pages

If there are more offers available than the amount that Fyber is responding with to a single request, this parameter will indicate how many more pages of results are available. You can then issue additional requests using the optional parameter page to request all the remaining offers.

information

This element contains basic information about the application and offers that are being returned, see below.

app_name

The title of the application as entered in the Fyber Publisher Control Panel.

appid

The application id used by Fyber to identify your specific application. You can find your ID in the Fyber Publisher Control Panel in the ‘Integration’ section of your application. This element should match the parameter appid of your request.

virtual_currency

The name of your currency as entered in the Fyber Publisher Control Panel. This element represents the country of the user, which Fyber derives from the IP given in the request (via parameter ip). The offers returned are all targeted to users from this country.

language

This element represents the language used to describe the offers (e.g. the required actions) and should match the locale parameter of your request.

support_url

This element represents the customer support URL specific to your app.

offers[]

This element contains an array of offers returned. Each offer contains more detailed information, as seen below.

link

This element represents the URL that the user should be sent to upon selecting this offer.

Note: Please open the link in the system browser instead of a web view, as some offers don’t work within the context of a web view.

offer_id

An identifier of the offer in case you need to identify returned offers across requests.

title, teaser and required_actions

These elements describe the offer as well as giving a description of the steps needed to complete the offer. If there is no offer specific description available, the element teaser will contain the same content as the element required_actions.

thumbnail

This element contains URLs to the image used for the offer. Both a high resolution (hires) and a low resolution (lowres) version of the image are included.

offer_types[]

This element contains a list of one or more offer_types attributed to this offer, both as offer_type_id as well in a human readable format (using the language requested via the locale parameter). A list of all offer_types can be found below.

payout

This element contains the amount of virtual currency paid out to the user upon completion of the offer. It is calculated using the money payout and the exchange rate setup for your application in the Fyber Publisher Control Panel.

time_to_payout

This element contains the amount of seconds a user normally has to wait until the payout is finished after completing an offer, both in the numerical representation as well as in a human readable format (using the language requested via the locale parameter). If the time to payout is unknown, the element will contain “N/A” as a string.

Signed Response

To ensure the integrity and validity of the response, Fyber adds a special security parameter to the HTTP response header. It is called X-Sponsorpay-Response-Signature,and is created by using rules similar to those for the request signature.

Rules

  1. Concatenate the full response body with your API key.
  2. Hash the whole resulting string using SHA1.

Example header

X-Sponsorpay-Response-Signature: 96cf9acc1c1d1800ba8aa1e095e3a032ec49bca3

Warning!

The use of this parameter is optional but we strongly recommend that you evaluate it on your side to prevent anyone from tampering with any responses sent to you.

Time to handle the rewarding aspect.

Suggest Edits

Step 4: Rewarding Strategy

 

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.

Note

Our system expects an HTTP 200 response to indicate that you have successfully processed the callback. All other HTTP response codes indicate a failure.
For more information on setting up your endpoint, refer to the advanced configuration section on implementing a server-side callback.

For more details on Reward Handling, click here.

Callback Structure and Behavior

Fyber calls 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

always

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 Fyber dashboard.

currency_id

always

The id of the virtual currency being rewarded as it appears in the Fyber 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.

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

Configure Your Endpoint in the Fyber Dashboard

Once you have configured your endpoint, you can configure that endpoint in the Callback URL under Reward Handling in Settings tab of the Fyber Dashboard.

Fyber automatically adds in the parameters necessary for you to deliver the reward, so you'll only need to configure the endpoint itself.

Adding the Transaction ID

It is possible to uniquely identify every callback sent to your system with Fyber'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 on 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 may choose to change this token at any time.

Security Alert!

The Security token you find in the dashboard should never be placed in your client-side integration. This token that should be kept secret between your servers and ours. Ensure that there is no possible way that any of your users can access it.

If you feel your token may have been compromised, you may change it in the dashboard and then update your server-side configurations with the new token.

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 fraud your system into providing unearned rewards.

You have successfully set up Offer Wall via REST API.