FAQ
SDK integration
Do I need the SDK if my game doesn't use accounts or cloud saves?
Yes. Every game must call game.loadingStart() / game.loadingStop() and
game.gameplayStart() / game.gameplayStop() — the portal uses them to count game launches and
activity for analytics, regardless of whether the game uses accounts or progress. See
Requirements · Technical Requirements.
My game has levels or rounds. Where do the lifecycle calls go?
Call game.loadingStart() / game.loadingStop() once, around the game's initial loading, and wrap
every round or level in game.gameplayStart() / game.gameplayStop(). Don't call the loading pair
for each level or restart: the portal treats every extra loadingStart() as the game reloading and
starts a new session, so the game's session and play counts grow with the number of rounds instead of
the number of launches. See
SDK · Sessions and gameplay segments.
How do I add the SDK to my game?
Add a <script> tag to the <head> of your index.html, before the tag that loads your game's
code. The SDK is exposed as the global window.QSPlaySDK — it isn't distributed through npm, so
there is nothing to import or install, and the global is used the same way whether or not your
game is built with a bundler. See SDK · Including the SDK.
Which engines and frameworks does the SDK work with?
The SDK is plain JavaScript that talks to the portal through postMessage, so it doesn't depend on
any engine. Any HTML5 game that can load a <script> tag and call a global object from its own
code can use it (Phaser, PixiJS, a custom engine, a Unity WebGL export calling into JavaScript,
etc.).
Do I need to wait for a "ready" event before calling SDK methods?
No. Calls made before the SDK and the portal have finished their handshake are queued and sent in
order as soon as it completes, so you can call methods right after the script has loaded. The
10-second request timeout still applies to queued calls, though — if the portal never answers, they
reject with TIMEOUT.
Will an SDK update break my game?
Not silently. The path in the script URL (v1/sdk.js) is the protocol's major version: it changes
only when the protocol changes incompatibly. New methods and optional fields are added within the
same version, so a game that is already published keeps working. See
SDK · SDK version.
Accounts and progress
Why does user.getUser() return null when I'm signed in?
First, a guest and a signed-out user look identical to the game — both give null.
If you're sure the player is signed in, the most likely cause is that they signed in after the
game had already called getUser(). Subscribe once at startup with
addAuthListener and call getUser() again whenever
authChanged fires, instead of relying on a value cached at startup.
Also check whether the game is running in mock mode (QSPlaySDK.env.isMock): there the accounts are
test ones, not real. See How do I test different user states without the real
portal?.
How do I ask a guest to sign in?
Call user.showAuthPrompt(). It only opens the portal's
sign-in screen and doesn't report how it ended, so continue the flow in the authChanged listener.
Don't build your own login forms inside the game — see
Requirements · Do Not Implement Custom Login Screens.
Can my backend identify the player by qsid?
No. qsid is public — it appears in other places on the portal — so it can be used for display but
not to prove who the player is. To verify a player on your backend, send the result of
user.getUserToken() from the client and verify it on the server: it is an RS256-signed JWT that
you check locally against the public key from https://play.quartsoft.com/publicKey.json. See
SDK · Token format and backend verification.
Can I store the token from getUserToken() and reuse it later?
There is no need to. The SDK caches the token and silently refreshes it about 30 seconds before it
expires (it lives for roughly an hour), so call getUserToken() every time your backend needs one
rather than keeping it yourself. The cache is also reset when the player signs in or out.
Where is the player's progress stored?
For a guest, in the portal page's storage, scoped to your game; for a signed-in player, on the
portal's server, scoped to their account and available from any device. When a guest signs in, the
portal moves their guest data into the account for you (keys that already exist in the account
aren't overwritten). Your game uses the same data.* calls in both cases. See
SDK · Data module.
How much data can I save?
1 MB per player per game, counted as the JSON size of all keys together. When a write would exceed
it, the promise rejects with DATA_QUOTA_EXCEEDED. Keep to progress, settings, and achievements —
not full state snapshots or assets. See SDK · Writing a value.
Why doesn't data.setItem() reach the portal immediately?
Writes are debounced on purpose: the SDK collects changes until there has been 1 second without
new calls (and flushes no later than 30 seconds after the batch started), then sends them in a
single request. If it matters that the data is actually saved, await the promise — it settles
only after the portal has answered. See
SDK · Write debouncing.
The SDK doesn't flush on page close, so a write made less than a second before the player closes the
tab can be lost. Await setItem() at natural checkpoints (a level completed, a purchase made)
rather than relying on the debounce.
Does the portal see the progress I save with data.setItem()?
No. The Data Module is your game's own save: the portal stores it but never reads it. To show the
player's level in this game in their portal profile, report one number with
game.reportPlayerLevel() — a level, or for a game without levels something that grows with progress,
such as rounds played. Report overall progress rather than the current position, so replaying an
early level doesn't make the level drop. Nothing is stored for guests, so report again after sign-in.
See SDK · Player level.
Multiplayer
Does QS Play provide multiplayer servers or matchmaking?
No. Rooms, matchmaking, state synchronization, and chat must be provided by the game itself. The SDK only carries invitation parameters from the player who creates a link to the player who opens it. See Requirements · Multiplayer Games.
How do invitation links work?
Create the room on your own server, then call
game.inviteLink(params) with whatever the game needs
to rejoin it (typically a room id) and give the returned URL to the player. When another player
opens that link, game.getInviteParams() returns the same params — join the room directly
instead of showing the main menu. In a regular visit it returns null.
Why doesn't getInviteParams() return anything for a player who is already in the game?
Invitations work only when the link is opened — in a new tab or by reloading the page. The value is fixed once when the page opens, and the portal has no live notifications for players who are already playing. If you need real-time invitations, the game has to deliver them itself. See SDK · Getting invite parameters.
Ads
Can I show my own ads instead of the SDK's?
No. Don't include your own ad code or any third-party ad SDK in the build — use
ad.requestAd() and banner.* only. The portal alone
decides which ads are shown, when, and how often. See Requirements · Ads.
Can I show a banner while the player is actively playing?
Yes — it isn't limited to menus and pauses. The only rule is that it must never cover the playable area or crowd a button/control, for example in the empty margins around a game that's narrower than the frame it's shown in. See Requirements · Where banners may appear.
Do I need to refresh banners myself?
No. The creative refreshes itself automatically on the portal's own schedule once requestBanner()
(or requestResponsiveBanner()/requestOverlayBanner()) resolves — there's nothing to call
periodically. Call it again with the same id only when you need to change something about that
slot. See SDK · Rendering into your own element.
Does ad.requestAd() reject if no ad is available?
No — it never rejects. It resolves once the whole flow is over either way, and reports a failed or
unfilled ad through the adError callback instead, so you can await it without try/catch.
banner.* calls are different: they do reject with SdkError on failure. See SDK · Requesting an
ad.
Can I test ads without a live portal?
Yes. In mock mode, ad.requestAd() shows a visible full-screen
placeholder and simulates the adStarted/adRewarded/adFinished sequence, and banner.* renders
a gray placeholder box — enough to test your pause/mute/reward logic locally without a live portal.
See SDK · Ad module — Testing without ads.
Testing and debugging
Can I develop the game without access to the portal?
Yes. When the game isn't opened inside an <iframe> (for example, in a separate tab during local
development), the SDK switches to mock mode automatically: all methods resolve locally with test
data. See SDK · Testing.
How can I see what the SDK sends and receives?
Add ?sdk-debug=1 to the page URL. A panel appears in the bottom-right corner that logs every
module.method call, its result or error, and every event. It works in both mock mode and on the
real portal. See SDK · Testing.
How do I test different user states without the real portal?
In mock mode, QSPlaySDK.__mock gives you login(), logout(), and setLocale() from the
console. Query parameters (?sdk-mock-user=, ?sdk-mock-auth-prompt=, ?sdk-mock-token-error=,
?sdk-mock-invite=) set the starting state directly in the link, which is handy for QA and
screenshot tests. See SDK · Testing.
How do I test an invitation link locally?
Call game.inviteLink() in mock mode, copy the ?sdk-mock-invite=... part from the returned URL,
and open the game with it. game.getInviteParams() then returns the same parameters. See
SDK · Controlling the user via query parameters.
Troubleshooting
The SDK can't find the host and my messages don't reach the portal
Most likely the game isn't running inside the portal's <iframe> — for example, it was opened
directly by its own URL. In that case the SDK deliberately runs in mock mode instead of trying to
reach a parent that doesn't exist. Check QSPlaySDK.env.isEmbedded and QSPlaySDK.env.isMock in the
console. Also make sure the URL doesn't contain a leftover ?sdk-mock=1, which forces mock mode even
inside an iframe.
What happens if the portal doesn't respond to a request?
The promise rejects with SdkError and error.code === "TIMEOUT" after 10 seconds. Calls to the
data module that read from or write to the portal's server are retried once, so they can take up
to about 20 seconds before failing. Handle TIMEOUT like any network problem — retry or show a
message to the player. The full list of codes is on the SDK · Errors page.
What happens if a player has an ad blocker?
Ad calls never hang forever either way. If the ad-frame itself is blocked from loading, or it loads
but Playgama's script inside it is blocked, the SDK gives up after about 8 seconds:
ad.requestAd() calls adError (it never rejects), and
banner.* rejects with SdkError, error.code === "other". Treat that
exactly like "no ad was available" — see Requirements · Ads.
The loading size reported for my game looks too small
The SDK measures the game's size with the browser's Resource Timing API. For resources served from
another domain, the browser exposes their size only if that server sends the Timing-Allow-Origin
header; otherwise they are left out and the total is understated. Host your assets on the same
domain as the game or add the header. See SDK · Game loading.
Still have questions?
If the answer isn't here, contact the QS Play team directly.