Integrating via REST API

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. 

Before you can configure the DT 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 DT Offer Wall tab within your App.
  3. Select a placement. 
    mceclip1.png
  4. Make sure Status is set to Active.
  5. Select the currency you wish to use for rewards from the Virtual currency dropdown menu.
  6. 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).
  7. Select the Round up low rewards to 1 unit of virtual currency (recommended).
  8. Click Save to save your configuration.

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

mceclip2.png

The next step is to activate the REST API.

Activating the REST API

  1. Click on  located at the top right corner on the DT Offer Wall Publisher Dashboard
  2. Click the app you desire to integrate from the app list 

  3. Click Settings 


To Initiate the generation of a REST API key, kindly contact your dedicated DT Account Manager. Once receiving the API key it 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 API key.

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. 

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

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

iPhone Version Values

"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 Version Values

"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 Version Values

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

Unknown Version
If phone_version is left blank, it is considered that the version is unknown, and DT filters the request.

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=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
  1. Concatenate the resulting string with your API Key. For example: 

API Key Example: 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=1585187676&uid=player1&e95a21621a1865bcbae3bee89c4d4f84
  1. Hash the resulting string using SHA1. Result example:
68fc8e87db598e2149b4f72379fc2efd69309787
  1. 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=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: code implementation 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=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.

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

If you want to request all offers except one or more categories (blacklisting), please use the filter configuration in the DT 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

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.

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 HTTP 200 OK, the response body will contain the offers in the format you chose upon requesting. We've provided a successful response example, as well as an explanation for the parameters.

