Account integration scenarios
Account integration scenarios
Pick the scenario that matches your game. All of them must keep guests playing.
1. Your game has no accounts#
Use the data module for saves. Nothing else is required. Showing the player's portal name in the HUD via getUser() is optional.
2. Use the ZokoGames profile#
Use the portal identity as the account. Read getUser() for the name and avatar, and listen with addAuthListener for sign-ins. Offer showAuthPrompt() on a button, never automatically. Store progress with the data module or your backend keyed by the verified userId.
3. Your own backend, guests allowed (basic integration)#
You run your own login and server saves.
- Guests must be able to play without creating an account.
- Remove or disable external login methods (social login buttons) in the portal build.
- Call
getUserToken()on every launch, verify it server-side, and use it to look up or create the account for thatuserId. - If the call fails with
userNotAuthenticated, let the player continue as a guest. Do not open the sign-in dialog on your own.
4. Your own backend, linked accounts (full integration)#
Players who already have a game account can link it to their ZokoGames identity.
- Player signs in to the portal (
showAuthPrompt). - Your game verifies the token on the server.
- If the
userIdis already linked, load that account. - If not, call
showAccountLinkPrompt(). On"yes", link theuserIdto the player's game account. On"no", continue as a guest. - From then on the ZokoGames identity wins: log them in with it on every launch.
Guidance:
- Refresh the stored username and avatar when they change.
- Prefer linking to a new account over merging two accounts that both have progress.
- Never trust
__dangerousUserIdfrom the client. Use the token.
Saving progress#
Progress must be saved one of three ways: the data module, your own backend linked through the user module, or both. A game that loses progress when the tab closes will not pass full launch.