Best Practices

Guidelines to make your UbuntuPlay games and plugins secure, fast, accessible, and resilient in real classrooms with limited connectivity.

Offline-First Design

• No external CDNs: All required JS, CSS, fonts, and images must be inside the ZIP.
• Self-contain assets: Avoid hot-linked images or Google Fonts. Use self-hosted fonts or system fallbacks.
• Graceful degradation: If UbuntuAnalytics or the AI helpers are not present, the game should still function.
• LocalStorage caution: Marketplace demo previews run in a sandboxed iframe where storage may be limited; keep progress recoverable from tracked events where possible.

Performance

• Keep the total ZIP under 10 MB when possible; games are cached on low-end devices.
• Optimise images (WebP or compressed PNG) and audio (compressed OGG/MP3).
• Use requestAnimationFrame for animation loops and throttle heavy computation.
• Lazy-load AI or vision bundles only when needed.

Security

• Never include secrets in game code. Assume the source is readable.
• Validate any metadata you post via UbuntuAnalytics.track; don't trust client-generated fields blindly on the server.
• For plugins, only use allowed modules. fs, child_process, and process.env are blocked by static analysis.
• Sanitise inputs and escape output in plugin code to avoid injection.

Localisation

• Mark all user-facing strings with data-i18n attributes and register English defaults — see the Internationalisation guide.
• Keep strings short and context-agnostic; use keys like game.hint.tap.
• Provide a meaningful English fallback if a translation is missing.
• Test in at least one local language (Bemba, Nyanja, Tonga, or Lozi).

Classroom UX

• Optimize for touch and small screens (phones and low-cost tablets).
• Use large tap targets and high-contrast visuals.
• Provide clear feedback for correct/wrong answers.
• Avoid timers that punish slow readers; prefer progress-based challenges.
• Respect the 2-minute demo cap in trial environments; keep onboarding fast.

Privacy by Design

• Do not collect names, phone numbers, or photos of students.
• Games never receive student identity; the server attributes telemetry to an anonymous pseudonym derived from the session token.
• Report aggregate events; avoid sending individually identifiable detail.

Troubleshooting Checklist

• Does the game run when opened directly as a local file?
• Does it record telemetry with a mock UbuntuAnalytics object?
• Does the ZIP contain index.html at the root?
• Does the manifest sign without validation errors?
• Does the marketplace preview look correct on a 360 px-wide screen?