Skip to main content

QSPlaySDK.game

Methods for managing the game's lifecycle inside the portal: environment settings, active gameplay, loading, game context, player level, fullscreen mode, the game link, and inviting other players.

Mandatory in every game (see Requirements): game.loadingStart(), game.loadingStop(), game.gameplayStart(), game.gameplayStop(). They don't control any visual element of the portal — the portal uses them to count game launches and activity for internal analytics, so call them in any case, even if nothing visually changes at that moment. The other methods of the module are optional and can be adopted as needed.

Environment settings​

The game.getConfig() method returns the settings of the environment the game is currently running in.

const config = await QSPlaySDK.game.getConfig();
// { locale: "en", deviceType: "desktop" }

Returns:

interface GameConfig {
locale: string;
deviceType: "desktop" | "mobile";
}
FieldDescription
localeThe portal's current interface language, for example "en" or "ru".
deviceTypeThe device type, determined on the server from the User-Agent.

Game loading​

Call game.loadingStart() at the very beginning of loading the game's assets — as early as possible, right after the SDK becomes available. Call game.loadingStop() when asset loading is complete and the game is ready to show its first frame.

await QSPlaySDK.game.loadingStart();

await preloadAssets();

await QSPlaySDK.game.loadingStop();

When game.loadingStop() is called, the SDK attaches the game's loading sizes by itself (how many bytes were downloaded and how much the game weighs unpacked) — they are measured by the Resource Timing API inside your iframe, so there is nothing to pass manually. The browser counts resources from another domain only if their server sends the Timing-Allow-Origin header; the rest are not included, and the resulting size will be understated — so it's best to host assets on the same domain or add this header.

This pair doesn't control any visual element of the portal — the portal needs it for analytics: it is used to count game launches and activity. Call both methods in any case, even if nothing changes on screen at that moment.

Report the game's real loading, normally once — when the game starts. Don't call loadingStart() / loadingStop() for a new level, a round, a restart or a scene change: the portal treats every further loadingStart() as the game reloading itself, ends the current session and starts a new one. A game that wraps every round in a loading pair ends up with one session per round, and its play count grows with the number of rounds instead of the number of times players launched the game. Mark rounds with gameplayStart() / gameplayStop() instead.

Active gameplay​

game.gameplayStart() tells the portal that the player has started active play — after the main menu, a tutorial, a pause, or a death screen. game.gameplayStop() tells it that they have left it: opened a menu, paused, or lost.

await QSPlaySDK.game.gameplayStart();
// ...
await QSPlaySDK.game.gameplayStop();

Call both methods on every transition between active play and everything else (menus, pauses, screens between levels) — this is the only signal the portal uses to tell an actual gameplay session apart from time spent in the interface.

Sessions and gameplay segments​

The portal opens a session when the player clicks Play, and the game's first game.loadingStart() joins it. The session lasts for the whole visit and ends when the player leaves or reloads the page. Every gameplayStart() / gameplayStop() pair inside it is one gameplay segment — a round, a level, the time between two pauses — and the portal adds up the active time of all segments. So the number of rounds a player plays doesn't change the number of sessions, only how much active time the session has.

  • Call the methods in pairs: gameplayStop() before the next gameplayStart(), and never the same one twice in a row.
  • Call gameplayStop() when active play ends — a level is completed or lost, the player opens a menu or pauses. Don't call it when the browser tab loses focus: only the time the tab is visible is counted anyway.
  • gameplayStop() doesn't end the session, and there is nothing to call when the player leaves the game — the portal closes the session itself.

A game with rounds calls the lifecycle methods like this:

// once, at startup
await QSPlaySDK.game.loadingStart();
await preloadAssets();
await QSPlaySDK.game.loadingStop();

// every round
await QSPlaySDK.game.gameplayStart(); // the round begins
// ... the player plays ...
await QSPlaySDK.game.gameplayStop(); // won, lost, or quit to the menu

Game context​

game.setGameContext(context) passes the current state of the game (level, score, scene, etc.), which is attached to a player's report about the game ("Report a problem") or to feedback, if they submit one. It helps reproduce the problem when handling the report.

await QSPlaySDK.game.setGameContext({ level: 4, score: 1200 });

Accepts context: Record<string, unknown> — an arbitrary object, entirely up to the game. Update it as the game progresses (for example, when the level changes), so that by the time of a report or feedback it holds the current state.

game.clearGameContext() resets the context — for example, when a level is restarted or the player returns to the main menu.

