Follow this 6-step guide to integrate DT Offer Wall via REST API:

1. Configure your app on the DT Console.
2. Activate the REST API and receive your API key.
3. Prepare and send a request.
4. Parse the response.
5. Redirect the user to the offer url (using the /show function).
6. Set up reward handling.

Configure Offer Wall in DT Console

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 Adding Your App, you will have already configured the DT Offer Wall. If so, you may proceed to Step 2: Activating the REST API. 

Remember that you can always add extra virtual currency under the settings section:

The next step is to activate the REST API.

Activating the REST API

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

Preparing a Request

In the request, you provide DT with the needed information about the user. In the response, we can return all available offers, according to the information passed in the request. When preparing the request, pay special attention to the Hash Key Calculation instructions.

All requests to the API have to use HTTP GET. No other HTTP methods are supported and will result in a HTTP Error 404. Find below the basic structure of the request:

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] 

Query Params

The following table details the descriptions of all params in the request. 

Param	Type	Status	Description
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 DT Application ID of your application.
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.
	Tip: [[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:
	Tip: [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. More information can be found in Step 3.
	Tip: [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString] forKey:@"apple_idfa"];
apple_idfa_ tracking_enabled	string	required	Is user tracking via Apple ID for Advertising enabled by the user
	Tip: [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]]
google_ad_id	string	required	Google Advertising ID.
	Tip: AdvertisingIdClient.getAdvertisingIdInfo(context).getId()
google_ad_id_ limited_tracking _enabled	string	required	Is user tracking via Google Advertising ID enabled by the user?
	Tip: AdvertisingIdClient.getAdvertisingIdInfo(context) .isLimitAdTrackingEnabled()
device_id	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.
	Tip: UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad ? @"tablet" : @"phone" forKey:@"device_id"
ip	string		This parameter represents the IP address of the device of your user. DT 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 Step 3.
page	string		DT 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. DT uses it to filter the offers available. If the parameter is not provided DT 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

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 DT
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

1. Gather all request parameters, except the hashkey. For example:

   • 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
2. Sort the gathered parameters in alphabetical order
3. Concatenate all request parameters with '&'. Result example:

appid=000&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=111.22.333.44&locale=aa&page=2&pub0=campaign2&timestamp=1585187676&uid=player1

4. Concatenate the resulting string with your API Key. For example: 

API Key Example: e95a21621a1865bcbae3bee89c4d4f84

appid=000&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=111.22.333.44&locale=aa&page=2&pub0=campaign2&timestamp=1585187676&uid=player1&a11b22222c3333defgh4ijk55t6d7f88

5. Hash the resulting string using SHA1. Result example:

8ee872d6999f9e05b033a38824385278139d63b6

6. The Mobile Offer API expects the hashkey to be in lower case. The complete request URL to DT's API would then look like this:

http://api.fyber.com/feed/v1/offers.json?appid=000&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=111.22.333.44&locale=aa&page=2&pub0=campaign2&timestamp=1585187676&uid=player1&hashkey=8ee872d6999f9e05b033a38824385278139d63b6

Example: code implementation in Ruby

require 'digest/sha1'
                        
                        api_key = 'aa11b22222c3333defgh4ijk55t6d7f88' # your DT API key for the application
                        params = 'appid=000&google_ad_id=a0b0c0d0-a0b0-c0d0-e0f0-a0b0c0d0e0f0&google_ad_id_limited_tracking_enabled=true&ip=111.22.333.44&locale=de&pub0=campaign2&timestamp=1585187676&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}"

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.

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 sorted by user action:

Download offers sorted by gaming category (if applicable):

Improving Response Times

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.

Parsing the Response

The response returns all available offers according to the information passed in the request. While parsing the response, keep in mind that you must call the /show function if you choose to present an offer to a user.

Successful Response

After successful request, you will receive a 200 OK response. The response body will contain the offers in the format you chose upon requesting. The following is an example of a successful response as well as an explanation of the response parameters.

code 200 OK

  {
  "code": " OK",
  "message": "OK",
  "count": 1,
  "pages": 1,
  "information": {
    "app_name": "My Fun Game",
    "appid": 000,
    "placement_id": "",
    "virtual_currency_sale_enabled": false,
    "country": " US",
    "language": " EN",
    "support_url": "http://iframe.fyber.com/mobile/AA/000/my_offers"
  },
  "offers": [
    {
      "title": "My Fun Game",
      "offer_id": 00000,
      "teaser": "Download and START",
      "required_actions": "Download and START",
      "link": "http://iframe.fyber.com/mbrowser?appid=000&lpid=00000&uid=player1",
      "store_id": "com.my.fungame",
      "detailed_actions_text": "regsiter and get 20 blocks to stack",
      "instruction_steps": [
        "Register",
        "Get 20 blocks to stack"
      ],
      "offer_types": [
        {
          "offer_type_id": 101,
          "readable": "Download"
        },
        {
          "offer_type_id": 102,
          "readable": "Free"
        }
      ],
      "thumbnail": {
        "lowres": "http://cdn.fyber.com/assets/1000/icon_60.png",
        "hires": "http://cdn.fyber.com/assets/1000/icon_175.png"
      },
      "payout": 90,
      "time_to_payout": {
        "amount": 1800,
        "readable": 30
      },
      "action_steps": [
        {
          "action_id": "SIXTH_MINE",
          "step": "Reach Mine 6 and get u’r reward",
          "payout_distribution": 1.71,
          "rewd_amnt": 1
        },
        {
          "action_id": "EIGHTH_MINE",
          "step": "Reach Mine 8 and get u’r reward",
          "payout_distribution": 4.27,
          "rewd_amnt": 1
        },
        {
          "action_id": "TENTH_MINE",
          "step": "Reach Mine 10 and get u’r reward",
          "payout_distribution": 17.09,
          "rewd_amnt": 5
        },
        {
          "action_id": "FOURTEENTH_MINE",
          "step": "Reach Mine 14 and get u’r reward",
          "payout_distribution": 25.64,
          "rewd_amnt": 8
        },
        {
          "action_id": "TWENTIETH_MINE",
          "step": "Reach Mine 20 and get u’r reward",
          "payout_distribution": 51.29,
          "rewd_amnt": 16
        }
      ],
      "asset_urls": [
        {
          "low": "https://ofw-assets.fyber.com/offer_campaign/0000/00000/e7ab883d-4237-4d1f-ae3a-924f4bf02525_low.mp4",
          "raw": "https://ofw-assets.fyber.com/offer_campaign/0000/00000/e7ab883d-4237-4d1f-ae3a-924f4bf02525_raw.mp4",
          "high": "https://ofw-assets.fyber.com/offer_campaign/0000/00000/e7ab883d-4237-4d1f-ae3a-924f4bf02525_high.mp4",
          "medium": "https://ofw-assets.fyber.com/offer_campaign/0000/00000/e7ab883d-4237-4d1f-ae3a-924f4bf02525_medium.mp4"
        }
      ],
      "url": "//aws.fyber.com/show/fyberappid=0000&uid=uniqueID&client=api&device_model=&platform=android&appname=+0000+My+Fun+Game&traffic_source=offer_api&country_code=DE&pubid=249&ip=192.168.0.1&request_timestamp=1676985764323&request_id=090172a5-7e1b-4881-9cbc-c06c2721e7bc&timestamp=1676968753&ad_id=000000&ad_format=offer&group=Fyber&gdpr_privacy_consent=0&sig=2797caf0485ee6fed3f8bcebe5075de900c68ea0"
    }
  ]
}

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

Unsuccessful Response

code 401

{
    "code": "ERROR_INVALID_HASHKEY",
    "message": "An invalid hashkey for this appid was given as a parameter in the request."
}

code 400

Code 400 means something in the request isn't correct, and it was not received. Please check HTTP status and error:

To ensure the integrity and validity of the response, DT 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

Redirecting a User to an Offer

In order to properly redirect the user to complete the offer, you must use the url provided by DT and send the user to it. This url, together with further information about the offer, is provided upon calling a /show function to the API.

Upon issuing the request to call the /show function, the response will present many details about the offer, and include the offer_url property. This url is the endpoint to which the publisher should redirect the user.

Request /show

Find below an example of the request to call the /show function:

https://aws.engine.fyber.com/show/fyber?appid=000&uid=pitis&client=api&device_model=&platform=android&appname=Android+Test&traffic_source=offer_sdk&country_code=AA&pubid=123&ip=111.22.333.44&request_timestamp=1676894767825&request_id=11aaaab2-33cc-4444-dd55-6666e77f888g&ad_id=1111111&ad_format=offer&group=Fyber&rank=1&gdpr_privacy_consent=0&sig=273e6231d834d90703cfb04d28c15c4ac7cedf

 

/show Response

Below we present a response example to the /show function.

Notice the second property in the response, offer_url. Redirect your user to this url for them to complete the offer.

{
  "id": 1111111,
  "offer_url": "https://app.adjust.com/aytn3sk?campaign=AB_9807G_android_Fyber_AAA_XX_16_Feb&adgroup=9999&idfa=&gps_adid=&android_id=&ip_address=11.222.333.4&user_agent=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_15_7%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F109.0.0.0+Safari%2F537.36&fyber_click_id=5216e006-3ed0-471c-907d-d08a212c5050&cost_type=CPE&cost_amount=280.0&cost_currency=USD",
  "country_code": "AA",
  "background_tracking": false,
  "mobile_app_identifier": "com.my.fungame",
  "preview": true,
  "preview_text": "Installieren Fun Game!\nErreiche eine Tiefe von 9500 Metern und erhalte deine Belohnung   ",
  "is_download": false,
  "reload_offers": false,
  "icon_hires": "https://icons.fyber-static.com/offercampaign/icon/large-largeicon.gif",
  "icon_lores": "https://icons.fyber-static.com/offercampaign/icon/small-smallicon.gif",
  "title": "Erreiche in Fun Game eine Tiefe von 9500 Metern",
  "virtual_currency": "Tokens",
  "attribution_window": 10,
  "type": "task",
  "ad_id": 1111111,
  "lpid": 2222222,
  "advertiser_id": 33333,
  "account_manager_id": 555555,
  "comment": "**Das Angebot gilt nur für neue Benutzer!**",
  "program_id": 7777777,
  "mobile_title": "Erreiche in Fun Game eine Tiefe von 9500 Metern",
  "url": "//aws.engine.fyber.com/show/fyber?appid&uid=pitis&client=sdk&device_model=&platform&appname=Android+Test&traffic_source&country_code=AA&pubid&ip=99.888.777.6&request_timestamp=1676971418380&request_id=12feedf4-07fb-4867-aa04-3485f31e709f&ad_id=1111111&ad_format=offer&group=Fyber&sig=215d5d78bad6aa8db6c2e45e45c5e56a7777f0cd",
  "is_free": true,
  "is_trackable": true,
  "rewd_curr": null,
  "rewd_amnt": 1243,
  "actn_text": "mobile_required_actions.download_and_start",
  "icon": "https://icons.fyber-static.com/offercampaign/icon/icon.gif",
  "user_task_category": "In-App Action",
  "user_task_category_id": 27,
  "user_task": {
    "id": 27,
    "icon": "https://icons.fyber-static.com/assets/11111/icons_mobile_original.svg"
  },
  "user_task_icon": "https://icons.fyber-static.com/assets/11111/icons2_mobile_original.svg",
  "is_highlighted": false,
  "store_id": "com.my.fungame",
  "size_tag": "80 MB",
  "is_video": false,
  "video": false,
  "initial_scarcity": 1,
  "required_actions": "",
  "action_steps": [
    {
      "step": "Installieren Fun Game!",
      "payout_distribution": 0,
      "action_id": "",
      "minimum_latency": null
    },
    {
      "step": "Erreiche eine Tiefe von 9500 Metern und erhalte deine Belohnung   ",
      "payout_distribution": 0,
      "action_id": "S2S_DEPTH_REACHED_9500",
      "minimum_latency": null
    }
  ],
  "action_description": "ACP-EDGE action description",
  "billing_relation_id": 0,
  "latency": 30,
  "dynamic_payout_enabled": false,
  "cost_model": "cost_per_engagement",
  "complexity": 100,
  "mobile_app_primary_category": "Games",
  "non_web_offer": true,
  "avg_latency": 0,
  "multi_payout": false,
  "instruction_steps": [],
  "asset_urls": [
    null
  ],
  "action_type": "complete_action",
  "creative_id": null
}

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.

For more details on Reward Handling, click here. 

Callback Structure and Behavior

DT calls your endpoint with an HTTP GET request. When we request your endpoint, we add in several parameters.