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 center key to view ad or manually close with the softleft key.

Responsive - a responsive ad (or 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. Whichever size is defined by the developer, KaiAds will try to find best possible ad, to fill as much space as possible.

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 provides one single method getKaiAd(...). The ad should be requested after the document.body element finished loading, and the dom is read, eg.

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

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 implementing KaiAds SDK the developer should consider user experience, and usability in general.

Displaying a full screen ad on app's startup is sensible, and yet if the user is on a slow network the ad might take a long time to load, forcing user to just hang.

During this time the user could instead see a relevant "loading..." screen. It would also make sense to set the timeout to 5-10 seconds, making the wait time reasonable.

Another example would be end of game or session, or a pause in usage. During this time showing an ad is a common practice. Displaying preloaded ads is the best possible scenario.

Alternatively, if there is no preloaded ad, and the developer is trying to load and display an ad in real time, the slow network might come into play again, and the timeout should be again set to something reasonable.

Usage // Fullscreen Ad


Requests 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 resolved, loaded, and is ready to display
		
		// 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, application 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 before deciding the ad request is unresponsive

Usage // Responsive Ad


Requests responsive ad, and display it immediately after it's ready.
Add or create a container for the ad

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

getKaiAd({
	publisher: 'yourPublisherID',
	app: 'yourAppName',
	slot: 'yourSlotName',
	
	h: 264,
	w: 240,
	// Max supported size is 240x264
	

	// If container (HTMLElement) is not provided,
	// a fullscreen ad will be requested

	// A fullscreen ad it will be
	// absolutely positioned and document.body appended

	// if container provided,
	// a responsive banner type ad will be requested
	container: document.getElementById('ad-container'),

	onerror: err => console.error('Custom catch:', err),
	onready: ad => {
		// Ad is resolved, loaded, and 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 as such 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, application 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 design pattern is to pre-load the ad and show it upon certain events, such as ending of a game level. This is achieved by wrapping ad.call('display') in an event listener, in this example, a button click.


getKaiAd({
	publisher: 'yourPublisherID',
	app: 'your app name',
	slot: 'your alot name',
	onerror: err => console.error('Custom catch:', err),
	onready: ad => {
		// Ad is resolved, loaded, and is ready to display
		
		// 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')
		})
	}
})				
		

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 resolved, loaded, and is ready to display
		
		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') )
	}
})				
		

Onerror codes


Error codes returned by onerror.
Code Description
1 Document body not yet ready
2 Ad onready function is required
3 Ad container dimension is too small
4 Ad iframe is gone
5 Ad request timed out
6 Server responded 'no ad'. (Maybe specified ad dimension is not available)
7 Frequency capping in effect
8 Configuration error: Missing w & h
9 Bad server response
10, 11, 12 Internal error
13 Cannot process server response
14 No server response
15 Configuration error: Invalid test parameter
16 ad.call('display') is not allowed to be called more than once