JavaScript SDK

Client-side helpers available to games, plugins, and portals running inside the UbuntuPlay ecosystem.

UbuntuAnalytics

The game telemetry API. Include the shared analytics script — events queue locally (offline-safe) and flush to the classroom server automatically; the server attributes them to an anonymous student pseudonym (names are never shared):

HTML

<script src="/analytics.js"></script>

JAVASCRIPT

UbuntuAnalytics.track('puzzle_complete', 'my-game-id', {
  puzzleId: 'level_1',
  stars: 3,
  timeSec: 42,
  subject: 'Maths'
});

Method	Description
`UbuntuAnalytics.track(eventType, gameId, metadata)`	Record a learning event (`quiz_correct`, `quiz_wrong`, `level_complete`, `puzzle_complete`, `game_start`, `game_end`). See the Building Games reference.
`UbuntuAnalytics.getRollingAccuracy(gameId)`	The student's rolling quiz accuracy for your game (0–100).
`UbuntuAnalytics.flush()`	Manually flush queued events to the server.

UbuntuAI

The offline AI helper, mirrored in Hub and Classroom frontends. Methods are lazy-loaded the first time they are called.

Method	Description
`UbuntuAI.chat(prompt)`	Send a prompt to the Gogo AI Bridge.
`UbuntuAI.translate(text, lang)`	Translate a string into a local language.
`UbuntuAI.batchTranslate(texts, lang)`	Translate an array of strings efficiently.
`UbuntuAI.generateLevel(gameId, difficulty, theme)`	Generate structured level JSON for a game.
`UbuntuAI.getRecommendedDifficulty(accuracy, subject)`	Recommend Easy/Medium/Hard based on accuracy.
`UbuntuAI.initVision(modelPath)`	Initialise MediaPipe Vision for hand tracking.
`UbuntuAI.startVoice()`	Start Web Speech recognition for voice commands.

i18n Helpers

The UbuntuI18n layer (loaded from /js/i18n.js) translates your UI into Bemba, Nyanja, Tonga, and Lozi. Mark up elements with data-i18n keys:

HTML

<span data-i18n="mygame.start">Start</span>
<span data-i18n="common.score">Score</span>

Programmatic access:

JAVASCRIPT

await UbuntuI18n.setLanguage('bem', 'Bemba'); // Switch to Bemba (AI-translates missing strings)
UbuntuI18n.t('mygame.start');                 // Returns translated string (falls back to English)
UbuntuI18n.refreshUI();                       // Re-translates all data-i18n elements

See the full Internationalisation guide for registering your game's strings, interpolation, caching, and the language-change event.

UP Shared Helpers (Portals)

Portal pages loaded from the Hub can use helpers in /shared.js:

JAVASCRIPT

const token = await UP.requireAuth('dev_token', '/hub/api/dev/me', '/dev/login');
const { ok, data } = await UP.api(token, '/hub/api/dev/me');
UP.clearToken('dev_token');

Helper	Description
`UP.requireAuth(tokenKey, whoamiUrl, loginUrl)`	Reads a stored token, validates it against `whoamiUrl`, redirects to login if invalid.
`UP.api(token, path, options)`	JSON helper that adds auth headers and parses responses.
`UP.clearToken(tokenKey)`	Removes the stored token. To fully sign out, also call `POST /api/auth/sign-out` to end the Better Auth session.