PokiSDK: Defold

Integration outline

1. Set up the SDK for Defold. Add the official Poki SDK extension to your Defold project dependencies. Defold is an official Poki partner engine.
2. Signal loading: fire gameLoadingFinished() when your game is done loading, so conversion to play is measured correctly.
3. Gameplay events: fire gameplayStart() on the player's first input and every return to gameplay; gameplayStop() on every interruption (pause, level end, game over, menu).
4. Ads: implement commercialBreak() at natural breaks before returning to gameplay, and rewardedBreak() for opt-in rewards. Mute audio and disable input during ads.
5. Test with the Poki Inspector to verify the event flow.

Event rules and the full order-of-events reference live in the SDK overview.

The Defold integration is built and maintained by Defold, an official Poki partner engine. The Lua API mirrors the original JavaScript API:

poki_sdk.gameplay_start() -- in JS it's PokiSDK.gameplayStart()
poki_sdk.gameplay_stop() -- in JS it's PokiSDK.gameplayStop()
poki_sdk.commercial_break(function(self, status)end) -- in JS it's PokiSDK.commercialBreak()
poki_sdk.rewarded_break(function(self, status)end) -- in JS it's PokiSDK.rewardedBreak()
poki_sdk.happy_time(value) -- in JS it's PokiSDK.happyTime(value), where value is between 0 and 1
poki_sdk.shareable_url(params, callback) -- in JS it's PokiSDK.shareableURL({}).then(url => {})
local value = poki_sdk.get_url_param(key) -- in JS it's PokiSDK.getURLParam('id')

Use the Defold Poki integration

Below is a step-by-step guide to implement the Poki SDK and get your game ready to launch. As part of the partnership between Poki and the Defold Foundation, we've also released the ability to bundle Defold games directly to Poki. This direct integration, which includes an SDK template, makes creating, testing, and iterating on your Poki game much smoother. For more on the integration and how to use it, see this article.

Install the SDK

To use the Poki SDK in your Defold project, add a version of the Poki SDK extension to your game.project dependencies from the list of available releases. Find the version you want, copy the URL to the ZIP archive of that release, and add it to the project dependencies. Then select Project -> Fetch Libraries once you've added the version to game.project to download it and make it available in your project.

Gameplay events

Use gameplay_start() to mark when players are playing your game (for example on first interaction and unpause). Use gameplay_stop() to mark when they aren't (for example level finish, game over, pause, or quit to menu).

-- player interacts with the game
poki_sdk.gameplay_start()
-- player is playing
-- player loses round
poki_sdk.gameplay_stop()
-- game over screen pops up

commercialBreak

Commercial breaks show video ads and should be triggered at natural breaks in your game. Throughout the game we recommend calling commercial_break() before every gameplay_start(), that is, whenever the player has shown intent to continue playing.

poki_sdk.commercial_break(function(self, status)
	if status == poki_sdk.COMMERCIAL_BREAK_START then
		-- commercial break started, pause your game
	elseif status == poki_sdk.COMMERCIAL_BREAK_SUCCESS then
		-- continue game
	end
end)

rewardedBreak

Rewarded breaks let a player choose to watch a rewarded video ad in exchange for a benefit in the game (more coins, for example). When using rewarded_break(), make it clear to the player beforehand that they're about to watch an ad.

-- gameplay stops
poki_sdk.rewarded_break(function(self, status)
	if status == poki_sdk.REWARDED_BREAK_ERROR then
		-- an error happened, don't give the reward and continue the game
	elseif status == poki_sdk.REWARDED_BREAK_START then
		-- rewarded break started, pause your game
	elseif status == poki_sdk.REWARDED_BREAK_SUCCESS then
		-- rewarded break finished, give the reward and continue the game
	end
end)

Final steps

Disable sound and input during ads

Make sure your game is paused and keyboard input is disabled during commercial breaks and rewarded breaks, so the game doesn't interfere with the ad. Either:

-- gameplay stops
poki_sdk.commercial_break(function(self, status)
	if status == poki_sdk.COMMERCIAL_BREAK_SUCCESS then
		-- fire your function to continue the game
	end
end)

Or:

poki_sdk.commercial_break(function(self, status)
	if status == poki_sdk.COMMERCIAL_BREAK_START then
		-- gameplay stops
	elseif status == poki_sdk.COMMERCIAL_BREAK_SUCCESS then
		-- fire your function to continue the game
	end
end)

Upload and test your game in Poki for Developers

Congratulations, you've implemented the PokiSDK. Now upload your game to the Poki Inspector and test it there. When you're happy with the implementation, send us a review request and we'll play the game. If you get stuck, reach out via Discord or developersupport@poki.com.

Error handling

Don't collect Lua errors manually using sys.set_error_handler(). The SDK collects Lua errors and the engine's errors and warnings automatically.

Shareable URLs

You can create a shareable URL with the following function:

local params = {
	id = "myid",
	type = "mytype",
	score = 28
	-- ... any other param
}
poki_sdk.shareable_url(params, function(self, url)
	print(url)
	-- if run on e.g. https://poki.com/en/g/my-awesome-game it will return:
	-- https://poki.com/en/g/my-awesome-game?gdid=myid&gdtype=mytype&score=28
end)
-- read further to see how to fetch these params easily from within your game

Reading Poki URL params

As you may have noticed above, poki_sdk.shareable_url() creates a URL with parameters prefixed with gd. This helper function reads them back easily:

poki_sdk.get_url_param("<param name>")

-- example
local id = poki_sdk.get_url_param("id")
-- this will return either the gdid param set on poki.com or the id param on the current url

Moving the Poki Pill on mobile

On mobile you can reposition the Poki Pill slightly to better fit your game UI using move_pill(topPercent, topPx).

• topPercent is a number between 0 and 50 and sets the pill's vertical position as a percentage from the top of the game area.
• topPx is an additional pixel offset on top of topPercent (positive moves it down, negative moves it up).

You can't move the pill lower than 50% of the game area (the game bar at the bottom isn't included in this area). The default position is move_pill(0, 24).

Poki Pill size: 46px × 62px on screens narrower than 1211px, and 92px × 64px on screens 1211px wide or wider.

-- Move the pill 100 pixels above the center of the game.
poki_sdk.move_pill(50, -100)

Example project and source code

See the example project for a complete look at how the integration works. The source code is available on GitHub.