Game Role API

The Game Role API allows you to provide player context (server, character, level) to the SDK for enriched analytics tracking.

Overview

When players enter your game and select a server/character, call setGameRole() to store this information. The SDK uses this data to enrich analytics events, particularly in-app purchase tracking (sdk_recharge).

API Reference

setGameRole()

Kotlin

import vn.oeg.sdk.v2.core.auth.OEGAuthCore

OEGAuthCore.setGameRole(
    serverId: String,
    serverName: String? = null,
    roleId: String,
    roleName: String? = null,
    level: Int = 0
)

Java

import vn.oeg.sdk.v2.core.auth.OEGAuthCore;

// All parameters required from Java — use null for optional String, 0 for default level
OEGAuthCore.INSTANCE.setGameRole(serverId, serverName, roleId, roleName, level);

Parameters:

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

Returns: Nothing (void)

Storage: In-memory only (cleared on logout)

Usage Examples

Basic Usage

Kotlin

// After player selects server and character
OEGAuthCore.setGameRole(
    serverId = "server_01",
    roleId = "character_123"
)

Java

OEGAuthCore.INSTANCE.setGameRole("server_01", null, "character_123", null, 0);

Full Usage with All Parameters

Kotlin

OEGAuthCore.setGameRole(
    serverId = "asia_server_1",
    serverName = "Asia Server 1",
    roleId = "char_abc123",
    roleName = "DragonSlayer",
    level = 50
)

Java

OEGAuthCore.INSTANCE.setGameRole("asia_server_1", "Asia Server 1", "char_abc123", "DragonSlayer", 50);

Update on Character Switch

Kotlin

// When player switches characters
fun onCharacterSelected(character: Character) {
    OEGAuthCore.setGameRole(
        serverId = character.serverId,
        serverName = character.serverName,
        roleId = character.id,
        roleName = character.name,
        level = character.level
    )
}

Java

public void onCharacterSelected(Character character) {
    OEGAuthCore.INSTANCE.setGameRole(
        character.getServerId(),
        character.getServerName(),
        character.getId(),
        character.getName(),
        character.getLevel()
    );
}

Update on Level Up

Kotlin

// When player levels up
fun onLevelUp(newLevel: Int) {
    val currentRole = OEGAuthCore.gameRole
    if (currentRole != null) {
        OEGAuthCore.setGameRole(
            serverId = currentRole.serverId,
            serverName = currentRole.serverName,
            roleId = currentRole.roleId,
            roleName = currentRole.roleName,
            level = newLevel
        )
    }
}

Java

public void onLevelUp(int newLevel) {
    OEGGameRole currentRole = OEGAuthCore.INSTANCE.getGameRole();
    if (currentRole != null) {
        OEGAuthCore.INSTANCE.setGameRole(
            currentRole.getServerId(),
            currentRole.getServerName(),
            currentRole.getRoleId(),
            currentRole.getRoleName(),
            newLevel
        );
    }
}

When to Call

Call setGameRole() in these scenarios:

1. After Login → Enter Game:

Kotlin

OEGAuth.login(username, password) { result ->
    if (result is AuthResult.Success) {
        // Player logged in, now entering game
        loadPlayerData { player ->
            OEGAuthCore.setGameRole(
                serverId = player.serverId,
                roleId = player.characterId,
                roleName = player.characterName,
                level = player.level
            )
        }
    }
}

Java

OEGAuth.INSTANCE.login(username, password, result -> {
    if (result instanceof AuthResult.Success) {
        loadPlayerData(player -> {
            OEGAuthCore.INSTANCE.setGameRole(
                player.getServerId(), null,
                player.getCharacterId(), player.getCharacterName(),
                player.getLevel()
            );
        });
    }
});

2. After Character Creation:

Kotlin

fun onCharacterCreated(character: Character) {
    OEGAuthCore.setGameRole(
        serverId = character.serverId,
        roleId = character.id,
        roleName = character.name,
        level = 1
    )
}

Java

public void onCharacterCreated(Character character) {
    OEGAuthCore.INSTANCE.setGameRole(
        character.getServerId(), null,
        character.getId(), character.getName(), 1
    );
}

3. On Server Switch:

Kotlin

fun onServerChanged(newServerId: String, newServerName: String) {
    // Load character data for new server
    loadCharacterForServer(newServerId) { character ->
        OEGAuthCore.setGameRole(
            serverId = newServerId,
            serverName = newServerName,
            roleId = character.id,
            roleName = character.name,
            level = character.level
        )
    }
}

