SDK
The QSPlay SDK is a JavaScript library that an HTML5 game includes to communicate with the
play.quartsoft.com portal, which embeds the game via an <iframe>.
Through the SDK, the game learns the player's locale and device type, reports loading and gameplay
progress, requests fullscreen mode, receives the signed-in player's data, saves the player's
progress in the cloud, and shows video ads and banners.
The game gets a single global object — window.QSPlaySDK — with five modules:
QSPlaySDK.game— the game's lifecycle inside the portal: loading, active gameplay, fullscreen, environment settings, the game link, invite links.QSPlaySDK.user— data about the current portal player: profile, a token for the game's backend, a subscription to sign-in/sign-out.QSPlaySDK.data— saving the player's progress: a simple key-value store that works the same way for a guest and for a signed-in user.QSPlaySDK.ad— full-screen video ads: midgame interstitials and rewarded ads.QSPlaySDK.banner— in-game banner ads, rendered inside the game's own document.
Which methods are mandatory and how to use them is described in the Requirements section — this page and the following ones only cover how the SDK itself is connected and how it works technically.
Including the SDK
Add a <script> tag to the <head> of your game's index.html — before the tag that loads the
game's own code, so that window.QSPlaySDK already exists by the time the game accesses it:
<head>
<!-- Include the SDK before the game code -->
<script src="https://sdk.quartsoft.com/v1/sdk.js"></script>
</head>
Once the script has loaded, the global window.QSPlaySDK object is available right away and ready
to use — there is nothing to initialize.
Access the SDK through the global QSPlaySDK variable — exactly as shown in the examples on this
page — regardless of whether the game is built with a bundler (Webpack, Vite, etc.) or not.
Quick example
await QSPlaySDK.game.loadingStart();
await loadGameAssets(); // your asset loading code
await QSPlaySDK.game.loadingStop();
const user = await QSPlaySDK.user.getUser();
if (user) {
console.log(`Hello, ${user.name}!`);
}
All QSPlaySDK.* methods are asynchronous and return a Promise — messages between the game and
the portal always go through postMessage, even when the answer is essentially instant.
Where it works
The SDK detects the environment it is running in and picks the appropriate mode:
- The game is embedded in an
<iframe>on play.quartsoft.com — real message exchange with the portal. - The game is opened in a separate tab (the typical case during local development) — mock mode is enabled automatically: all methods resolve locally with test data, without contacting the portal. See the Testing page for details.
SDK version
QSPlaySDK.version; // for example, "1.4.0"
sdk.js and the portal's server side are two halves of one protocol and are always released
together, under a single version number. The CDN path (v1/... in the example above) is the
protocol version, not a build number: it changes only on incompatible protocol changes, so a game
that is already embedded won't silently break after the next portal update.
Basic integration example
A typical sequence of calls when the game starts:
async function bootstrap() {
await QSPlaySDK.game.loadingStart();
await Promise.all([preloadAssets(), preloadAudio()]);
await QSPlaySDK.game.loadingStop();
const user = await QSPlaySDK.user.getUser();
if (user) {
console.log(`Now playing: ${user.name}`);
}
QSPlaySDK.user.addAuthListener(({ user }) => {
// the player signed in or out without leaving the game
});
}
bootstrap();
// every time the player starts playing: a new round, a level, or a resume after a pause
function onLevelStart() {
QSPlaySDK.game.gameplayStart();
}
// every time they stop: the round ended, they went to the menu, or paused
function onPause() {
QSPlaySDK.game.gameplayStop();
}
For a detailed description of each method, see the Game module, User module, Data module, Video ads module, and Banner module pages.