FOR GAME DEVELOPERS
Make a game for dingn
dingn games are web pages: HTML, CSS and JavaScript, made with any engine or framework that builds static files. They run in a secure frame on dingn.com and use the dingn game SDK for the player's language and name, saved progress and sign-in.
Download the starter gameOpen the playground
Get started in three steps
- Download the starter game and unzip it.
- Serve the folder on your computer:
Your server must allow other origins (CORS), because dingn runs games in a sandbox. With Vite, set server.cors to true.npx serve --cors -l 5173 dingn-starter - Open the playground, enter http://localhost:5173/ and press Load. Edit the files, then press Reload game to see your changes.
Add the SDK to your game
Import it from dingn. It works in any modern browser, with or without a bundler.
import { connect } from "https://dingn.com/sdk/v1/dingn-sdk.js";
const dingn = await connect();Using TypeScript? Download the type definitions: dingn-sdk.d.ts
Opened outside dingn, connect() still works: signed out, in the browser's language, with storage that lasts until the page closes.
SDK reference
| Call | What it does |
|---|---|
dingn.locale | The player's language, "en" or "zh-CN". Show your game in it. |
dingn.player | { signedIn, name, avatar }. Never an email address or account id. |
dingn.onPlayer(fn) | Called when the player signs in or out. Returns a function that stops listening. |
dingn.storage.get(key)
dingn.storage.set(key, value) | Saves JSON on this device only. Keys are up to 64 letters, digits, dots, dashes or underscores. Values are up to 16 KB. |
dingn.progress.load()
dingn.progress.save(data) | Saves JSON to the signed-in player's account, so it follows them to any device. Up to 16 KB. save() fails with the code "signed_out" when no one is signed in. |
dingn.rewards.unlock(id)
dingn.rewards.list() | Awards a badge listed in your game.json, such as "level-10". Each badge pays its dingn coins once per player, and dingn shows a "Badge earned" popup. unlock() fails with the code "signed_out" when no one is signed in. list() gives your badges and which ones the player has. |
dingn.rewards.spend(id)
dingn.rewards.shop() | Sells an upgrade listed in your game.json "shop", such as "power-1", for the player's dingn coins. dingn asks the player to confirm first. spend() fails with the code "cancelled", "not_enough_coins", "requires" or "signed_out". shop() gives your upgrades and which ones the player owns. |
dingn.rewards.earn(coins) | Pays the signed-in player 1 to 10 dingn coins for play itself, such as a failed level that still got somewhere. Each game can pay a player up to 500 coins a day this way, on top of its badges; past that, earn() pays 0. dingn shows the coins over the game. It fails with the code "signed_out" when no one is signed in. |
dingn.requestSignIn() | Sends the player to sign in. They come back to your game afterwards. |
dingn.navigate(path) | Leaves your game for a dingn page, such as "/" for the game list. |
dingn.ready() | Hides dingn's loading screen. Call it once your game can be played. |
Rules of the sandbox
- Your game runs in its own isolated origin. It cannot read dingn's pages, cookies or the player's account.
- localStorage, sessionStorage, IndexedDB and cookies are blocked. Use dingn.storage and dingn.progress instead.
- Load your own files with relative paths, such as img/hero.png. Each version of a game is served from its own folder.
- Full screen, sound, game controllers and pointer lock work. Links open in a new tab.
- Requests to other servers need CORS, because your game's origin is opaque.
game.json
Every game has a game.json next to its index.html. It names the game in English and Chinese:
{
"id": "mygame",
"version": "1.0.0",
"title": { "en": "My Game", "zh": "我的游戏" },
"description": { "en": "…", "zh": "…" },
"entry": "index.html",
"category": "casual",
"cover": "cover.png"
}The id is 2 to 31 lowercase letters and digits, starting with a letter. Every release needs a new version, because published versions never change.
category is casual, memory or puzzle: once approved, your game is listed on that category's page and in its menu. cover is an optional picture in your files for your game's card, 16:10, about 800×500. Without one, dingn draws a card from your title.
Publishing on dingn
- Zip your game's folder, with game.json and index.html at the top. For a game with a build step, zip the built files.
- Upload the zip on My games. It becomes a preview that you can try and share right away.
- dingn reviews the preview and makes it live. For every update, raise version in game.json and upload again.
Uploading from GitHub or a script
Create an upload key on My games, then send the zip with it. The upload is reviewed like any other. In a GitHub Action, keep the key as a secret named DINGN_UPLOAD_KEY:
curl --fail-with-body -X POST https://dingn.com/api/developer/games/upload \
-H "Authorization: Bearer $DINGN_UPLOAD_KEY" \
-H "Content-Type: application/zip" \
--data-binary @my-game-1.0.0.zipAnyone can sign up on My games by accepting the developer agreement. Read the developer agreement