Skip to main content

SDK Initialisation & Handshake

SDK initialisation is the process where PlayServ prepares the runtime context required to start a session and reach a usable state for gameplay features. This includes:

  • collecting required configuration inputs
  • establishing client readiness via PlayServ.Ready(...)
  • establishing server readiness via PlayServ.Server.Ready()
info

Use this flow whenever you need to:

  • start a session at application launch
  • authenticate immediately at session start via Ready(UserToken) or later during runtime
  • ensure the server runtime is ready before clients can join

Before you start​

SDK initialisation requires a project and credentials configured in the PlayServ Backoffice. Complete these steps first if you have not done so yet.

1

Create a project in the Backoffice

Open the PlayServ Backoffice and create a new project. This gives you a Game ID — the project identifier you will need during SDK setup.

The project also creates a Development environment automatically, which is where you will work during integration.

Creating a New Project →

2

Generate a Game Access Token

In the project workspace, open the SDK Keys section and generate a Development key. This becomes your Game Access Token — the credential the SDK uses to connect to the correct project environment.

Store it safely. The full key value is only shown once at the moment of creation.

SDK Key Generation and Management →

3

Connect the project to Unity

Import the PlayServ Unity package and open the PlayServ settings window. Enter the Game Access Token and Game ID from the previous steps.

After this, the SDK can resolve the project configuration from the PlayServ config asset.

Connecting a Project to Unity →

Configuration inputs​

PlayServ requires four inputs to establish a session. Three of them are managed automatically — only the Game Access Token needs to be configured by the developer.

InputSourceManaged by
GameAccessTokenConfigured in the PlayServ settings window in UnityDeveloper
UserDeviceTokenGenerated and persisted by the SDK automaticallySDK
GameVersionSynchronised by the SDK from the Backoffice in the backgroundSDK
Client SDK VersionDetermined from the installed SDK packageSDK

Game Access Token is the environment-specific credential that identifies the game context and validates the connection. It is set in the PlayServ settings window in the Unity Editor and is scoped to a specific project environment — Development or Production.

See SDK Key Generation and Management for how to generate and rotate tokens.

note

PlayServ encapsulates networking primitives. In client code you react to session state and SDK APIs rather than managing low-level connect/disconnect.

Client-side initialisation​

Explicit initialisation in client code is not required. The SDK prepares internal components automatically and places the session into its initial Offline state.

The client signals readiness by calling:

await PlayServ.Ready();

If a UserToken is already stored on the device, it can be passed immediately to start the session in an authenticated state:

await PlayServ.Ready(UserToken);

This enters the handshake flow and allows the session to progress toward Active.

Server-side initialisation​

Before clients can join, the game server completes its own startup and explicitly calls PlayServ.Server.Ready().

[Server]
class GameServer
{
    GameServer()
    {
        InitializeAsync();
    }

    private async Task InitializeAsync()
    {
        await Something();
        PlayServ.Server.Ready();
    }
}
warning

If a server RPC class contains a call to Ready(), the code analyser expects that Ready() will be executed at least once. Until that happens, the server is not considered available.

Server startup configuration (optional)​

If server code requires configuration at startup, it can be stored as a Singleton Entity and fetched on server start via the data model API.

[Server]
class GameServer
{
    private readonly Task<Model> _configTask;

    public GameServer()
    {
        _configTask = LoadConfigurationAsync();
    }

    private async Task<Model> LoadConfigurationAsync()
    {
        return await PlayServ.GetServerConfig();
    }

    public async Task DoSomethingNext()
    {
        var config = await _configTask;
        config.StartingLevel; // 1
    }
}
note

Build version management on the server side is handled by the Version Module, without requiring manual reconciliation by the developer.

Next step​

After Ready(...) is called, the client enters the handshake flow. Continue with Proxy Module & Handshake to understand what happens next.

For related topics: