ayeT-Studios Publisher In-App Webview Offerwall Integration Guide (v1.2)
Publisher Documentation Overview
- API Placement - Documentation
- Android Placement - SDK Integration Guide
- iOS Placement - Swift SDK Integration Guide
- Unity SDK Integration Guide
- Web Placement - In-App Webview Offerwall Integration Guide
- Web Placement - Mobile & Desktop Browser Offerwall Integration Guide
- Rewarded Video HTML5 Web Integration Guide
Updates
2019-07-19: v1.2 - Updated documentation to reflect the adslot changes
2018-11-29: v1.1 - Release of our updated web offerwall with dedicated webview support
2018-02-08: v1.0 - Initial Release of our Publisher Web Offerwall
Introduction
The ayeT-Studios Publisher In-App Webview Offerwall allows you to easily monetize your apps without support for our native SDKs and reward your users with in-app 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 and works well alongside traditional in-app purchases.Topics
- Prerequisites
- In-App Webview Offerwall Placements
- Retrieve your Web Offerwall URL - Mandatory Parameters
- Example: Usage in Android WebView
- 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. In-App Webview Offerwall Adslots
This type of web offerwall is intended to be called directly within your apps in a webview. These offerwalls are not intended to be loaded in an external browser or on PCs.
For browser based offerwalls check out our Mobile & Desktop Browser Offerwall Integration Guide.
Common use cases are:
Technically, the offerwall has to be implemented directly in the app by using a Webview.
To create an in-app web adslot, go to Add Application / Placement in your publisher account under Placements / Apps.
Select Web as placement type and Offerwall (In-App) as adslot type.
For browser based offerwalls check out our Mobile & Desktop Browser Offerwall Integration Guide.
Common use cases are:
- Integration in a native Android or iOS app
- Impossible to use our dedicated Android, iOS & Unity SDKs
- Access to the devices' advertising id (GAID or IDFA)
Technically, the offerwall has to be implemented directly in the app by using a Webview.
To create an in-app web adslot, go to Add Application / Placement in your publisher account under Placements / Apps.
Select Web as placement type and Offerwall (In-App) as adslot type.
3. Retrieve your Webview Offerwall URL - Mandatory Parameters
The URL template for our web offerwall looks like this:
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.
https://www.ayetstudios.com/offers/web_offerwall/ADSLOT_ID?advertising_id={ADVERTISING_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:
Parameter | Mandatory | Description |
advertising_id | yes | Google Advertising ID (GAID) or Apple IDFA |
external_identifier | no | Your identifier for the calling user - helps you identifying and matching S2S conversion callbacks |
android_id | no | Optional: Can be used instead of GAID if it's impossible to fill the advertising_id, NOT recommended |
4. Example: Usage in Android WebView
If you're developing an app built upon native Android componenents, you can load the offerwall like this:
layout.xml:
MyOfferwall.java:
Attention: Make sure you don't forget to enable Javascript for your WebView!
layout.xml:
<WebView android:id="@+id/myWebViewId" android:layout_width="match_parent" android:layout_height="match_parent"/>
MyOfferwall.java:
... String offerwallUrl = "https://www.ayetstudios.com/offers/web_offerwall/1?advertising_id="+adInfo.getId()+"&gaid_limited_string="+adInfo.isLimitAdTrackingEnabled()+"&external_identifier=myuser12"; // NOTE: check this for information on how to obtain the GAID -> http://www.androiddocs.com/google/play-services/id.html WebView myWebView = (WebView) findViewById(R.id.myWebViewId); myWebView.getSettings().setJavaScriptEnabled(true); myWebView.setWebViewClient(new WebViewClient() { @Override public boolean shouldOverrideUrlLoading(WebView view, String url) { if( URLUtil.isNetworkUrl(url) ) { return false; } try { Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url)); startActivity( intent ); } catch (Exception e) { return false; } return true; } }); myWebView.loadUrl(offerwallUrl);
Attention: Make sure you don't forget to enable Javascript for your WebView!
5. Currency Handling & Conversion Callbacks
For web placements, 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 web placement and set the Callback Url to your server's postback url:
If this is the callback url your set for your web placement:
A typical conversion callback sent by our server will look like this:
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:
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:
If your want to restrict postbacks to our callback server IPs, please whitelist the following IPs and check back regularly for possible changes:
To do so, navigate to Placements / Apps, edit your web placement and set the Callback Url to your server's postback url:

If this is the callback url your set for your web placement:
https://your-server.com/callback?network=ayetstudios&amount={currency_amount}&uid={uid}&device={advertising_id}&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&uid=username&device=[ADVERTISING_ID]&payout_usd=0.36* Note: This assumes you passed &external_identifier=username to the webview URL, the currency conversion rate in your adslot 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} | string | Unique transaction id - use for duplicate checks |
{payout_usd} | float | The actual conversion payout in USD |
{currency_amount} | float | The amount of currency the user earned (taken from your offerwall currency configuration) |
{external_identifier} | {uid} | string | The user identifier (EXTERNAL IDENTIFIER) originally passed in the web offerwall link |
{user_id} | integer | Our internal id for this offerwall user |
{placement_identifier} | string | The placement_identifier for which the conversion occured |
{adslot_id} | int | The id of the adslot for which the conversion occured |
{ip} | string | Converting device's IP address if known, 0.0.0.0 otherwise |
{offer_id} | int | Offer ID of the converting offer |
{offer_name} | string | Name / title of the converting offer |
{device_uuid} | string | ayeT-Studios internal device identificator |
{device_make} | string | Device manufacturer |
{device_model} | string | Device model |
{advertising_id} | string | Device advertising id (GAID/IDFA) if known, otherwise empty |
{sha1_android_id} | string | Device sha1 hashed android id if known, otherwise empty |
{sha1_imei} | string | Device sha1 hashed imei if known, otherwise empty |
{task_name} | string | Only available for cpe campaigns, shows individual task name for that conversion. |
{currency_identifier} | string | Shows virtual currency name as set in adslot. |
{currency_conversion_rate} | decimal | Shows currency conversion rate used to calculate user currency for the given conversion. |
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¤cy_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.140Last IP List Update: 2017-04-07