Game Role API

The Game Role API tells the SDK which server and character the player is currently on — used to enrich the SDK's auto-tracked analytics events with player context.

The One Rule

There is exactly one call to make: OEGAuth.setGameRole(), any time the player's server, character, or level changes. It's cheap and safe to call often — there's no separate API for "on level up" or "on character switch," it's always the same call, wired to whatever hook in your game already notices player state changing.

Call it from every one of these trigger points:

• Right after login, once you know the player's starting server/character
• After creating a new character
• Whenever the player switches character or server — this fires sdk_switch_role automatically, no extra step needed
• Whenever the player levels up — easy to forget since it's not a "switch," but skipping it means level silently drifts stale in analytics with no error to flag it

import { OEGAuth } from '@alogame/web-sdk';

// Call this from wherever your game already tracks these values changing —
// login, character creation, server switch, level up all funnel through here.
async function reportGameRole(player: Player) {
  await OEGAuth.setGameRole(
    player.serverId,
    player.characterId,
    player.serverName,
    player.characterName,
    player.level
  );
}

When the player instead leaves to a character/server-select screen with no role picked yet — a real gap, not a direct switch — call logoutGameRole() first so no stale role backs analytics in the meantime (see below).

API Reference

setGameRole()

import { OEGAuth } from '@alogame/web-sdk';

await OEGAuth.setGameRole(
  serverId: string,
  roleId: string,
  serverName?: string,
  roleName?: string,
  level?: number
);

Parameters:

Parameter	Type	Required	Description
serverId	string	✅ Yes	Game server identifier (e.g., "server_01", "asia_1")
roleId	string	✅ Yes	Character/role unique identifier
serverName	string	❌ No	Human-readable server name (e.g., "Asia Server 1")
roleName	string	❌ No	Character/role display name (e.g., "DragonSlayer")
level	number	❌ No	Character level

Returns: Promise<void> — resolves once the local role is stored; the backend sync (PUT /v2/user/game-role) is fire-and-forget and never rejects the call.

Storage: Persisted (survives a page reload), cleared on OEGAuth.logout(). This is the one place web intentionally differs from native, where the role is in-memory only — a browser tab reload shouldn't force the game to re-declare the role.

Analytics: If a role was already active and serverId/roleId actually change, fires sdk_switch_role (old + new server/role). The very first call after login (or after a page reload that restores a persisted role) is treated as an initial pick, not a switch, and does not fire it.

logoutGameRole()

Clears the active character/server context without logging the account out — call when the player returns to a server/character-select screen, before the next setGameRole() call for the newly chosen one. Optional: calling setGameRole() again directly for the new role is enough for a plain switch; use logoutGameRole() when there's a real gap (e.g. player is back at the character-select screen with no role picked yet).

import { OEGAuth } from '@alogame/web-sdk';

await OEGAuth.logoutGameRole();
// Game role cleared — navigate to your own switch-server screen here
navigateToServerSelect();

Returns: Promise<void> — the SDK only clears its own state, it does not navigate anywhere; move to your own switch-server screen after this resolves.

Analytics: Fires sdk_logout_game_role (with the role that was just cleared) — but only when a role was actually active. Calling it when no role is set is a safe no-op and does not fire the event.

Auto-tracked analytics events

Event Name	Constant (OEGEvents)	Trigger
sdk_switch_role	OEGEvents.SWITCH_ROLE	setGameRole() replaces an already-active role with a different server/role. Includes old_server_id, old_role_id, server_id (new), role_id (new)
sdk_logout_game_role	OEGEvents.LOGOUT_GAME_ROLE	logoutGameRole() clears an active role. Includes server_id, role_id (the role that was cleared)

These enrich the SDK's four built-in lifecycle events (sdk_show_login, sdk_register_success, sdk_login_success, sdk_logout) with server_id, role_id, server_name, role_name, role_level whenever a role is set — see Analytics.

Data Lifecycle

Storage

• Location: Persisted via the SDK's storage adapter (survives a page reload)
• Scope: Cleared on OEGAuth.logout() so it never leaks into the next account
• Access: Internal to the SDK (not exposed to the game — write-only)

Clearing

Call logoutGameRole() explicitly when the player returns to a server/character-select screen (fires sdk_logout_game_role). Game role data is also cleared automatically — silently, no event — when the account logs out:

await OEGAuth.logout(); // Clears game role automatically

Best Practices

✅ Do

• Wire setGameRole() into whichever single place your game already tracks server/character/level — don't treat login, character switch, and level-up as separate integrations
• Include level every time, not just at login — it's the field most likely to go stale if treated as optional
• Use meaningful IDs (e.g., "server_01", not "1")

❌ Don't

• Don't call before login completes
• Don't use sensitive data in role names
• Don't skip re-calling it on level-up because it "isn't a switch" — same call, just a changed value

Related Documentation

• Analytics - Auto-tracked events that use role data
• Authentication - Login flow and session management