Cocos
Cocos
The Cocos package is a promise-based TypeScript wrapper over window.ZokoGames.SDK for Cocos Creator 3.x. Names match the JavaScript SDK one to one (ZokoSDK.game.gameplayStart()). Outside a browser (the Creator editor, native builds), or when the SDK script cannot be loaded, a built-in simulator answers so the game keeps running.
Install#
- Copy the
zokogamesfolder (ZokoSDK.ts,ZokoTypes.ts,ZokoSimulator.ts) into your project'sassets/folder. - Paste the contents of
build-templates/zokogames-sdk-snippet.htmlinto the<head>of your build template (build-templates/web-desktop/index.ejsorbuild-templates/web-mobile/index.ejs), before the engine starts. It is one script tag forhttps://sdk.zokogames.com/zokogames-sdk-v1.js. If the tag is missing, the module loads the script itself. - Import the module and call
await ZokoSDK.init()once at startup.
import { ZokoSDK } from "./zokogames/ZokoSDK";
await ZokoSDK.init();Simulator#
ZokoSDK.isSimulated is true when the simulator is answering, and ZokoSDK.isSupportedPlatform is true only in a browser build. To tune the simulator, call ZokoSDK.configureSimulator(options) before init(). Options: disabled, accountAvailable, loggedIn, username, userId, friendCount, adBehaviour ("fill", "no_fill" or "error"), adDurationMs, adblock, muteAudio, disableChat, instantMultiplayer, verbose.
Mapping#
The module re-exports the global SDK with types. Names are identical to JavaScript; calls return promises.
| JavaScript | Cocos (TypeScript) |
|---|---|
SDK.init() |
await ZokoSDK.init() |
SDK.environment |
ZokoSDK.environment |
SDK.ad.requestAd(...) |
ZokoSDK.ad.requestAd(...) |
SDK.banner.requestBanner(...) |
ZokoSDK.banner.requestBanner(...) (needs a DOM container) or ZokoSDK.banner.requestBannerForNode(id, node, size?) |
SDK.game.*, SDK.user.*, SDK.data.* |
The same names |
ZokoSDK.isAvailable is false when the SDK is disabled in the embed. Errors are plain { code, message } objects.
Examples#
Ads#
import { _decorator, Component, director, game } from "cc";
import { ZokoSDK } from "./ZokoSDK";
const { ccclass } = _decorator;
@ccclass("AdButton")
export class AdButton extends Component {
async onRewardClicked() {
let earned = false;
await ZokoSDK.ad.requestAd("rewarded", {
adStarted: () => game.pause(),
adFinished: () => { earned = true; },
adError: () => { earned = false; },
});
game.resume();
if (earned) this.grantReward();
}
grantReward() { /* ... */ }
}Banners#
Banners are drawn in the page, not in the canvas. Add a UI node with a UITransform where the banner should sit and let the module place a container over it:
await ZokoSDK.banner.requestBannerForNode("menu-banner", this.bannerSlot); // largest size that fits
await ZokoSDK.banner.requestBannerForNode("menu-banner", this.bannerSlot, "300x250"); // a static size
await ZokoSDK.banner.clearBanner("menu-banner");ZokoSDK.banner.rectOfNode(node) returns the node's normalised rectangle if you want to place the container yourself and call requestBanner({ id, width, height }).
Game, User, Data#
await ZokoSDK.game.gameplayStart();
const user = await ZokoSDK.user.getUser();
ZokoSDK.data.setItem("level", "4");Tips#
- Use the build option Inline all SpriteFrames off, and split resources into bundles loaded after
gameplayStart. - Remote bundles count towards the initial download only when they are fetched before the first frame.