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()

import OegSdkV2

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

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)

Objective-C

#import <OegSdkV2/OegSdkV2-Swift.h>

[OegSdkCore setGameRoleWithServerId:@"server_01"
                         serverName:@"Server 1"
                             roleId:@"character_123"
                           roleName:@"DragonSlayer"
                              level:50];

Note: Objective-C does not support default parameters. You must pass all arguments. Use nil for optional strings and 0 for level if not available.

// Minimal call (required fields only)
[OegSdkCore setGameRoleWithServerId:@"server_01"
                         serverName:nil
                             roleId:@"character_123"
                           roleName:nil
                              level:0];

Usage Examples

Basic Usage

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

Full Usage with All Parameters

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

Update on Character Switch

// When player switches characters
func onCharacterSelected(_ character: Character) {
    OegSdkCore.setGameRole(
        serverId: character.serverId,
        serverName: character.serverName,
        roleId: character.id,
        roleName: character.name,
        level: character.level
    )
}

Update on Level Up

// When player levels up
func onLevelUp(newLevel: Int) {
    if let currentRole = OEGAuth.gameRole {
        OegSdkCore.setGameRole(
            serverId: currentRole.serverId,
            serverName: currentRole.serverName,
            roleId: currentRole.roleId,
            roleName: currentRole.roleName,
            level: newLevel
        )
    }
}

When to Call

Call setGameRole() in these scenarios:

1. After Login → Enter Game:

   OEGAuth.shared.login(username: username, password: password) { result in
       if case .success(let user) = result {
           // Player logged in, now entering game
           loadPlayerData { player in
               OegSdkCore.setGameRole(
                   serverId: player.serverId,
                   roleId: player.characterId,
                   roleName: player.characterName,
                   level: player.level
               )
           }
       }
   }

2. After Character Creation:

   func onCharacterCreated(_ character: Character) {
       OegSdkCore.setGameRole(
           serverId: character.serverId,
           roleId: character.id,
           roleName: character.name,
           level: 1
       )
   }

3. On Server Switch:

   func onServerChanged(newServerId: String, newServerName: String) {
       // Load character data for new server
       loadCharacterForServer(newServerId) { character in
           OegSdkCore.setGameRole(
               serverId: newServerId,
               serverName: newServerName,
               roleId: character.id,
               roleName: character.name,
               level: character.level
           )
       }
   }

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:

// Game calls IAP
OEGPayment.shared.purchaseAndVerify(productId: productId, gameData: gameData) { result in
    // SDK automatically tracks sdk_recharge event with:
    // - role_id from setGameRole()
    // - role_name from setGameRole()
    // - server_id from setGameRole()
    // - Falls back to gameData if setGameRole() not called
}

3. Fallback Behavior

If setGameRole() is not called, the SDK uses fallback data:

• IAP events: Uses GameData parameters passed to purchaseAndVerify()
• Other events: Uses empty strings for role fields

Best practice: Always call setGameRole() for accurate 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:

   OEGAuth.shared.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:

if let gameRole = OEGAuth.gameRole {
    let serverId = gameRole.serverId
    let serverName = gameRole.serverName
    let roleId = gameRole.roleId
    let roleName = gameRole.roleName
    let level = gameRole.level
}

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