ayeT-Studios Rewarded Video HTML5 Web Integration Guide (v1.1)



Updates

2021-07-30: v1.1 - Updated SDK interface, reworked waterfall and header bidding, respect bid TTL, support CMPs (TCF 2 / GDPR) for all demand
2021-04-27: v1.0 - Initial Release of our HTML5 Video SDK


Introduction

The ayeT-Studios Rewarded Video SDK for HTML5 allows web publishers to request and run rewarded video ads within their page.
Our javascript library supports the following features:

- OpenRTB header bidding with bundled prebid.js
- Adserver functionality with custom waterfall demand sources, bid buckets and backfill
- Consecutive waterfall VAST tag validation and fallback handling for no-bid scenarios
- VAST and VPAID support
- Content isolation and parent page protection using iframe playback
- Native browser video rendering
- Automatic detection of external CMPs and support for TCF2 / GDPR consent handling
- Both S2S and signed clientside callbacks for user rewards



Topics

  1. Prerequisites
  2. Integration
  3. Initialization & Global Callback Handlers
  4. Requesting Video Ads
  5. Playing Video Ads
  6. Rewarding Users
  7. Appendix I: Conversion Callbacks



1. Prerequisites


Before integrating the video SDK in your site, you should have a publisher account, a placement for your site and a "Rewarded Video Adslot".

Also a correctly configured ads.txt is required (see Integration) and we highly recommend using a CMP (Consent Management Provider) on your website.

Without a compliant CMP and without requesting consent from affected GDPR & CCPA users, both fillrate and eCPM will be impacted significantly or no ads delivered at all.

2. Integration


To integrate our video sdk on your site, add the following script to the <head></head> section of your web-app or pages where videos are supposed to be played:

<script src="https://d1mys92jzce605.cloudfront.net/offerwall/js/ayetvideosdk.min.js"></script>					


The above script is around 35kb in size and will load additional required scripts (bidders, players, configuration) upon initialization.

Next please verify that the ads.txt on your server contains all requested entries listed for your placement in our dashboard in the Placement Details > Overview page.

3. Initialization & Global Callback Handlers


To initialize the SDK for a user, make the following asynchronous call that returns a Promise:

var placementId=3; // This is the numeric id of your web placement
AyetVideoSdk.init(placementId, "your user identifier").then(function() {
	console.log("finished initialization!");
});


To receive notifications for video playback events, the following global callbacks can be configured:

/* An error occured when trying to play a video ad. After this callback, no video is being rendered and a new ad has to be requested first: */
AyetVideoSdk.callbackError = function(e) {console.log("callbackError: "+JSON.stringify(e));};

/* After this callback, a video will start playing: */
AyetVideoSdk.callbackPlaying = function() {console.log("callbackPlaying");};

/* After this callback, playing the video is finished and the player is closed: */
AyetVideoSdk.callbackComplete = function() {console.log("callbackComplete");};

/* This callback is sent once a second while a video is being played: */
AyetVideoSdk.callbackProgess = function(remainingSeconds) {console.log("callbackProgess: "+Math.round(remainingSeconds)+"s remaining");};

/* This callback is sent if a video has been completed and the impression has gone through fraud checks (see "Rewarding Users" for more details): */
AyetVideoSdk.callbackRewarded = function(details) {appendLog("callbackRewarded: "+JSON.stringify(details));};

4. Requesting Video Ads


To request a video ad for your adslot, make the following asynchronous call:

AyetVideoSdk.requestAd(
	'your_rewarded_video_adslot_name',
	function() { // success callback function
		console.log("requestAd successful");
	},
	function(msg) { // error callback function
		appendLog("requestAd failed: "+msg);
	}
);	                


Make sure to not call requestAd before the initialization of the SDK is complete, otherwise the call will fail.
Also note, that after a success callback a video ad is ready to be played. However, depending on your video demand sources, successful bids will time-out after a while (usually 1-60 minutes).
It's advisable to make a requestAd call just in time when a video should be played.

5. Playing Video Ads


