Skip to main content

QSPlaySDK.user

Data about the current portal player, the authentication prompt, and a subscription to sign-in/sign-out. For how a game is expected to use accounts, see Requirements · Accounts, Progress & Multiplayer.

Current player​

user.getUser() returns the current player's data. A guest and a signed-out user are indistinguishable to the game — both cases return null.

const user = await QSPlaySDK.user.getUser();
// signed in: { qsid: "YM4YAL", name: "Alex", avatarUrl: "https://..." }
// guest / not signed in: null

Returns SdkUser | null:

interface SdkUser {
qsid: string;
name: string;
avatarUrl: string | null;
}
FieldDescription
qsidThe player's public identifier on the portal. Not a secret — it can be used for display (for example, in the game's own leaderboard), but not to verify authenticity — for that, see the token for the game backend.
nameThe player's display name.
avatarUrlA link to the player's avatar, or null if no avatar is set.

Call this method again after the authChanged event rather than caching the result for long — the player can sign in or out without leaving the game.

Authentication prompt​

user.showAuthPrompt() shows the player the portal's sign-in screen without leaving the game page.

await QSPlaySDK.user.showAuthPrompt();

Use it when the game needs a signed-in player (for example, to record a score in a leaderboard) and getUser() has just returned null. After a successful sign-in the authChanged event fires — continue the flow on that, not on the result of showAuthPrompt() itself, which only opens the sign-in screen and doesn't report how it ended.

Authentication listener​

user.addAuthListener(callback) subscribes to sign-in/sign-out of the portal account without leaving the game (for example, the player opened the portal's login screen in a neighbouring tab and signed in there).

const unsubscribe = QSPlaySDK.user.addAuthListener(({ user }) => {
// user: SdkUser | null
});

// later, if you need to unsubscribe:
unsubscribe();

Event payload (portal → game):

interface AuthChangedEventPayload {
user: SdkUser | null;
}

Subscribe to this event once at game start and use it to reset the token/profile you have cached and, if necessary, to repeat getUserToken().

Token for the game backend​

user.getUserToken() returns a short-lived token for the game's server, so that the game's backend can confirm the player's identity to the portal when recording a result (for example, in a leaderboard), without trusting qsid from getUser() alone (it isn't a secret — it is also visible in other public places on the portal).

const token = await QSPlaySDK.user.getUserToken();
// send the token to your backend; the backend presents it to the portal

Returns a string — the token itself. Its lifetime isn't exposed: the SDK keeps it internally and silently refreshes the token about 30 seconds before it expires — repeated getUserToken() calls within that window return the cached value without a new request to the portal.

If nobody is signed in, the promise rejects with an SdkError, error.code === "USER_NOT_AUTHENTICATED" (the full list of codes is on the Errors page):

try {
const token = await QSPlaySDK.user.getUserToken();
} catch (error) {
if (error.code === "USER_NOT_AUTHENTICATED") {
await QSPlaySDK.user.showAuthPrompt();
// request the token again after the authChanged event
}
}

Token format and backend verification​

The token is an RS256-signed JWT bound to this particular game, not to the portal as a whole. Inside is the same qsid as in user.getUser().qsid (not the portal's internal numeric id — that is never exposed externally), so the token can be checked against what the game has already received from the client via getUser(). An example of the decoded payload:

{ "qsid": "YM4YAL", "game_code": "brain-blast", "iat": 1727520000, "exp": 1727523600 }
FieldDescription
qsidThe player's public identifier — matches user.getUser().qsid.
game_codeThe code of the game the token was issued for — check it against the expected one if your backend serves several games.
iatThe time the token was issued, unix time in seconds.
expThe time the token expires, unix time in seconds. Lives for about an hour.

The public key for verifying the signature (RS256, PEM) is served at a short address:

https://play.quartsoft.com/publicKey.json

Fetch it once and cache it on your side (if signature verification fails, it's worth re-fetching in case the key was rotated) — the signature is verified locally on your server, without calling the portal on every request:

import jwt from "jsonwebtoken";

const { publicKey } = await fetch("https://play.quartsoft.com/publicKey.json").then((r) => r.json());

const { qsid, game_code } = jwt.verify(token, publicKey, { algorithms: ["RS256"] });

Don't decode or trust the token on the client — verifying the signature only makes sense on your server, which has grounds not to trust the client.