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.

Best Practices


1. Preload your ads

Improves the ad loading time and user experience.

2. No Ad cluttering

Two ads cannot be displayed at the same instance, i.e. you cannot have two ads displayed on the screen at any given time.

3. Pause your content

When Fullscreen ad is displayed, pause the content beneath the ad.

4. Don’t switch action keys

Make the ad experience eventful and maintain consistency in the open & dismiss button. Designing apps that encourage accidental clicks may work against your favour and could result in getting blacklisted by advertisers. If possible indicate “ads” or “Sponsored” on top of the click button.

5. Rules for fullscreen ads

There are specific moments when these ads should be displayed: right after the app has launched, and/or after a party/session if the app is a game or similar. If a fullscreen ad is displayed at launch or after a party/session, you cannot call this format again before another five completed sessions/parties, to avoid user frustration.

Never display two fullscreen ads in a row.

6. Refresh rate

The refresh rate must not be inferior to 30s (do not refresh an ad when it’s been displayed less than 30s).

7. Keep the user in mind

A lot of our users are first time users, therefore unfamiliar with ads. Therefore it is important that ads are made distinct from the content of your app, and that it does not disturb the user experience.

8. Future updates

As KaiOS evolves, so will our guidelines and best practices. We have a section of our Roadmap entirely dedicated to the ad workflow and the way the SDK integrates the user experience. Expect continuous improvement of our guidelines and how we enforce them. Therefore it is paramount that as a publisher, you keep your app portfolio in line with the latest guidelines and best practices to avoid impacts on your ad revenues.

9. In-game advertising

When integrating our ads SDK into your gaming app, do not display any ads during the game play. Ads can only be displayed in menus or in-between sessions (interstitials). For interstitials please refer to point 5 of these guidelines.

10. app-ads.txt file

It is expected and compulsory that you implement and keep up to date our app-ads.txt file at the root domain of your publisher website. Failing to do so may result in payment being delayed until resolution.
⁕ To get up-to-date version of app-ads.txt file please visit https://adstxt.kaiads.com/.
⁕ For more information of what app-ads.txt is, please visit https://iabtechlab.com/blog/demystifying-app-ads-txt/.

Get started


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

2) For website integration, include the following script directly. Please note that by using and including this script you agree to be bound by and comply with the terms of our KaiAds SDK Agreement.

<script src="https://static.kaiads.com/ads-sdk/ads-sdk.v5.min.js"></script>
For KaiOS Apps, you can download KaiAds SDK V5, unzip and include kaiads.v5.min.js in your app. By downloading, including and using KaiAds SDK in your App, you agree to be bound by and comply with the terms of our KaiAds SDK Agreement.

3) For privileged or certified apps (not for web apps), include an extra dependency in manifest (manifest.webapp file).
   (For KaiOS 3.0 apps, dependency is not required in the manifest.webmanifest file.)

{
	"dependencies": {
		"ads-sdk": "1.5.0"
	}
}

To test in a KaiOS device, install the most recent version of Kai News app to make sure the required dependencies are downloaded.

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.
18 Internal error SDK internal error, please contact support.
19 Cannot load SDK Network condition or the SDK is too old. Please check SDK doc for latest SDK version
20 Internal error SDK internal error, please contact support.