PokiSDK: Unity

Integration outline

1. Set up the SDK for Unity. Download the Poki Unity template and C# class for your Unity version (5.6+, 2020, 2022, and Unity 6 builds are provided) instead of implementing the JavaScript SDK directly.
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.

Set up the SDK

To simplify integration in Unity WebGL games, we provide a template and a C# class you can use instead of implementing the JavaScript SDK directly. Start by downloading the files for your Unity version:

• Unity 5.6+
• Unity 2020
• Unity 2022
• Unity 6

Copy the WebGLTemplates directory from the downloaded zip into your Unity game's Assets directory, then select the template in Player Settings > WebGL > Resolution and Presentation.

Copy the PokiUnitySDK.cs file and the Plugins folder into your project's Assets folder so you can reach the PokiSDK from your code. Then initialize the SDK as early as possible in your application by calling PokiUnitySDK.Instance.init();.

Gameplay events

Use gameplayStart() to mark when players are playing your game (for example level start and unpause). Use gameplayStop() to mark when they aren't (for example level finish, game over, pause, or quit to menu).

// first level loads, player clicks anywhere
PokiUnitySDK.Instance.gameplayStart();
// player is playing
// player loses round
PokiUnitySDK.Instance.gameplayStop();
// 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 commercialBreak() before every gameplayStart(), that is, whenever the player has shown intent to continue playing.

PokiUnitySDK.Instance.commercialBreakCallBack = <function>;
PokiUnitySDK.Instance.commercialBreak();
// <function> is of type Function and will be triggered when the commercial break is finished.

Example:

public void commercialBreakComplete(){
    Debug.Log("Commercial break finished");
}

//Set the complete callback
PokiUnitySDK.Instance.commercialBreakCallBack = commercialBreakComplete;
PokiUnitySDK.Instance.commercialBreak();

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 rewardedBreak(), make it clear to the player beforehand that they're about to watch an ad.

PokiUnitySDK.Instance.rewardedBreakCallBack = <function(withReward)>;
PokiUnitySDK.Instance.rewardedBreak();
// <function> is of type Function and will be triggered when the rewarded break is finished.

Example:

public void rewardedBreakComplete(bool withReward){
	Debug.Log("Rewarded break finished, should i get a reward:"+withReward.ToString());
}

// set the complete callback
PokiUnitySDK.Instance.rewardedBreakCallBack = rewardedBreakComplete;
PokiUnitySDK.Instance.rewardedBreak();

Optimizing your Unity build

Settings, tips, and guides for optimizing your Unity build for the web. If you know of more ways to reduce file size or improve performance, let us know.

Build optimization

Publishing settings

Make sure these settings are in place before exporting:

• Set Enable Exceptions to Explicitly Thrown Exceptions Only
• Set the compression method to Disabled
• Toggle Name Files As Hashes to ON
• Read more about these settings in Unity's documentation

General

• Disable any built-in Unity modules your game isn't using (VR, XR, Terrain, and so on)
• Disable third-party plug-ins
• Toggle Strip Engine Code to ON
• Set Managed Stripping Level to high (if it breaks your game, set it to medium)
• Set Publishing Settings > Enable Exceptions to None.
• Enable Publishing Settings > Data Caching. This lets asset files be stored in the browser's local cache so they don't need to be re-downloaded.
• If you're using the Universal Render Pipeline, disable post processing, as it adds size to your build.

Images and sounds

• Set audio clips to Mono
• Remove redundant audio files. For example, .m4a files usually aren't needed, since most browsers accept both .mp3 and .m4a
• Compress your Asset Bundles using LZ4, not LZMA. You can also leave them uncompressed and the Poki server will compress them for you
• Use nested particle systems as sparingly as possible
• Use .png only for transparent elements; otherwise .jpg generally gives smaller builds
• Set sprites without mip maps, filter mode to point, and anisoLevel to 1. For sprites with gradients, try Bilinear or Trilinear
• Create an atlas for your UI sprites to reduce draw calls and run smoother on the web

Textures

For each texture:

• Set Format to Automatic (default)
• Set Compression to Low Quality, or High Quality if some assets look too rough
• Set Use Crunch Compression to 92, or 60 if quality is too low
• If available, set Format to RGB Crunched DXT1|BC1
• We strongly recommend compressing all textures for a smaller file size

You can also see our colleague Julien Mourer's video on reducing asset size, Unity's guide to optimizing your web build, and these deeper dives on texture compression: an introduction to texture compression and what is crunch compression.

Runtime and performance optimization

• Pool your game objects, particle systems, and other entities so they're created once and not destroyed
• Preload objects that aren't used right away, set them to inactive, and add them to the object pool for later
• Spread CPU-intensive actions over multiple frames. For example, build a level across a span of frames rather than all at once
• Don't overuse raycasts. Where possible, raycast once every 10 frames

Other helpful steps

• Download the Build Report Inspector for Unity to help improve build times and sizes
• Make a build, open the console, click the top right, and select Open Editor Log to see the final size of all assets, ordered largest to smallest
• Set API Compatibility Level to .NET 2.0 subset, which is known to produce smaller builds

Final steps

Disable sound and input during ads

Make sure audio and keyboard input are disabled during commercial breaks so the game doesn't interfere with the ad:

	public void triggerRestartGame() {
		// fire your mute audio function
		// fire your disable keyboard input function
		PokiUnitySDK.Instance.commercialBreakCallBack = restartGame;
		PokiUnitySDK.Instance.commercialBreak();
	}

	public void restartGame(){
		// reset game here
		// fire your unmute audio function
		// fire your enable keyboard input function
	}

Shareable URLs and URL manipulation

You can create and use a shareable URL with the following. Use triggerShareableURL to generate it, receive it in shareableURLResolved, then use triggerGetURLParam to read parameters back from the URL.

PokiUnitySDK.Instance.shareableURLResolvedCallback = shareableURLResolved;
PokiUnitySDK.Instance.shareableURLRejectedCallback = shareableURLRejected;

public class urlParams : ScriptableObject {
    public string param1 = "";
    public string param2 = "";
    public string test3 = "";
}

public void triggerShareableURL(){
    urlParams data = ScriptableObject.CreateInstance<urlParams>();
    data.param1 = "test1";
    data.param2 = "test2";
    data.test3 = "test3";
    PokiUnitySDK.Instance.shareableURL(data);
}

public void shareableURLResolved(string url){
    Debug.Log("shareableURL:"+url);
    debugText.text = "shareableURL:"+url;
}

public void shareableURLRejected(){
    Debug.Log("shareableURL rejected");
    debugText.text = "shareableURL rejected";
}

public void triggerGetURLParam(){
    string identifier = GameObject.Find("displayAd_inputIdentifier").GetComponent<InputField>().text;
    string param = PokiUnitySDK.Instance.getURLParam(identifier);
    Debug.Log("URL param "+identifier+"="+param);
    debugText.text = "URL param "+identifier+"="+param;
}

Moving the Poki Pill on mobile

On mobile you can reposition the Poki Pill slightly to better fit your game UI using movePill(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 movePill(0, 24).

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

	public void movePillAwayFromUI() {
		// Move the pill 100 pixels above the center of the game.
		PokiUnitySDK.Instance.movePill(50, -100);
	}

Images in the Unity loader

To add screenshots of your game to the Unity loader on Poki, add up to 4 images to the screenshots folder in your Unity project and they'll show up in the loader automatically. You can add 2 sizes per image. To set up your thumbnail, contact us via Discord and we'll handle that part of the screen for you.

Additional helpful methods

Detecting if the SDK is initialized

	PokiUnitySDK.Instance.isInitialized() // returns boolean

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.