Rewarded Video SDK for HTML5

The ayeT-Studios Rewarded Video SDK for HTML5 allows web publishers to request and run rewarded video ads within their page.

PreviousWeb integrations NextIn-app integrations

Last updated 25 days ago

Was this helpful?

Rewarded Video SDK for HTML5

The ayeT-Studios Rewarded Video SDK for HTML5 allows web publishers to request and run rewarded video ads within their page.

Eligible Placement & AdSlot Combinations

The table below shows all Placement & AdSlot Type combinations which allow you to utilize the Rewarded Video for Web integration.

Placement Type

AdSlot Type

Eligible Integration Type

Website

Rewarded Video

Rewarded Video SDK for HTML5

If you integrate the Rewarded Video for Web SDK while using a different Placement & AdSlot combination in the ayeT-Studios dashboard, you won't be able to send correct ad requests.

Getting Started

Before you start with the integration, make sure you:

Created an Account
Added a Placement
Added an AdSlot

You will find more details here:

Ads.txt

Adding an ads.txt to your domain is required (see Integration) to correctly utilize the Rewarded Video solution.

You can find the relevant ads.txt lines that you have to add to www.your-website.com/ads.txt under "Edit Placements" in your publisher dashboard.

CMP

We highly recommend using a CMP (Consent Management Platform) on your website.

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

There are two different options for you to integrate a CMP:

Self-Hosted CMP
- Look for a CMP that suits you
- Follow the integration docs of that CMP
CMP from Google AdSense (free of charge)
- Create a Google AdSense account
- Setup and integrate the Google CMP
- Our Team can assist with the setup

Supported Features

Our JavaScript library supports the following features:

OpenRTB header bidding with bundled prebid.js
Ad server functionality with custom waterfall demand sources, bid buckets and back fill
Consecutive waterfall VAST tag validation and fallback handling for no-bid scenarios
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 client-side callbacks for user rewards

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://cdn.ayet.io/offerwall/js/ayetvideosdk.min.js"></script>

The script above 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.

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
var externalIdentifier="{your user identifier}";
var optionalParameter=null; // or a string(32)
AyetVideoSdk.init(placementId, externalIdentifier, optionalParameter).then(function() {
	console.log("finished initialization!");
});

externalIdentifier is a string (up to 64 chars, min. 3 characters) you set to uniquely identify your user. It might be a UUID, a hashed email address or anything that allows you to persistently identify a user.

optionalParameter is an optional string (up to 32 chars) you can use to add an additional reporting dimension to the video statistics. It can be accessed and filtered in the video adslot statistics and the reporting API.

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.callbackProgress = function(remainingSeconds) {console.log("callbackProgress: "+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));};

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 not to 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. Depending on your video demand sources, successful bids will timeout after a while (usually 1-60 minutes). It's advisable to make a requestAd call just in time when a video should be played.

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('{your_html_video_div_id}');
} 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('{your_html_video_div_id}');
		},
		function(msg) { // error callback function
			appendLog("requestAd failed: "+msg);
		}
	);
}

While a video is playing, it's possible to externally interrupt the ad and destroy the player by making a call to destroy:

/* Interrupt a playing ad and destroy the player (to play another ad later, a new call to AyetVideoSdk.requestAd is required) */
AyetVideoSdk.destroy();

Rewarding Users

There are two ways to reward users for rewarded video views, (1) Clientside Video SDK Callbacks and (2) Server2Server Conversion Callbacks.

The S2S Callbacks are usually sent to your server within 60 seconds after a completed & rewarded video view.

Since rewarding users for video views in real time is usually important for a frictionless user flow, we recommend using (1) Clientside Video SDK Callbacks!

Server2Server Conversion Callbacks

For more information on Server2Server Conversion Callbacks please use this link:

Clientside Video SDK Callbacks

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"}
*/

/* Example output if custom parameters were set:
callbackRewarded: {"status":"success","rewarded":true,"externalIdentifier":"your user identifier","currency":10,"conversionId":"aef8cd370cfe-video-u94-adbcec159f76","custom_1":"bar", "custom_3":"foo","signature":"e35d78be4facef42dce5b31f6a5f9f0e8821c3de"}
*/

Please use AyetVideoSdk.callbackRewarded and not AyetVideoSdk.callbackComplete to reward users!

You can send the callback response to your server and validate the callback signature serverside. The signature can be verified serverside with your publisher API key (found in our Dashboard > Account Settings > Api Key), like the following example (in PHP). If custom parameters are present in the callback, they are also part of the signature. Signature calculation example:

