KaiAds SDK

Monetize your app

Overview

Types of Ads


There are 2 types:

Fullscreen - a fullscreen ad covers the entire screen. Users can either click the softright key to view the ad or close the ad with the softleft key.

Responsive - a responsive ad (banner ad) is displayed within a container specified in your app. Users can navigate to the ad with directional keys and hit center key to view. KaiAds will try to find a best fit ad for the specified size.

Get started


1) Head to https://publishers.kaiads.com/ to get your publisher ID.

2) Download the KaiAds SDK

3) After downloading, unzip and include kaiads.min.js in your app.

4) See usage examples below. Technically the SDK only provides one method getKaiAd which requests an ad.


// request an ad when the DOM is loaded
document.addEventListener("DOMContentLoaded", () => {
// getKaiAd( config )
});
			

Usage

Usage // Timeout


The timeout setting is set using milliseconds, the default value is 60 * 1000, or 60 seconds.
When using KaiAds SDK the developer should consider user experience in general.

Displaying a fullscreen ad in real time might force users to wait for a long time on a slow network.

In this case timeout should be set e.g. 5-10 seconds.

Alternatively preloading ads is highly recommended.

Usage // Fullscreen Ad


Request a fullscreen ad and display it immediately after it's ready.

getKaiAd({
	publisher: 'yourPublisherID',
	app: 'yourAppName',
	slot: 'yourSlotName',
	onerror: err => console.error('Custom catch:', err),
	onready: ad => {
		// Ad is ready to be displayed
		// calling 'display' will display the ad
		ad.call('display')
	}
})
		
Parameter Type Description
publisher String Required to associate earnings/impressions to your account
app String Optional, application name, used for reporting, for your own convenience
slot String Optional, ad slot name, used for reporting, for your own convenience
test Integer Enable test mode. Please set this to 1 when testing the ad, 0 when in production
timeout Integer (in milliseconds) Milliseconds to wait for loading the ad

Usage // Responsive Ad


Request responsive ad, and display it immediately after it's ready.
A container element has to be provided, otherwise a fullscreen will be requested instead.

<div id='ad-container'></div>

getKaiAd({
	publisher: 'yourPublisherID',
	app: 'yourAppName',
	slot: 'yourSlotName',
	
	h: 264,
	w: 240,

	// Max supported size is 240x264
	// container is required for responsive ads
	container: document.getElementById('ad-container'),
	onerror: err => console.error('Custom catch:', err),
	onready: ad => {

		// Ad is ready to be displayed
		// calling 'display' will display the ad
		ad.call('display', {

			// In KaiOS the app developer is responsible
			// for user navigation, and can provide
			// navigational className and/or a tabindex
			tabindex: 0,

			// if the application is using
			// a classname to navigate
			// this classname will be applied
			// to the container
			navClass: 'items',

			// display style will be applied
			// to the container block or inline-block
			display: 'block',
		})
	}
})
	
Parameter Type Description
publisher String Required to associate earnings/impressions to your account
app String Optional, application name, used for reporting, for your own convenience
slot String Optional, ad slot name, used for reporting, for your own convenience
container HTML element Ad will be displayed inside of this container
h Integer Max allowed height of ad
w Integer Max allowed width of ad
test Integer Enable test mode. Please set this to 1 when testing the ad, 0 when in production
timeout Integer (in milliseconds) Milliseconds to wait before deciding the ad request is unresponsive

Examples

Examples // Pre-loading


A common pattern is to load the ad in advance and display it at natural transition points in the flow of your app, such as the ending of a game level. In this example, ad.call('display') is wrapped in a click event handler.


getKaiAd({
	publisher: 'yourPublisherID',
	app: 'yourAppName',
	slot: 'yourSlotName',
	onerror: err => console.error('Custom catch:', err),
	onready: ad => {
		// Ad is ready to be displayed
		// custom event
		let button = document.getElementById('button')
		button.addEventListener('click', function btnListener() {
			button.removeEventListener(‘click’, btnListener)
			// calling 'display' will display the ad
			ad.call('display')
		})
	}
})				
		

Examples // Website Integration


Integrating KaiAds SDK on a website instead of a KaiOS app is also possible. If you want to restrict KaiAds to KaiOS devices only, we recommend checking the user agent string.                 


if (navigator.userAgent.toLowerCase().indexOf('kaios') > -1){
    getKaiAd({
        publisher: 'yourPublisherID',
        app: 'yourWebsiteName',
        slot: 'yourSlotName',
        onerror: err => console.error('Custom catch:', err),
        onready: ad => {
            // Ad is ready to be displayed
            // calling 'display' will display the ad
            ad.call('display')
        }
    })
}			
			

Ad Events


The SDK provides a feedback on its and user activities.
Event Description
click User clicked the ad
close User closed the ad
display Ad sucessfully displayed on device

getKaiAd({
	publisher: 'yourPublisherID',
	app: 'yourAppName',
	slot: 'yourSlotName',
	onerror: err => console.error('Custom catch:', err),
	onready: ad => {
		
		// Ad is ready to be displayed
		let button = document.getElementById('button')
		button.addEventListener('click', function btnListener() {

			button.removeEventListener(‘click’, btnListener)

			// calling 'display' will display the ad
			ad.call('display')
		})

		// user clicked the ad
		ad.on('click', () => console.log('click event') )

		// user closed the ad (currently only with fullscreen)
		ad.on('close', () => console.log('close event') )

		// the ad succesfully displayed
		ad.on('display', () => console.log('display event') )
	}
})				
		

Error codes


Error codes returned by onerror.
Code Error Notes
1 Document body not yet ready Please invoke getKaiAd after the DOMContentLoaded event.
2 Ad onready function is required Please implement the onready function to handle the returned ad.
3 Ad container dimension is too small Try increasing the width/height parameters.
4 Ad iframe is gone The ad iframe may have been acidentally removed.
5 Ad request timed out Try another network or adjust the timeout parameter.
6 Server responded 'no ad' The specified ad dimension may not available, try adjusting the width/height.
7 Frequency capping in effect Frequency capping is the limit on how often the device can request for an ad, please try again later.
8 Configuration error: Missing w & h Please provide the width and height parameters for getKaiAd.
9 Bad server response Server error, please contact support.
10, 11, 12 Internal error SDK internal error, please contact support.
13 Cannot process server response Server error, please contact support.
14 No server response Server error, please contact support.
15 Configuration error: Invalid test parameter The test parameter should either be 1 or 0.
16 ad.call('display') is not allowed to be called more than once An ad container should only be displaying ads once.
17 Cannot fetch settings Please provide the correct configurations before invoking getKaiAd.