KaiAds SDK

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>

3) For Privileged or Certified Apps (not for Web Apps) in KaiOS 2.5, include an extra dependency in manifest (manifest.webapp file).

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

{
	"b2g_features": {
		"dependencies": {
			"ads-sdk": "1.5.8"
		}
	}
}

<link rel="manifest" href="/manifest.webmanifest">

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 // Timeout

Usage // Fullscreen Ad

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

Usage // Responsive Ad

<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',
		})
	}
})
	

Examples // Pre-loading

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

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

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