Skip to main content

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.

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.

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.