Turnkeyxgaming

Guide · Integration

The launch call is where the session is decided

A game launch is a request for a URL. The parameters on that request decide whose balance is used, which language the client attempts, and where the player returns when they close the game.

7 min readUpdated By the Turnkeyxgaming team

Five parameters that cause real incidents

Player id and currency select the wallet. Language selects a translation, with a fallback you should know about. The lobby URL is where the client sends the player on exit. The cashier URL is where it sends them when the balance is too low to stake. If those two URLs point at production while you are testing in staging, a tester will walk into the live site mid-session. Build them from the environment, do not paste them.

Tokens expire. A URL saved in a chat and opened an hour later should fail closed, with a new launch, not resume a dead session. Do not put a long-lived secret in the query string. The launch token is enough for that session and nothing else.

Build the return addresses from the environment that issued the token. A staging lobby URL pasted into a production config, or the reverse, walks a tester onto the live site or a player onto a half-built cashier. Language is the other parameter people hard-code to English and then forget. Send the player's choice, and know which fallback the client will load when that translation is missing, so support is not reading a rules card the player never saw.

Parameters that decide the session

These five are enough to cause an incident on their own. Anything else on the query string is optional. These are not.

ParameterWhat it selectsIncident when it is wrong
Player idWhose balance is debited.Another account's money, or a staff user left in a shared test login.
CurrencyWhich of that player's balances the round locks to.A debit in one code and a credit in another if something tries to switch later.
LanguageThe translation the client attempts, then your chosen fallback.Rules text in a language your support team cannot read back to the player.
Lobby URLWhere the client sends the player on exit.A production homepage in the middle of a staging test, or a dead page.
Cashier URLWhere the client sends them when the balance cannot cover the stake.A top-up that returns to the wrong brand, or nowhere.

Before the first real launch

  1. 01

    Environment URLs

    Generate lobby and cashier URLs from the environment you are actually in.

  2. 02

    Expiry

    Confirm an old launch URL is refused and that the lobby can ask for a fresh one.

  3. 03

    Language fallback

    Decide what the player sees when the requested language is missing.

The launch token is a bearer for that session

A URL copied into a ticket can be opened by anyone who can read the ticket, until it expires. Keep the lifetime short, refuse a token past its time, and do not put a long-lived secret beside it in the query string.

A launch that worked and a return that lost the player

At 14:02 a player tapped a tile on brand A's lobby. The launch call answered, the client opened, the balance chip showed the right figure, and the game ran for forty minutes without a fault. When they closed it, the client sent them to the lobby address passed at launch, which on this brand lives on a subdomain that expects a session cookie set by the marketing site. The player arrived logged out, looking at a welcome offer they had already claimed. Eleven tickets in the first hour described it as 'my balance is gone'.

Nothing in the launch failed and the wallet never moved. The incident lived in the two return addresses, which were copied from a config file written before the brand moved its lobby to that subdomain. A better homepage URL is not the fix. The fix is a handoff endpoint on the brand's own domain that reads a short-lived return token, mints the session, and then redirects; the client's exit control and its low-balance control both point at that endpoint rather than at a page.

Test the exits rather than only the entry. Open one game and close it with the client's own control, then with the browser back gesture, then force the low-balance path with a balance below the minimum stake, then abandon a session and come back an hour later. Each of those four lands somewhere, and three of them are not the launch call at all. Write the four destinations into the integration note beside the launch table, so the next person to change a domain can see what depends on it.

What to capture for a launch before it ships

Five values and one owner. Most of this is invisible until a domain, a translation file or a wallet moves.

  • The host and path of each return address, written with the environment in the URL, so a staging value is visibly staging rather than plausibly production.
  • The lifetime of the launch token in seconds, and the component that actually enforces it. A countdown in the client is a hint, not enforcement.
  • The handoff endpoint that exchanges a return token for a session on the brand's domain, and the person who owns it when it breaks at a weekend.
  • The language order sent on the request, and the code the client reported loading on the last test session, which are rarely the same field.
  • The currency passed and the label on the balance chip, checked on an account that holds two wallets rather than on a single-wallet test user.
  • The date a human last read the config, because a domain move somewhere else in the estate is the usual cause of a dead return.

FAQ

Questions operators ask

Can the game change the currency after launch?

It should not. Currency is fixed for the session. A different currency is a new launch against the wallet that holds it.

Can the lobby refresh a game by reusing this morning's launch URL?

No. Ask for a new launch. An expired token fails closed. Replaying a saved URL either errors in a way the player cannot act on, or, if you forgot the expiry, resumes a session that should have ended.

Should language and currency travel as cookies instead of launch parameters?

No. The launch request is the contract the studio sees. A cookie on your domain is invisible to that request. If the cookie and the parameter disagree, the session will follow the parameter and your UI will follow the cookie.

Should the lobby URL point at the game's category or at the homepage?

At whatever the player would expect after finishing a game: the category they came from, or the last lobby screen. A homepage makes a normal close look like an ejection. A deposit page is worse, because it implies the session ended for want of money and reads as a prompt to spend again.

The client appends its own query parameters to our return URL. Does that break the token?

Assume it will append something. Read the return token by name and ignore unknown parameters rather than requiring an exact match or relying on position. An endpoint that refuses extra parameters breaks on the first client release that adds one, and the player sees an expired-session message for what is a parsing bug.

Keep reading

Related pages

  • DocumentationAPI docsAuthentication, the game list, demo and real launch, AES-encrypted wallet callbacks and error handling, with test keys to start.Read
  • IntegrationIntegrationSandbox keys, AES-encrypted wallet callbacks and the four wallet endpoints, then a 24–72 hour go-live once decryption and retries pass.Read
  • Guide · LobbyLanguage fallbacksIf a game lacks the player's language, choose the fallback order deliberately. Do not keep the studio's compiled default.Read
  • Product · WalletWalletBalance, bet, win and rollback on one seamless wallet: idempotent transaction ids shared by casino games and sportsbook alike.Read

Get a written quote and sandbox access

Tell us your licence, target markets and products. You get the GGR rate in writing, the studio list for your markets and sandbox credentials.

Telegram @turnkeyxhub WhatsApp Email Contact form