Technical Requirements
All games submitted to QS Play must meet the technical requirements described on this page. These requirements help ensure that games load correctly, communicate with the platform, and provide a stable experience across supported browsers and devices.
QS Play games run directly in the browser inside an <iframe>. Communication between the game and the platform is handled through the QS Play SDK.
Before submitting your game, test the production build in an iframe-based environment and verify that all mandatory SDK lifecycle calls are triggered at the correct time.
Platform Architecture
Your game must:
- Be delivered as an HTML5 application.
- Run directly in a supported web browser without installation or additional software.
- Work correctly when embedded in an
<iframe>. - Use the QS Play SDK to communicate with the platform.
- Load all required game resources over HTTPS.
- Remain functional without direct access to the QS Play parent page.
Do not attempt to access or modify the parent page directly. Use the QS Play SDK for platform-related functionality such as lifecycle reporting, player data, cloud saves, and fullscreen controls.
Build Requirements
Submit a complete, production-ready build that includes all files required to launch and play the game.
The build must:
- Include a valid entry point for launching the game (typically
index.html). - Include all required scripts, styles, assets, fonts, audio files, and configuration files.
- Keep the initial load size below 50 MB.
- Keep the total build size below 200 MB.
- Use relative paths for all files included in the build.
- Load external resources only from secure HTTPS endpoints.
- Contain no references to local development environments such as
localhost. - Contain no missing, inaccessible, or broken resources.
- Run without requiring browser extensions, plugins, or additional downloads.
- Exclude source files, development-only tools, test data, and other files not required in production.
To improve loading performance, optimize images, audio, video, fonts, and JavaScript bundles before submission.
Large assets such as videos, voice-over files, and additional levels should be loaded only when needed rather than during the initial game load.
Browser and Device Compatibility
Your game must work reliably on every browser and device type selected during submission.
Depending on the platforms supported by the game, verify:
- Keyboard and mouse input on desktop devices.
- Touch input on mobile devices.
- Correct layout at different viewport sizes and aspect ratios.
- Correct behavior when the browser window is resized.
- Correct orientation handling on mobile devices.
- Readable and accessible interface elements at all supported resolutions.
- Fullscreen behavior, if fullscreen mode is available in the game.
If the game is designed only for specific device types, orientations, or input methods, clearly specify these limitations in the game submission form.
Do not block users based only on the browser user-agent string. Whenever possible, detect whether the required browser features are available and provide a clear message when the game cannot run on a device.
Performance and Stability
The game should load quickly and remain responsive throughout the player session.
Before submission, verify that the game:
- Starts without critical JavaScript errors.
- Does not freeze, crash, or become unresponsive during normal gameplay.
- Maintains stable performance on supported devices.
- Uses memory efficiently and releases resources that are no longer required.
- Avoids unnecessary network requests and repeated asset downloads.
- Handles delayed or failed network requests without leaving the player on an unresponsive screen.
- Pauses or reduces resource usage when gameplay is not active, where appropriate.
Long loading times, repeated runtime errors, severe frame-rate drops, excessive memory usage, or crashes may prevent the game from passing technical review.
QS Play SDK Integration
Every game must integrate the QS Play SDK, including games that do not use QS Play accounts or cloud saves.
The SDK is the communication layer between the game and QS Play. It allows the game to:
- Report loading and gameplay states.
- Receive the player's locale and device information.
- Request fullscreen mode.
- Access authenticated player data when account integration is implemented.
- Store and retrieve player progress when cloud saves are implemented.
- Show video ads and banners, if the game includes them — see Ads.
Detailed setup instructions and the complete API reference are available in the separate SDK section.
Mandatory SDK Lifecycle Calls
The following lifecycle calls are mandatory for every game:
game.loadingStart();
game.loadingStop();
game.gameplayStart();
game.gameplayStop();
QS Play uses these events to understand when the game is loading and when active gameplay begins or ends. They are also required for platform analytics.
Loading lifecycle
Call game.loadingStart() when the game starts loading the resources required before the player can start playing — normally once, when the game starts.
Call game.loadingStop() when those resources have loaded and the game is ready for the player's first action.
The loading state must reflect the actual game state. Do not call game.loadingStop() while the player is still waiting for required resources.
Do not use these calls to mark levels, rounds, restarts, or scene changes. The portal treats every additional game.loadingStart() as the game reloading itself and starts a new session, so a game that reports loading for every round inflates its session and play counts. Report those transitions with game.gameplayStart() and game.gameplayStop() instead.
Gameplay lifecycle
Call game.gameplayStart() when the player enters active gameplay.
Call game.gameplayStop() when active gameplay ends or is interrupted, for example when the player:
- Completes or exits a level.
- Returns to the main menu.
- Opens a state in which gameplay is no longer active.
- Pauses or leaves the game, where applicable.
The implementation must avoid overlapping or duplicate lifecycle states. Each started state should be stopped at the appropriate point in the game flow.
All gameplay segments of one visit belong to the same session, and the portal adds up their active time — see Sessions and gameplay segments. game.gameplayStop() does not end the session. Do not call it just because the browser tab lost focus: only the time the tab is visible is counted anyway.
For method signatures, initialization requirements, and implementation examples, refer to the Game module documentation.
Iframe Compatibility
Because the game runs inside an <iframe>, it must not depend on unrestricted access to the top-level browser window.
Your game must not:
- Redirect the parent page.
- Replace or modify QS Play page content.
- Depend on direct DOM access outside the game frame.
- Open unexpected pop-ups or new tabs.
- intercept browser or platform navigation.
If navigation outside the game is required, use the supported SDK functionality or another QS Play-approved integration method.
The game should also handle focus changes correctly. Keyboard input, audio, pause behavior, and pointer controls should not remain active unexpectedly when the game loses focus.
Network Requests and External Services
If the game communicates with external servers or third-party services:
- Use HTTPS for every request.
- Configure the service to support requests from the QS Play environment.
- Do not expose private keys, credentials, or server secrets in client-side code.
- Handle timeouts, unavailable services, and invalid responses gracefully.
- Keep essential gameplay functional whenever an optional external service is unavailable.
- Ensure that external dependencies remain maintained and accessible after publication.
The developer is responsible for the availability, security, and compatibility of external services used by the game.
Error Handling
The game must handle recoverable errors without forcing the player to reload the entire QS Play page.
Where relevant, provide:
- A clear loading error state.
- A retry option for failed network requests.
- A safe fallback when optional content cannot be loaded.
- A user-friendly explanation when the game cannot continue.
Error messages should explain what happened and what the player can do next. Do not expose stack traces, internal service details, credentials, or other sensitive technical information to players.
Security and Player Data
The game must follow secure web development practices.
The game must not:
- Include malicious, deceptive, or unauthorized scripts.
- Attempt to bypass browser or QS Play security controls.
- Store secrets or private credentials in the client build.
- Collect player data that is not required for the game experience.
- Transmit player data through insecure connections.
When player accounts or progress synchronization are supported, use the QS Play user and data modules instead of adding a separate platform login flow. See Accounts, Progress & Multiplayer for the corresponding requirements.
Any processing of player data must comply with applicable laws, platform policies, and the disclosures provided to players.
Audio, Focus, and Pause Behavior
The game should respond appropriately when the player changes tabs, minimizes the browser, leaves fullscreen mode, or moves focus outside the game.
Verify that:
- Audio does not continue unexpectedly when the game is paused or inactive.
- Keyboard and pointer input are released when the game loses focus.
- Gameplay does not continue in a way that unfairly affects the player while the game is inactive.
- The game can resume safely after focus is restored.
Fullscreen Support
If the game supports fullscreen mode, request it through the QS Play SDK rather than directly controlling the parent page.
Fullscreen mode must:
- Be initiated by a clear player action.
- Preserve the game's layout and aspect ratio.
- Keep controls and important interface elements visible.
- Exit cleanly without interrupting or resetting gameplay.
Refer to Fullscreen mode in the SDK documentation for the supported fullscreen integration. For the gameplay-side expectations, see Fullscreen Experience.
Technical Review Checklist
Before submitting the game, confirm that:
- The production build launches successfully.
- The game runs correctly inside an
<iframe>. - All required files are included in the build.
- Internal file paths work in the production environment.
- All external resources and requests use HTTPS.
- The QS Play SDK is initialized correctly.
-
game.loadingStart()andgame.loadingStop()are called once, around the game's initial loading — not for levels, rounds, or restarts. -
game.gameplayStart()andgame.gameplayStop()are called in pairs on every transition between active gameplay and menus, pauses, or screens between levels. - Lifecycle calls do not overlap or fire repeatedly by mistake.
- The game works on every declared device type and input method.
- The interface remains usable at supported resolutions and orientations.
- Fullscreen mode works correctly, if supported.
- The game does not produce critical console errors during normal gameplay.
- Failed network requests are handled gracefully.
- Audio, focus, pause, and resume behavior have been tested.
- No secrets, private credentials, or development-only files are included.