await QSPlaySDK.game.clearGameContext();

Player level​

game.reportPlayerLevel(level) reports the player's level in your game — a single number that the portal shows in the player's profile as their level in this game.

QSPlaySDK.game.reportPlayerLevel(42);

What the number means is up to your game. If it has levels, report the player's level. If it doesn't, report another number that grows as the player progresses — for example, how many rounds they have played. The portal doesn't interpret it, it shows it as the level either way.

Report the player's overall progress, not their current position: the highest level reached, not the level being played right now, so that a player who goes back to replay level 1 doesn't see their level drop. The portal shows whatever you reported last.

The value must be an integer from 0 to 4294967295. Anything else (a negative number, a fraction, NaN, a string) is ignored with a warning in the browser console.

Call it whenever the level changes, and once after loading the player's save, so a returning player's profile is up to date from the first minute.

The method returns nothing and never throws, so there is no need to await it or wrap it in try/catch. It is safe to call often: the SDK waits 5 seconds, sends only the last value reported in that time, skips a value that hasn't changed since the last one it sent, and sends what is still pending when the player leaves the page.

A guest has no profile to show a level in, so nothing is stored for them. If your game lets players sign in mid-session, report the level again once they do — listen with the authentication listener. The SDK doesn't skip that repeated value as "unchanged" after a sign-in.

This is separate from the Data Module: the portal never reads what you save there, only the level you report here.

Fullscreen mode​

game.requestFullscreen() asks the host to expand the game to full screen, and game.exitFullscreen() exits fullscreen mode.

await QSPlaySDK.game.requestFullscreen();
// ...
await QSPlaySDK.game.exitFullscreen();

Fullscreen listener​

game.addFullscreenListener(callback) subscribes to fullscreen changes made on the host's side: for example, the player left fullscreen via Esc or a system gesture rather than via exitFullscreen().

const unsubscribe = QSPlaySDK.game.addFullscreenListener(({ isFullscreen }) => {
// update the game UI
});

// later, if the subscription is no longer needed:
unsubscribe();

Event payload (portal → game):

interface FullscreenChangedEventPayload {
isFullscreen: boolean;
}

Locale change​

game.addLocaleListener(callback) subscribes to portal language changes without reloading the game.

const unsubscribe = QSPlaySDK.game.addLocaleListener(({ locale }) => {
// switch the language inside the game
});

Event payload (portal → game):

interface LocaleChangedEventPayload {
locale: string;
}

game.shareLink() returns a link to the game for a "share" button inside the game, with the portal's current UTM tags.

const url = await QSPlaySDK.game.shareLink();

Returns a string.

They let one player invite another to their room or match via a link to the game. The SDK doesn't handle networking between players (rooms, matchmaking, state synchronization) — that remains on the side of the game's multiplayer server; the SDK only passes the related parameters once, from the person who created the link to the person who followed it. For what a multiplayer game must implement on its side, see Requirements · Multiplayer Games.

game.inviteLink(params) builds a link to the game that carries params — for example, the id of a room the game created on its multiplayer server. A player who opens this link will receive the same params through getInviteParams().

const url = await QSPlaySDK.game.inviteLink({ roomId: "abc123" });
// "https://play.quartsoft.com/en/games/brain-blast/?invite=eyJyb29tSWQiOiJhYmMxMjMifQ"

Accepts params: Record<string, DataValue> — the same JSON-compatible value type as in the data module, entirely up to the game: the SDK doesn't look inside and doesn't validate it in any way. Keep it small — it is encoded directly into the URL (base64url over JSON), so this is not the place for the full game state, but rather a room id and, perhaps, a seed.

Returns a string — the full link to the game's page on the portal (not to the game's iframe), ready to be handed to a player in any way (an "Invite" button, copying to the clipboard, your own chat).

Getting invite parameters​

game.getInviteParams() returns the params with which the current visit was opened, if it began by following a link from inviteLink().

const params = await QSPlaySDK.game.getInviteParams();
// opened via a link: { roomId: "abc123" }
// regular visit: null

Returns Record<string, DataValue> | null.

The value is fixed once, when the page is opened — repeated calls within a single session always return the same result, even if the URL changes later (for example, through client-side navigation without a page reload).

An invitation works only by following a link — opening it in a new tab or reloading the current one. If the invited player is already in the game at the moment the link is created, they won't receive any automatic notification about it — they still need to open the link (for example, from a chat or notification where the game puts it).