code 200 OK


    {
	"code": " OK" ,
	"message": "OK",
	"count": 1,
	"pages": 1,
	“information" : {
	"app_name": "SP Test App" ,
 	"appid": 157,
"placement_id": "",
"virtual_currency_sale_enabled": false, "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",
"store_id": "com.ovivo.eatrepeat",
"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": 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" } "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/1333/38839/e7aa883d-4237-4d1f-ae3a-924f4bf02525_low.mp4", "raw": "https://ofw-assets.fyber.com/offer_campaign/1333/38839/e7aa883d-4237-4d1f-ae3a-924f4bf02525_raw.mp4", "high": "https://ofw-assets.fyber.com/offer_campaign/1333/38839/e7aa883d-4237-4d1f-ae3a-924f4bf02525_high.mp4", "medium": "https://ofw-assets.fyber.com/offer_campaign/1333/38839/e7aa883d-4237-4d1f-ae3a-924f4bf02525_medium.mp4" } ], "url": "//aws.fyber.com/show/fyber?appid=1246&uid=marcelo&client=api&device_model=&platform=android&appname=+1246+Product+Android+Test&traffic_source=offer_api&country_code=DE&pubid=249&ip=62.96.69.0&request_timestamp=1676985764323&request_id=090172a5-7e1b-4881-9cbc-c06c2721e7ac&timestamp=1676968753&ad_id=151521&ad_format=offer&group=Fyber&gdpr_privacy_consent=0&sig=2797caf0485ee6fed3f8bcebe5075de900c68ea9" } ] }

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.

Response Element Explanation
response The complete response is 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 DT 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 DT Publisher Control Panel.
appid The application id used by DT to identify your specific application. You can find your ID in the DT Publisher Control Panel in the ‘Integration’ section of your application. This element should match the parameter appid of your request.
placement_id 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.
virtual_currency_sale_enabled This is a boolean field identifying if the publisher is running a virtual_currency sale. If the flag is enabled, then the reward will be multiplied.
virtual_currency The name of your currency as entered in the DT Publisher Control Panel. This element represents the country of the user, which DT 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 field contains the URL to Offer Wall status page where the user can see all of the offers he has in progress, click on one and file a report if needed.
report_url This field contains the URL to the report form for a specific offer after a user has already clicked and started it.
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
titleteaser 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.
store_id Advertised app  package name on Google Play or Apple IStore 
detailed_actions_text Represents instructions on each offer step
instruction_steps Steps for the user to follow to get the reward
mobile_app_primary_category Advertised app store category on Google Play or Apple IStore 
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 DT Publisher Control Panel.
net_payout_usd This element contains the amount of virtual currency paid out to the user in USD before applying the virtual currency exchange rate.
action_steps List of action steps required to complete the offer. Each item in the list contains information about the actions such as action_id, step (description), minimum_latency, payout_distribution and rewd_amt.
asset_urls List of URLs pointing to the assets included in the offer. These assets can include images, videos, documents, or any other digital files that are relevant to the offer.
url

This url points to the show endpoint, which should be called when a user decides to complete an offer, as it contains specific details about the particular offer. 

Note that within the show endpoint response, the field offer_url is the url that should be used by the publisher to send the user to complete the offer. Read more about show endpoint here.

limit Limit number of offers returned per page in response
Best practice: publishers that want to view all available offers for a request, can achieve this by setting a value as high as 1000.
attribution_window  The timeframe in which the user can claim the reward. Users who complete an offer beyond this timeframe are not eligible to receive the reward.

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:

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 occurred on the DT server

Signed Response

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

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.

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=1246&uid=pitis&client=api&device_model=&platform=android&appname=Android+Test&traffic_source=offer_sdk&country_code=DE&pubid=249&ip=84.130.238.0&request_timestamp=1676894767825&request_id=24feedf4-67fb-4862-aa04-3481f31e709f&ad_id=1606247&ad_format=offer&group=Fyber&rank=1&gdpr_privacy_consent=0&sig=273e6661d834d20703cfb04d28c15c464ac5cedf

 

/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": 1606247,
  "offer_url": "https://app.adjust.com/aytn3sk?campaign=ER_9500M_android_Fyber_CPE_WW_16_Feb&adgroup=1246&idfa=&gps_adid=&android_id=&ip_address=84.130.238.0&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=5226e006-3ed9-471c-915d-d08a512c5829&cost_type=CPE&cost_amount=280.0&cost_currency=USD",
  "country_code": "DE",
  "background_tracking": false,
  "mobile_app_identifier": "com.ovivo.eatrepeat",
  "preview": true,
  "preview_text": "Installieren Eat Repeat!\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-284cbe121e1b6c6731b4de64572191d2.gif",
  "icon_lores": "https://icons.fyber-static.com/offercampaign/icon/small-4c06e31d2829e52f33280b8a990f24a6.gif",
  "title": "Erreiche in Eat Repeat eine Tiefe von 9500 Metern",
  "virtual_currency": "Tokens",
  "attribution_window": 10,
  "type": "task",
  "ad_id": 1606247,
  "lpid": 1606247,
  "advertiser_id": 79456,
  "account_manager_id": 117789,
  "comment": "**Das Angebot gilt nur für neue Benutzer!**",
  "program_id": 1048311,
  "mobile_title": "Erreiche in Eat Repeat 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=DE&pubid&ip=84.130.238.0&request_timestamp=1676971418380&request_id=24feedf4-67fb-4862-aa04-3481f31e709f&ad_id=1606247&ad_format=offer&group=Fyber&sig=215d5d78bad6aa8db6c2e42e45c5e56a3143f0cd",
  "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/3974c89cbd60f824cf1e6817388bd63f.gif",
  "user_task_category": "In-App Action",
  "user_task_category_id": 27,
  "user_task": {
    "id": 27,
    "icon": "https://icons.fyber-static.com/assets/68418/icos_ofw_mobile_original.svg"
  },
  "user_task_icon": "https://icons.fyber-static.com/assets/68418/icos_ofw_mobile_original.svg",
  "is_highlighted": false,
  "store_id": "com.ovivo.eatrepeat",
  "size_tag": "73 MB",
  "is_video": false,
  "video": false,
  "initial_scarcity": 1,
  "required_actions": "",
  "action_steps": [
    {
      "step": "Installieren Eat Repeat!",
      "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.

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

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

Parameter Added Automatically Description
uid Always

The ID of the user to be created

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

action_id   Only if configured in the dashboard

An ID representing the event passed in the postbacks DT receives to notify that the user successfully completed the required event and is eligible to be rewarded.

 

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 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, so you'll only need to configure the endpoint itself.

7fc6c35-callback__1_.png

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 on your system and comparing your known list to the id sent in each reward callback.

Security token is generated for you to use when calculating the sid parameter. You may choose to change this token at any time.

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.

mceclip2.png

You have successfully set up DT Offer Wall via REST API.

Back to Top ⇧