Authentication

There are two ways to authenticate a player:

1. Built-in UI (recommended) — let the native SDK render the login/register screen.
2. Headless — call the auth methods yourself and draw your own UI.

Both go through AlogameAuth, imported from alogame-sdk.

Option 1 — Built-in login UI (recommended)

import { AlogameSdk, AlogameAuth } from 'alogame-sdk';

await AlogameSdk.init();

const result = await AlogameAuth.showLoginUI();
if (result.success) {
  console.log('Logged in:', result.user?.username);
}

This launches the native SDK's own login/register screen (username/password, guest, and whichever social providers are enabled for your game in the Alogame CMS) and resolves once the player completes it.

Option 2 — Headless (custom UI)

Use these when you build your own login screen. All resolve to an AuthResult.

import { AlogameAuth } from 'alogame-sdk';

// Username / password
const r1 = await AlogameAuth.login('username', 'password');

// Register — note the parameter order: (fullname, username, password)
const r2 = await AlogameAuth.register('Display Name', 'username', 'Password123!');

// Guest / Play Now
const r3 = await AlogameAuth.playNow();

// Social — the game completes the OAuth flow itself and passes the token
const r4 = await AlogameAuth.socialLogin('google', googleAccessToken);
// provider: 'google' | 'apple' | 'facebook' | 'tiktok'

if (r1.success) {
  console.log('User:', r1.user);
} else {
  console.error(r1.error?.code, r1.error?.message);
}

Account merge (guest → full account)

// Merge a guest (Play Now) session into a full account with username/password
await AlogameAuth.merge(uuid, 'username', 'Password123!');

// Or merge into a social provider account
await AlogameAuth.mergeSocial(uuid, 'google', googleAccessToken);

Password management

await AlogameAuth.forgotPassword('player@example.com');
await AlogameAuth.changePassword('oldPass', 'newPass');

Profile

await AlogameAuth.updateProfile({
  displayName: 'DragonSlayer',
  email: 'player@example.com',
  birthday: '01/01/2000',   // dd/MM/yyyy
});

const info = await AlogameAuth.fetchUserInfo();

OTP / verification

const status = await AlogameAuth.checkEmailVerification();

const otp1 = await AlogameAuth.requestEmailOtp();
const otp2 = await AlogameAuth.requestPhoneOtp();  // uses account phone if omitted

const verified = await AlogameAuth.verifyOtp('123456');

State queries

import { AlogameAuth } from 'alogame-sdk';

const user = await AlogameAuth.getCurrentUser();   // AuthUser | null
const loggedIn = await AlogameAuth.isLoggedIn();    // boolean

There is no reactive onAuthStateChanged subscription (unlike the Web SDK) — call these after any flow that may change the session (login, logout, merge), or poll on scene transitions.

Bind the player's game role (optional)

If your game has servers/characters, report the active role after login so Alogame can attribute sessions and payments correctly. This also feeds Analytics and Payment verification.

await AlogameAuth.setGameRole(
  'server-01',    // serverId
  'role-12345',   // roleId
  'Asia 1',       // serverName  (optional)
  'DragonSlayer', // roleName    (optional)
  42              // level       (optional)
);

Logout

await AlogameAuth.logout();

Reference

AuthResult

interface AuthResult {
  success: boolean;
  user?: AuthUser;
  loginMetadata?: LoginMetadata;  // account status, maintenance info
  error?: AlogameError;           // { code: number; message: string }
}

AuthUser (common fields)

Field	Type	Notes
userId	string	Numeric user id from the backend
uuid	string	Stable account UUID
username	string?	Login name
displayName / fullname	string?	Display name
email / phone	string?	Masked contact info
emailVerified / phoneVerified	boolean	Verification flags
isPlayNow	boolean	true for guest sessions
token	string	Session token (managed by the SDK)

Common error codes

Code	Meaning
1001–1012	Validation (invalid username, password, email, OTP…)
2001	Not logged in
2002	Session expired
2003	Account merge required
3001/3002	Network timeout / unavailable
3401	Unauthorized

Next step

→ Payment