Skip to content

defold-banner

PokiSDK - Defold

Made by Defold 

Introduction & Features

This is a Poki Plugin made for the Defold Engine.

The Lua API here corresponds to the original Javascript API:

Lua vs Javascript
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)end) -- in JS it's PokiSDK.commercialBreak()
poki_sdk.rewarded_break(function(self, success)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')

1. Install the SDK

To use 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 ZIP archive of the release and add it to the project dependencies.

extension-add

Select Project->Fetch Libraries once you have added the version to game.project to download the version and make it available in your project.


2. Implement the gameplay events

Use the  ðŸŽ® gameplayStart()  event to describe when users are playing your game (e.g. on first user interaction and unpause).

Use the  â˜  gameplayStop()  event to describe when users aren’t playing your game (e.g. level finish, game over, pause, 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


3. Implement commercialBreak

Commercial breaks are used to display video ads and should be triggered on natural breaks in your game. Throughout the rest of your game, we recommend you implement the  ðŸŽž commercialBreak()  before every  ðŸŽ® gameplayStart() , i.e. whenever the user has shown an intent to continue playing.

-- gameplay stops
poki_sdk.commercial_break(function(self)end)

Important information about commercialBreaks

Not every single  ðŸŽž commercialBreak()  will trigger an ad. Poki’s system will determine when a user is ready for another ad, so feel free to signal as many commercial break opportunities as possible.


4. Implement rewardedBreak

Rewarded breaks allow for a user to choose to watch a rewarded video ad in exchange for a certain benefit in the game (e.g. more coins, etc.). When using  ðŸŽ¬ rewardedBreak() , please make it clear to the player beforehand that they’re about to watch an ad.

-- gameplay stops
poki_sdk.rewarded_break(function(self, success)end)

About the rewardedBreak timer

 ðŸŽ¬ rewardedBreak()  affects the timing of  ðŸŽž commercialBreak()  - When a user interacts with a rewarded break, our system’s ad timer is reset to ensure the user does not immediately see another ad.


Final Steps

Disable sound and input during ads

Make sure that audio and keyboard input are disabled during commercialBreaks, so that the game doesn’t interfere with the ad:

-- gameplay stops
-- fire your mute audio function
poki_sdk.commercial_break(function(self)
  -- fire your unmute audio function
  -- fire your function to continue to game
end)


Upload and test your game in Poki for Developers

Congrats, you’ve successfully 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. Feel free to contact us via Discord or developersupport@poki.com if you’re stuck.


Error handling

Do not collect Lua errors manually using sys.set_error_handler(). The SDK collects Lua errors and the engine’s errors and warnings automatically.


Shareable URLs & URL manipulation

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.com url params

As you might have noticed in the previous topic, the poki_sdk.shareable_url() creates a url with parameters that are prefixed with gd. We have created a simple helper function that will easily allow you to read the params.

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


Example project and Source code

Refer to the example project to see a complete exameple of how the intergation works.

The source code is available on GitHub