Skip to main content
Getting Started

Not translated yet — showing English.

Connection & Session

Your game holds one live, authenticated connection to PlayServ. PlayServ.Connect() signs the player in, opens the connection and keeps it alive: it reconnects after a drop and refreshes the player's token on its own. Your code connects once, watches for a lost session, and disconnects when the game ends.

using System;
using Playserv.Wrapper;
using UnityEngine;

public sealed class PlayServBootstrap : MonoBehaviour
{
    async void Start()
    {
        PlayServAuth.SessionLost += info => Debug.LogWarning($"Session lost: {info.Reason}");
        PlayServ.OnTransportError += error => Debug.LogWarning(error);

        try
        {
            if (await PlayServ.Connect())
                Debug.Log($"Online as {PlayServAuth.PlayerId}");
        }
        catch (Exception e)   // signing in failed, for example a revoked client key
        {
            Debug.LogError(e.Message);
        }
    }

    void OnDestroy() => PlayServ.Disconnect();
}

Setting up the SDK and its configuration is covered in Connect Your Game.


What the SDK needs

Connect() reads the configuration you set up in the PlayServ window. To configure it from code instead, call PlayServ.Config(...) before Connect().

SettingDefaultMeaning
ClientToken—The project's client key (pk_…). It selects the project and the environment. Required.
BackendServerAddress—The platform's address, wss://platform.playserv.com/ws. Filled in by the PlayServ window; required when you configure from code.
GameVersion1.0.0Your build's version, sent as is.
EnableAutomaticPlayerAuthenticationonSign in an anonymous player on connect.
AnonymousDisplayName—The display name of a newly created anonymous player.
PlayerSessionStorePlayerPrefsWhere the player's session is kept between launches, see Tokens and refresh.
KeepAlivePingIntervalMs · KeepAlivePongTimeoutMs30000 · 10000The check interval the platform expects, and how long to wait for an answer.
TimeoutSeconds120The timeout of a request.
PlayServ.Config(new PlayServSettings
{
    ClientToken = "pk_...",
    GameVersion = "1.0.0",
    BackendServerAddress = "wss://platform.playserv.com/ws",
});

The client key picks the environment

The client key decides which project and environment the game talks to. A game that connects but sees none of your data is usually using a key of another environment. Client keys are safe to ship in a build; server keys never are, see API Key Management.


Connect

Sign in the player

The SDK restores the player saved on this device, or creates a new anonymous player. To sign the player in with a provider, see User Login.

Open the connection

The SDK opens the connection and introduces itself with the client key and the player's token. The platform checks both.

Go online

When the platform accepts, the state becomes Online, keep-alive starts, and Connect() returns true. If the connection can't be opened or is refused, it returns false, the state goes back to Offline, and OnTransportError says why. If signing the player in fails before that, for example because the client key isn't valid or was revoked, Connect() throws.

Call Connect() once, from the main thread. Calling it again while a connect is in progress returns the same task; calling it while already online throws.


Connection states

PlayServ.State tells you where the connection is. There is no event for state changes: read it when you need it.

StateMeaning
OfflineNot connected: before Connect(), after Disconnect(), or after a failed connect.
ConnectingOpening the connection.
HandshakingConnected, waiting for the platform to accept the game and the player.
OnlineReady. Data, events and function calls work.
ReconnectingThe connection dropped and the SDK is restoring it.

Reconnects and keep-alive

The SDK checks the connection about every 25 seconds. If the platform doesn't answer for 40 seconds, or the connection drops, the SDK reconnects on its own:

AttemptWhen
First attempt2 seconds after the drop.
Next attemptsAfter 1 second, doubling each time up to 30 seconds.
Each attemptTimes out after 30 seconds.
Gives upNever on its own: it keeps trying until it succeeds or you call Disconnect().

Each reconnect signs in again with a fresh token. If it succeeds within 30 seconds of the drop, your data subscriptions are picked up where they left off. If the platform ends the connection on purpose, see below, the SDK doesn't reconnect.


Tokens and refresh

The player's access token lasts 15 minutes; the SDK renews it 90 seconds before it expires, in place, without dropping the connection. The renewal itself is good for 30 days: a player who comes back within 30 days of their last session is signed straight back in.

The player's ID and the renewal token are saved on the device, in PlayerPrefs by default, once per client key and platform. A build with a different client key doesn't find the saved player and starts a new one. PlayerPrefs isn't secure storage: for a production game, set PlayerSessionStore to your own IPlayServPlayerSessionStore that keeps them somewhere safe.


When the session is lost

The platform can end a session: the player was banned, the session was revoked, or the accounts were merged. The connection is closed, the SDK clears the saved session and disconnects, and PlayServAuth.SessionLost fires once.

PlayServAuth.SessionLost += info =>
{
    if (info.CanRetry) ShowSignIn();       // sign in again, then Connect()
    else ShowBlocked(info.Reason);         // don't retry
};
ReasonWhenCanRetry
SessionRevokedThe session was revoked, for example in Players.Yes
SessionMergedThe player's account was merged into another one.Yes
RefreshRejectedThe platform refused to renew the session.Yes
ExpiredWithoutRefreshThe token expired and wasn't renewed in time.Yes
BannedThe player was banned.No
CredentialRevokedThe client key the game uses was revoked.No

Don't retry a ban or a revoked key

When CanRetry is false, connecting again fails the same way. Tell the player, and for a revoked key, ship a build with a working one.

SessionLost doesn't fire when you sign out yourself.


Errors

EventFires for
PlayServ.OnTransportErrorConnection problems: a refused or broken connection, or the platform disconnecting the game.
PlayServ.OnErrorErrors that don't belong to a particular call. Errors of a call come back with that call's result.
CodeMeaning
00001The platform refused the connection: the client key or the player's token isn't valid, or something required is missing.
02004A player session is required, and the game connected without one.
02003The platform disconnected the game.
01002This SDK version is no longer supported: update the SDK.
01003This game version is not accepted: update the game.
02001The platform has reached its connection limit. Try again later.
02002The platform is in maintenance and refuses connections.

Next steps

Last updated on 19 Oct 2026