ayeT-Studios Mobile & Desktop Web Offerwall Integration Guide (v1.2.1)



Updates

2022-06-14: v1.2.2 - Updated documentation to introduce custom parameters for postback URLs and Offerwall URL
2020-08-11: v1.2.1 - Updated documentation to introduce new parameters to differentiate chargebacks from conversions
2019-07-19: v1.2 - Updated documentation to reflect the adslot changes
2018-11-29: v1.1 - Release of our updated web offerwall with desktop support
2018-02-08: v1.0 - Initial Release of our Publisher Web Offerwall


Introduction

The ayeT-Studios Publisher Browser Web Offerwall allows you to easily monetize your desktop and mobile traffic and reward your users with virtual currency. Your users get access to our offerwalls, allowing them to earn currency for completing tasks such as trying new apps, answering surveys, signing up for free trials or watching video ads. The integration is simple and allows you to receive callbacks and handle user wallets yourself.




Topics

  1. Prerequisites
  2. Dedicated Browser Offerwall Placements
  3. Your Browser Offerwall Link - Mandatory Parameters
  4. Currency Handling & Conversion Callbacks





1. Prerequisites


Before integrating the offerwall in your app or website, you should sign up for a publisher account. Activate your account and login as publisher.

2. Dedicated Browser Offerwall Adslots


This type of web offerwall is intended to be called directly in an actual browser and is not suited for webview (in-app) integration. If you're looking for a tighter integration in an app, please check our available SDKs or use the In-App Webview Offerwall.

Common use cases for a web offerwall are:
  • Use in a mobile website, either by opening a new tab or in an iframe
  • Support Desktop, iOS and Android users both seamlessly and cross-platform

Technically, the offerwall has to be implemented by opening a new browser tab or loading the offerwall link inside an iframe.

To create a browser offerwall, go to Add Application / Placement in your publisher account under Placements / Apps.
Select Web as placement type and Web Offerwall as the first adslot you create for the placement.

3. Your Browser Offerwall Link - Parameters


The URL template for our web offerwall looks like this:

https://www.ayetstudios.com/offers/web_offerwall/ADSLOT_ID?external_identifier={EXTERNAL_USER_IDENTIFIER}


To retrieve the URL for one of your web offerwall adslots, click on "Edit" next to an adslot under Placements / Apps and retrieve the Integration URL in the modal.

URL Parameters:

ParameterMandatoryDescription
external_identifieryesYour identifier for the calling user - this is mandatory and allows you to attribute our Server2Server conversion callbacks to a specific user (returned as {external_identifier})
custom_1noCustom parameter to pass variables to the conversion callbacks
custom_2noCustom parameter to pass variables to the conversion callbacks
custom_3noCustom parameter to pass variables to the conversion callbacks
custom_4noCustom parameter to pass variables to the conversion callbacks
custom_5noCustom parameter to pass variables to the conversion callbacks

4. Currency Handling & Conversion Callbacks


For web offerwalls, you have to manually manage your users currencies on your own servers. You can configure a conversion callback url in our publisher dashboard.
To do so, navigate to Placements / Apps, edit your placement and set the Callback Url to your server's postback url:


If this is the callback url your set for your offerwall placement:
https://your-server.com/callback?network=ayetstudios&amount={currency_amount}&external_identifier={external_identifier}&payout_usd={payout_usd}

A typical conversion callback sent by our server will look like this:
https://your-server.com/callback?network=ayetstudios&amount=360&external_identifier=username&payout_usd=0.36
* Note: This assumes you set external_identifier to username in the original offerwall url for that user, the currency conversion rate in your placement was 1000 per $1 and the user completed an offer with a $0.36 payout.

Important: Your server must always reply with an HTTP 200 status code to our postbacks. Otherwise we will resend the postback 12 times over a span of one hour before giving up.

Available Macros for Postback URLs:
{transaction_id}stringUnique transaction id - use for duplicate checks. If chargeback it's prepend with r-
{payout_usd}floatThe actual conversion payout in USD. If chargeback value is negative.
{currency_amount}floatThe amount of currency the user earned (taken from your offerwall currency configuration). If chargeback value is negative.
{external_identifier}stringThe user identifier (EXTERNAL IDENTIFIER) originally passed in the web offerwall link
{user_id}integerOur internal id for this offerwall user
{placement_identifier}stringThe placement_identifier for which the conversion occured
{adslot_id}intThe id of the adslot for which the conversion occured
{ip}stringConverting device's IP address if known, 0.0.0.0 otherwise
{offer_id}intOffer ID of the converting offer
{offer_name}stringName / title of the converting offer
{device_uuid}stringayeT-Studios internal device identificator
{device_make}stringDevice manufacturer
{device_model}stringDevice model
{advertising_id}stringDevice advertising id (GAID/IDFA) if known, otherwise empty
{sha1_android_id}stringDevice sha1 hashed android id if known, otherwise empty
{sha1_imei}stringDevice sha1 hashed imei if known, otherwise empty
{is_chargeback}intEither 0 or 1. Indicator if the callback is a conversion (0) or a chargeback (1).
{chargeback_reason}stringReason why chargeback created. Only available if is_chargeback set to 1.
{chargeback_date}stringDate of chargeback creation. Only available if is_chargeback set to 1.
{task_name}stringOnly available for cpe campaigns, shows individual task name for that conversion.
{currency_identifier}stringShows virtual currency name as set in adslot.
{currency_conversion_rate}decimalShows currency conversion rate used to calculate user currency for the given conversion.
{custom_1}stringCustom parameter to pass variables to the conversion callbacks
{custom_2}stringCustom parameter to pass variables to the conversion callbacks
{custom_3}stringCustom parameter to pass variables to the conversion callbacks
{custom_4}stringCustom parameter to pass variables to the conversion callbacks
{custom_5}stringCustom parameter to pass variables to the conversion callbacks


Postback Verification with HMAC Security Hash (optional):
Our server will always add a custom header, X-Ayetstudios-Security-Hash, containing a SHA256 HMAC hash of the request parameters and your publisher api key.
Your API key can be found in your dashboard at ayetstudios.com under settings.

To verify the hash, perform the following steps:
(1) Get all request parameters
(2) Order the request parameters alphabetically
(3) Build and compare the HMAC hash using the ordered request parameter string and your API key

PHP Example:
ksort($_REQUEST, SORT_STRING);
$sortedQueryString = http_build_query($_REQUEST, '', '&'); // "adslot_id=123&currency_amount=100&payout_usd=1.5...."
$securityHash = hash_hmac('sha256', $sortedQueryString, 'YOUR PUBLISHER API KEY');
if($_SERVER['HTTP_X_AYETSTUDIOS_SECURITY_HASH']===$securityHash) { // actually sent as X-Ayetstudios-Security-Hash but converted by apache2 in this example
    // success
}
else {
    // invalid signature
}                    


If your want to restrict postbacks to our callback server IPs, please whitelist the following IPs and check back regularly for possible changes:
35.165.166.40
35.166.159.131
52.40.3.140	    
Last IP List Update: 2017-04-07