Java

public void onServerChanged(String newServerId, String newServerName) {
    loadCharacterForServer(newServerId, character -> {
        OEGAuthCore.INSTANCE.setGameRole(
            newServerId, newServerName,
            character.getId(), character.getName(), character.getLevel()
        );
    });
}

How It's Used

The SDK uses game role data in the following ways:

1. Analytics Events

Role information is automatically included in analytics events:

• sdk_recharge (IAP events): Includes role_id, role_name, server_id
• sdk_logout: Includes server_id
• Custom events: Available for game-specific tracking

2. IAP Tracking

When a player makes an in-app purchase, the SDK automatically includes role context:

Kotlin

// Game calls IAP
OEGPayment.purchaseAndVerify(productId, gameData) { result ->
    // SDK automatically tracks sdk_recharge event with:
    // - role_id from gameData (primary); falls back to setGameRole() if gameData field is empty
    // - role_name from gameData (primary); falls back to setGameRole() if empty
    // - server_id from gameData (primary); falls back to setGameRole() if empty
}

Java

OEGPayment.INSTANCE.purchaseAndVerify(productId, gameData, (purchaseResult, result) -> {
    // SDK automatically tracks sdk_recharge event with role data from gameData (primary)
});

3. Priority and Fallback Behavior

For IAP analytics, the SDK uses GameData as the primary source (it is always present at purchase time). setGameRole() data is used as a fallback when a GameData field is empty.

Field	Primary	Fallback
role_id	gameData.characterId	gameRole.roleId
role_name	gameData.characterName	gameRole.roleName
server_id	gameData.serverId	gameRole.serverId

For non-IAP events (e.g. sdk_logout), the SDK uses setGameRole() data directly.

Best practice: Always populate GameData fields when calling purchaseAndVerify() for accurate IAP tracking.

Data Lifecycle

Storage

• Location: In-memory only (not persisted to disk)
• Scope: Current session only
• Access: Internal to SDK (not exposed to game)

Clearing

Game role data is automatically cleared in these scenarios:

1. User logs out:

Kotlin

OEGAuth.logout() // Clears game role automatically

Java

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

2. Session expires:

   • SDK receives 401 from backend
   • Game role cleared during session cleanup

3. Force logout (maintenance):

   • SDK force logs out user
   • Game role cleared

Persistence

Game role data is NOT persisted across app restarts. You must call setGameRole() again after:

• App restart
• User logs in again
• Session restoration

Reading Game Role (Internal)

The game role data is stored internally and used by the SDK. Games typically don't need to read it back, but if needed:

Kotlin

val gameRole = OEGAuthCore.gameRole

if (gameRole != null) {
    val serverId = gameRole.serverId
    val serverName = gameRole.serverName
    val roleId = gameRole.roleId
    val roleName = gameRole.roleName
    val level = gameRole.level
}

Java

OEGGameRole gameRole = OEGAuthCore.INSTANCE.getGameRole();

if (gameRole != null) {
    String serverId   = gameRole.getServerId();
    String serverName = gameRole.getServerName();
    String roleId     = gameRole.getRoleId();
    String roleName   = gameRole.getRoleName();
    int level         = gameRole.getLevel();
}

Note: This is read-only. Use setGameRole() to update.

Best Practices

✅ Do

• Call setGameRole() as soon as player enters the game
• Update when player switches servers or characters
• Use meaningful IDs (e.g., "server_01", not "1")
• Include optional fields when available (improves analytics)

❌ Don't

• Don't call before login completes
• Don't use sensitive data in role names
• Don't call excessively (only on actual changes)
• Don't rely on persistence across sessions

Troubleshooting

Role data not appearing in analytics

Problem: IAP events show empty role fields

Solutions:

1. Verify setGameRole() is called after login
2. Check that it's called before IAP purchase
3. Ensure parameters are non-empty strings
4. Check logs for any SDK errors

Role data cleared unexpectedly

Problem: Role data disappears during session

Cause: User logged out or session expired

Solution: Re-call setGameRole() after re-login

Multiple characters per account

Problem: Game supports multiple characters, which one to track?

Solution: Call setGameRole() for the currently active character. Update when player switches characters.

Related Documentation

• Analytics Tracking - Auto-tracked events that use role data
• In-App Purchases - IAP flow that includes role tracking
• Authentication - Login flow and session management