Skip to main content

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:

index.html
<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.