Session #

A session is created when a player successfully logs in and persists until it expires or is terminated. It carries identity, display name, and platform metadata that backend services and clients can access on any request.

Player Session #

When a player logs in, the engine creates a PlayerSession that is carried in the session Jwt and passed to backend service handlers. The following fields are available on PlayerSession:

Field	Type	Description
`pragmaId`	`Fixed128`	Game Backend: Player Id (Guid), Social Backend: Social Id (Guid)
`socialId`	`Fixed128`	Player’s social Id (Guid)
`sessionId`	`Fixed128`	Unique Id for this specific session
`displayName`	`DisplayName`	Proto representation of player’s display name
`idProvider`	`string`	Authentication provider used at login (e.g. `"STEAM"`)
`distributionPlatform`	`string`	Distribution platform classifier supplied at login (e.g. `"STEAM"`)
`hardwareClass`	`string`	Hardware class classifier supplied at login (e.g. `"PC"`)
`hardwareDevice`	`string`	Hardware device classifier supplied at login (e.g. `"alienware"`)

PragmaId, PlayerId, and SocialId #

While the majority of services run only on one backend type (Game or Social), some services like Telemetry run on both. In these cases the RPC handlers are invoked on both backend types in a shared codepath. The engine uses playerId for Game user Ids and socialId for Social user Ids almost everywhere; pragmaId is reserved for these shared-backend handlers and is avoided otherwise.

We recommend assigning this field to a more precisely named variable for clarity.

The socialId was added to enable Game services to invoke Social RPCs (which require socialIds). The consequence is that for social RPCs, the pragmaId and socialId fields are identical.

Field	Backend	Resolves to
`pragmaId`	`GAME`	PlayerId
`pragmaId`	`SOCIAL`	SocialId
`socialId`	`GAME or SOCIAL`	SocialId

DisplayName #

Use PragmaDisplayName(session.displayName) to construct a domain object that exposes the individual components as well as the fully formatted name (e.g. SimpleName#1234).

Platform classifiers #

The three classifier fields (distributionPlatform, hardwareClass, hardwareDevice) are optional strings. See Login — With Login Options for how to seed them during client login.

Examples #

Accessing session fields in a backend service #

    import pragma.auth.PragmaDisplayName
    import pragma.utils.toUUID
    import pragma.utils.toUUIDString

    // Example Game Service RPC
    @PragmaRPC(SessionType.PLAYER, RoutingMethod.RANDOM)
    suspend fun echoV1(
        session: PlayerSession,
        request: EchoV1Request,
    ): EchoV1Response {
        val playerId = session.pragmaId.toUUID() // convert protobuf Fixed128 type to UUID type.
        println(session.socialId.toUUIDString()) // convert directly to string (with hyphens)
        println(PragmaDisplayName(session.displayName).fullDisplayName()) // SimpleName#1234
        
        //...
    }

Retrieving session fields from the Unreal SDK #

Most fields are available directly on FPlayer. The classifier fields require decoding the game Jwt.

// Direct FPlayer accessors
FString PragmaId      = PragmaPlayer->Id();
FString SocialId      = PragmaPlayer->SocialId();
FString DisplayName   = PragmaPlayer->DisplayName();
FString Discriminator = PragmaPlayer->Discriminator();
int32   IdProvider    = PragmaPlayer->GetCurrentIdProvider();

// Classifier fields require decoding the game JWT
const TPragmaResult<FPragmaJwt> Decoded = FPragmaJwt::FromEncoded(PragmaPlayer->PragmaGameToken());
if (Decoded.IsSuccessful())
{
    const FPragmaJwtPayload& Payload = Decoded.Payload().Payload;
    FString Platform = Payload.DistributionPlatform(); // e.g. "STEAM"
    FString HwClass  = Payload.HardwareClass();        // e.g. "PC"
    FString HwDevice = Payload.HardwareDevice();       // e.g. "alienware"
}

Retrieving session fields from the Unity SDK #

Most fields are available directly on Player. The classifier fields are present in the game Jwt under the short claim keys dp, hwc, and hwd.

    PragmaId pragmaId    = _player.Id;
    PragmaId socialId    = _player.SocialId;
    string displayName   = _player.DisplayName;
    string discriminator = _player.Discriminator;
    int    idProvider    = _player.CurrentIdProvider;

    // Decode the game JWT for additional identity claims
    var result = Jwt.FromEncoded(_player.PragmaGameToken);
    if (result.IsSuccessful)
    {
        string distributionPlatform = result.Payload.Payload.dp; // e.g., "STEAM"
        string hardwareClass = result.Payload.Payload.hwd;       // e.g., "PC"
        string hardwareDevice = result.Payload.Payload.hwd;      // e.g., "alienware"
    }