$signature = hash_hmac('sha1',
	$response['externalIdentifier'] .
	$response['currency'] .
	$response['conversionId'] .
	(isset($response['custom_1']) ? isset($response['custom_1'] : '') .
	(isset($response['custom_2']) ? isset($response['custom_2'] : '') .
	(isset($response['custom_3']) ? isset($response['custom_3'] : '') .
	(isset($response['custom_4']) ? isset($response['custom_4'] : '') .
	(isset($response['custom_5']) ? isset($response['custom_5'] : '')
	, $user->publisher->user->api_key);

Passing Custom Parameters

To pass custom parameters to server-side conversion callbacks and clientside callbacks, the function AyetVideoSdk.setCustomParameter('custom_n', 'value') is available.

Where:

custom_n can be one of these: custom_1, custom_2, custom_3, custom_4, custom_5. value is a string (up to 64 chars).

Custom Parameters are up to 64 chars of length!

AyetVideoSdk.setCustomParameter can be called any time with the most recent content used when a video view is completed.

/* Example of setting custom parameters: */
AyetVideoSdk.setCustomParameter("custom_1", "bar");
AyetVideoSdk.setCustomParameter("custom_3", "foo");

/* Example of unsetting custom parameter: */
AyetVideoSdk.setCustomParameter("custom_1", null);

Error Handling / Error Codes

There are two different callback methods for errors in the ayetvideosdk:

The global AyetVideoSdk.callbackError function that can be configured and is invoked for any type of callback errors: AyetVideoSdk.callbackError = function(e) {console.log("callbackError: "+JSON.stringify(e));};
The local error function in AyetVideoSdk.requestAd(adslotName, successFunction, errorFunction); that is invoked if an ad request did not succeed

Possible error messages for AyetVideoSdk.callbackError:

no adTagUrl set, no video ad available.

No ad was requested using requestAd or the request was unsuccessful.

provided ad unit did not start.

The player was unable to start the playback of the video.

provided ad unit stalled.

The video playback was interrupted for > 5 seconds and aborted (for ex. network issues).

provided ad unit is corrupt.

The video file or companion ads are corrupted or not supported (for ex. codecs).

all bids expired or contained invalid VAST responses, unable to render ad.

No valid bids response was found or all bids responses are expired (please request a new ad).

unrecoverable ad error: {message}

Other video player or VAST parser errors that were not covered above.

Possible error messages for the AyetVideoSdk.requestAd(...) error callback:

no fill.

This is expected behaviour: There is currently no video ad available for the device & user.

unhandled client exception.

Unspecified exception in the ayetvideosdk during ad request.

invalid server response.

Error communicating with our servers, check your internet connection & make sure ad blockers are disabled.

cap reached.

The user/device video cap has been reached.

Conversion Callbacks & Currency Handling

Learn about:

Setting up callbacks
IP Whitelists
Securing callbacks using HMAC Security Hash
Testing callbacks

Click on the link below:

PreviousWeb integrations NextIn-app integrations

Last updated 25 days ago

Was this helpful?

Eligible Placement & AdSlot Combinations

The table below shows all Placement & AdSlot Type combinations which allow you to utilize the Rewarded Video for Web integration.

Placement Type

AdSlot Type

Eligible Integration Type

Website

Rewarded Video

Rewarded Video SDK for HTML5

If you integrate the Rewarded Video for Web SDK while using a different Placement & AdSlot combination in the ayeT-Studios dashboard, you won't be able to send correct ad requests.

Getting Started

Before you start with the integration, make sure you:

Created an Account
Added a Placement
Added an AdSlot

You will find more details here:

Ads.txt

Adding an ads.txt to your domain is required (see Integration) to correctly utilize the Rewarded Video solution.

You can find the relevant ads.txt lines that you have to add to www.your-website.com/ads.txt under "Edit Placements" in your publisher dashboard.

CMP

We highly recommend using a CMP (Consent Management Platform) on your website.

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

There are two different options for you to integrate a CMP:

Self-Hosted CMP
- Go to
- Look for a CMP that suits you
- Follow the integration docs of that CMP
CMP from Google AdSense (free of charge)
- Create a Google AdSense account
- Setup and integrate the Google CMP
- Our Team can assist with the setup

Supported Features

Our JavaScript library supports the following features:

OpenRTB header bidding with bundled prebid.js
Ad server functionality with custom waterfall demand sources, bid buckets and back fill
Consecutive waterfall VAST tag validation and fallback handling for no-bid scenarios
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 client-side callbacks for user rewards

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://cdn.ayet.io/offerwall/js/ayetvideosdk.min.js"></script>

The script above 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.

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
var externalIdentifier="{your user identifier}";
var optionalParameter=null; // or a string(32)
AyetVideoSdk.init(placementId, externalIdentifier, optionalParameter).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.callbackProgress = function(remainingSeconds) {console.log("callbackProgress: "+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));};

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);
	}
);

Playing Video Ads

/* 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();

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('{your_html_video_div_id}');
} 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('{your_html_video_div_id}');
		},
		function(msg) { // error callback function
			appendLog("requestAd failed: "+msg);
		}
	);
}

While a video is playing, it's possible to externally interrupt the ad and destroy the player by making a call to destroy:

/* Interrupt a playing ad and destroy the player (to play another ad later, a new call to AyetVideoSdk.requestAd is required) */
AyetVideoSdk.destroy();

Rewarding Users

There are two ways to reward users for rewarded video views, (1) Clientside Video SDK Callbacks and (2) Server2Server Conversion Callbacks.

The S2S Callbacks are usually sent to your server within 60 seconds after a completed & rewarded video view.

Since rewarding users for video views in real time is usually important for a frictionless user flow, we recommend using (1) Clientside Video SDK Callbacks!

Server2Server Conversion Callbacks

For more information on Server2Server Conversion Callbacks please use this link:

💡Callbacks & Testing

Clientside Video SDK Callbacks

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"}
*/

/* Example output if custom parameters were set:
callbackRewarded: {"status":"success","rewarded":true,"externalIdentifier":"your user identifier","currency":10,"conversionId":"aef8cd370cfe-video-u94-adbcec159f76","custom_1":"bar", "custom_3":"foo","signature":"e35d78be4facef42dce5b31f6a5f9f0e8821c3de"}
*/

Please use AyetVideoSdk.callbackRewarded and not AyetVideoSdk.callbackComplete to reward users!

$signature = hash_hmac('sha1',
	$response['externalIdentifier'] .
	$response['currency'] .
	$response['conversionId'] .
	(isset($response['custom_1']) ? isset($response['custom_1'] : '') .
	(isset($response['custom_2']) ? isset($response['custom_2'] : '') .
	(isset($response['custom_3']) ? isset($response['custom_3'] : '') .
	(isset($response['custom_4']) ? isset($response['custom_4'] : '') .
	(isset($response['custom_5']) ? isset($response['custom_5'] : '')
	, $user->publisher->user->api_key);

Passing Custom Parameters

To pass custom parameters to server-side conversion callbacks and clientside callbacks, the function AyetVideoSdk.setCustomParameter('custom_n', 'value') is available.

Where:

custom_n can be one of these: custom_1, custom_2, custom_3, custom_4, custom_5. value is a string (up to 64 chars).

Custom Parameters are up to 64 chars of length!

AyetVideoSdk.setCustomParameter can be called any time with the most recent content used when a video view is completed.

/* Example of setting custom parameters: */
AyetVideoSdk.setCustomParameter("custom_1", "bar");
AyetVideoSdk.setCustomParameter("custom_3", "foo");

/* Example of unsetting custom parameter: */
AyetVideoSdk.setCustomParameter("custom_1", null);

Error Handling / Error Codes

There are two different callback methods for errors in the ayetvideosdk:

The global AyetVideoSdk.callbackError function that can be configured and is invoked for any type of callback errors: AyetVideoSdk.callbackError = function(e) {console.log("callbackError: "+JSON.stringify(e));};
The local error function in AyetVideoSdk.requestAd(adslotName, successFunction, errorFunction); that is invoked if an ad request did not succeed

Possible error messages for AyetVideoSdk.callbackError:

no adTagUrl set, no video ad available.

No ad was requested using requestAd or the request was unsuccessful.

provided ad unit did not start.

The player was unable to start the playback of the video.

provided ad unit stalled.

The video playback was interrupted for > 5 seconds and aborted (for ex. network issues).

provided ad unit is corrupt.

The video file or companion ads are corrupted or not supported (for ex. codecs).

all bids expired or contained invalid VAST responses, unable to render ad.

No valid bids response was found or all bids responses are expired (please request a new ad).

unrecoverable ad error: {message}

Other video player or VAST parser errors that were not covered above.

Possible error messages for the AyetVideoSdk.requestAd(...) error callback:

no fill.

This is expected behaviour: There is currently no video ad available for the device & user.

unhandled client exception.

Unspecified exception in the ayetvideosdk during ad request.

invalid server response.

Error communicating with our servers, check your internet connection & make sure ad blockers are disabled.

cap reached.

The user/device video cap has been reached.

Conversion Callbacks & Currency Handling

Learn about:

Setting up callbacks
IP Whitelists
Securing callbacks using HMAC Security Hash
Testing callbacks

Click on the link below:

💡Callbacks & Testing