After a video ad has been successfully requested, the following calls are available to play an ad.
Please note that these functions should be called from a user-interaction (for example a click event) or from the requestAd success callback which itself has been called from a user-interaction.
Otherwise video autoplay will be rejected by most browsers and we must render an additional button over the video for the user to click, which lowers the acceptance and usability.

/* Play the ad in a pre-defined div (consult your account manager to determine if size & location is appropriate for all demand partners): */
AyetVideoSdk.playInPageAd('video_div');

/* Play the ad full size (100% of your page viewport): */
AyetVideoSdk.playFullsizeAd();

/* Play the ad fullscreen (this temporarily switches the browser to fullscreen mode): */
AyetVideoSdk.playFullscreenAd();


The different play...Ad functions will silently abort if an ad is already playing. In all other cases, they make use of the global callback handlers described in the Initialization & Global Callback Handlers section.

Additionally it makes sense to check if a video is ready to play, especially if there's a bigger expected delay between requestAd and play...Ad, for example:

/* This example assumes an ad was requested a longer time ago and we're unsure if the bid expired already */
if (AyetVideoSdk.isAdAvailable()) {
	AyetVideoSdk.playInPageAd('video_div');
} else {
	/* Either abort and notify the user or request and play a fresh ad: */
	AyetVideoSdk.requestAd(
		'your_rewarded_video_adslot_name',
		function() { // success callback function
			AyetVideoSdk.playInPageAd('video_div');
		},
		function(msg) { // error callback function
			appendLog("requestAd failed: "+msg);
		}
	);
}

6. Rewarding Users


There are two ways to reward users for rewarded video views, (1) Server2Server Conversion Callbacks and (2) Clientside Video SDK Callbacks.
The S2S Callbacks are usually sent to your server within 60 seconds after a completed & rewarded video view. See Appendix I: S2S Conversion Callbacks for more information on this topic.

The Clientside SDK Callbacks are received through the global AyetVideoSdk.callbackRewarded function shown in Initialization & Global Callback Handlers:

/* This callback is sent if a video has been completed and the impression has gone through fraud checks: */
AyetVideoSdk.callbackRewarded = function(details) {appendLog("callbackRewarded: "+JSON.stringify(details));};

/* Example output:
callbackRewarded: {"status":"success","rewarded":true,"externalIdentifier":"your user identifier","currency":10,"conversionId":"aef8cd370cfe-video-u94-adbcec159f76","signature":"f98c35ae4facef42dce5b31f6a5f9f0e8819b8ec"}
*/


Since these are clientside callbacks, they should not be trusted for important rewards like virtual currency. Instead you can send the response to your server and validate the callback signature serverside.
The signature is can be verified serverside with your publisher API key (found in our Dashboard > Account Settings > Api Key), like the following example (in PHP):

$signature = hash_hmac('sha1', $response['externalIdentifier'].$response['currency'].$response['conversionId'], $user->publisher->user->api_key);



9. Appendix I: S2S Conversion Callbacks


To handle video conversions with S2S Callbacks, first make sure your callback URL is setup correctly in your publisher placement.
To do so, navigate to Placements / Apps, edit your app placement and set the Callback Url to your server's postback url:

Also make sure that Send S2S Callbacks For Video Views is enabled for your rewarded video adslot(s) in Adslot Details > Overview.

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

A typical conversion callback sent by our server will look like this:
https://your-server.com/callback?network=ayetstudios&amount=10&external_identifier=username&payout_usd=0.007&adslot_id=16
* Note: This assumes you set external_identifier to username when calling AyetVideoSdk.init(...), the currency amount per view was set to 10 in your rewarded video adslot #16 and the delivered video had an eCPM of $7.00.

Hint: If you send callbacks from multiple different adslots (e.g. rewarded_video and offerwall) make sure to pass and validate {adslot_id} in your callback URL to determine if the conversion was a normal offer or a rewarded video.

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} | {uid}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}intValues 0 or 1. Indicator if the callback is conversion or chargeback. If set to 0 then it's conversion else it's chargeback.
{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.


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