Login & connecting a Baziness account

#The identity model

Your game keeps its own player accounts, for example keyed by a device id generated on first launch. Baziness is attached on top:

1. The first time the platform is on, your server creates an anonymous Baziness user for the player (create-user) and saves its userId on the player's record.
2. The player stays anonymous (isLinkedToAccount: false) until they sign in with their phone number on a Baziness page. The account is then linked.
3. If the Baziness account they sign into already belongs to another of your players (the same person on another phone), your game switches to that player. It doesn't link the account twice.

#The whole flow

sequenceDiagram
  autonumber
  participant C as Game client
  participant S as Game server
  participant K as Platform API
  participant W as Baziness page (sheet)
  C->>S: GET /api/platform/config
  S-->>C: { enabled, webBase, apiBase, packageName }
  Note over C: Splash: Sign in with Baziness / Continue as guest
  C->>S: POST /api/platform/token { deviceId, linkedToken? }
  S->>K: create-user (first time) / get-user-token
  K-->>S: { userId, token, isLinkedToAccount }
  S-->>C: { token, bazinessUserId, isLinked, switchToDeviceId? }
  C->>W: open login page (sdkType=js, linkedToken, allowGuest=false)
  W-->>C: postMessage { type: "login", data: "<token>" }
  C->>S: POST /api/platform/login { deviceId, token }
  S->>K: validate-user-token
  K-->>S: { isValid, userId }
  S-->>C: { ok } — or { ok, switchToDeviceId }
  C->>C: close sheet, or switch device id + reload

#What your server provides

Your client never calls the platform's server API itself. It calls three endpoints of your own server:

If the platform is unreachable, /token answers { enabled: true, error: "platform_unavailable" } without a token, and the game boots anyway.

#The first launch: guest or sign in

When Baziness is on and the player has neither chosen yet nor signed in, the splash screen shows two buttons instead of the loading bar:

• «ورود با حساب بازینس» (sign in with Baziness): opens the sign-in page and waits.
• «ادامه به عنوان مهمان» (continue as guest): remembers the choice and continues.

The boot order:

1. Sign the player in to your own account system.
2. Ask your server for /api/platform/config. If Baziness is off, skip everything below.
3. If no choice was made and the player isn't signed in, show the two buttons and wait.
4. Call /api/platform/token. If it answers switchToDeviceId, adopt that id and restart.
5. If the player just signed in, load their profile again, so the screen shows the signed-in account.

If the player closes the sign-in page without signing in, show the two buttons again.

#Account switching, step by step

A switch happens when the Baziness account the player signs into is already linked to another of your players, for example after a reinstall or on a new phone:

1. Your server answers switchToDeviceId: "<that player's device id>".
2. The client saves that device id as its own and forgets its stored Baziness token.
3. It restarts, without linkedToken in the address.
4. The next boot loads the other player, with all their progress.

#Opening the game from the Baziness app

Important

The Baziness app now also sends ?linkCode= (one-time). Forward it to your server instead of linkedToken. See Token migration.

The Baziness app opens games with ?linkedToken=<token> in the address:

• Send that token as linkedToken to /api/platform/token, so the player lands in the right Baziness account. Remove it from the address on the next restart.
• If the device already holds a different token, a different Baziness account is arriving: clear the local data and start again before continuing.
• Signing in decides which account plays, never whether the player is new. A first-time player arriving this way must still see your tutorial and receive your welcome gifts.

#Signing in later, from Settings

A guest can connect their account at any time: Settings → open the profile page (parameters). When the view closes, ask /api/platform/token again and refresh the coin balance.

#Signing out

When the page sends logout, close the view, delete everything your game stored locally (identity, token, choices, tutorial progress) and restart as a brand-new visitor.

#Testing logins on the dev platform

Tip

On the development platform (the one test games use), you can sign in with any phone number and the code 111111. No SMS is sent. Make up numbers to create as many test accounts as you need: one for the account-switch test, one for a fresh guest, and so on. Production sends real SMS codes.

#Common mistakes

Ready-made code: server endpoints, client controller and messages.