Pular para o conteúdo principal
Primeiros passos

Esta página ainda não foi traduzida: mostrando a versão em inglês.

Conexão e sessão

O seu jogo mantém uma única conexão ao vivo e autenticada com o PlayServ. PlayServ.Connect() faz o login do Player, abre a conexão e a mantém ativa: reconecta depois de uma queda e renova o token do Player sozinho. O seu código conecta uma vez, fica atento à perda da sessão e desconecta quando o jogo termina.

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

A instalação e a configuração do SDK estão em Conectar o seu jogo.


Do que o SDK precisa

Connect() lê a configuração que você fez na janela do PlayServ. Para configurar por código, chame PlayServ.Config(...) antes de Connect().

ConfiguraçãoPadrãoSignificado
ClientToken—A client key do Project (pk_…). Ela seleciona o Project e o Environment. Obrigatória.
BackendServerAddress—O endereço da plataforma, wss://platform.playserv.com/ws. Preenchido pela janela do PlayServ; obrigatório quando você configura por código.
GameVersion1.0.0A versão da sua build, enviada como está.
EnableAutomaticPlayerAuthenticationligadoFaz o login de um Player anônimo ao conectar.
AnonymousDisplayName—O nome de exibição de um Player anônimo recém-criado.
PlayerSessionStorePlayerPrefsOnde a sessão do Player fica guardada entre uma execução e outra; veja Tokens e renovação.
KeepAlivePingIntervalMs · KeepAlivePongTimeoutMs30000 · 10000O intervalo de verificação que a plataforma espera e quanto tempo aguardar pela resposta.
TimeoutSeconds120O tempo limite de uma requisição.
PlayServ.Config(new PlayServSettings
{
    ClientToken = "pk_...",
    GameVersion = "1.0.0",
    BackendServerAddress = "wss://platform.playserv.com/ws",
});

A client key escolhe o Environment

A client key define com qual Project e Environment o jogo fala. Um jogo que conecta, mas não vê nenhum dos seus dados, quase sempre está usando uma key de outro Environment. Client keys podem ir com segurança em uma build; server keys, nunca. Veja Gerenciamento de API keys.


Conectar

Login do Player

O SDK restaura o Player salvo neste aparelho ou cria um novo Player anônimo. Para fazer o login do Player com um provedor, veja Login de usuários.

Abertura da conexão

O SDK abre a conexão e se apresenta com a client key e o token do Player. A plataforma verifica os dois.

Online

Quando a plataforma aceita, o estado passa a Online, o keep-alive começa e Connect() retorna true. Se a conexão não puder ser aberta ou for recusada, ele retorna false, o estado volta a Offline e OnTransportError informa o motivo. Se o login do Player falhar antes disso, por exemplo porque a client key é inválida ou foi revogada, Connect() lança uma exceção.

Chame Connect() uma vez, a partir da thread principal. Chamar de novo enquanto uma conexão está em andamento retorna a mesma task; chamar com o jogo já online lança uma exceção.


Estados da conexão

PlayServ.State diz em que ponto a conexão está. Não há evento para mudanças de estado: leia o valor quando precisar.

EstadoSignificado
OfflineSem conexão: antes de Connect(), depois de Disconnect() ou depois de uma conexão que falhou.
ConnectingAbrindo a conexão.
HandshakingConectado, aguardando a plataforma aceitar o jogo e o Player.
OnlinePronto. Dados, Events e chamadas de Functions funcionam.
ReconnectingA conexão caiu e o SDK está restaurando-a.

Reconexão e keep-alive

O SDK verifica a conexão mais ou menos a cada 25 segundos. Se a plataforma não responder por 40 segundos, ou se a conexão cair, o SDK reconecta sozinho:

TentativaQuando
Primeira tentativa2 segundos depois da queda.
Tentativas seguintesDepois de 1 segundo, dobrando a cada vez até 30 segundos.
Cada tentativaExpira depois de 30 segundos.
DesisteNunca por conta própria: continua tentando até conseguir ou até você chamar Disconnect().

Cada reconexão faz o login de novo com um token novo. Se ela der certo em até 30 segundos depois da queda, as suas assinaturas de dados continuam de onde pararam. Se a plataforma encerrar a conexão de propósito (veja abaixo), o SDK não reconecta.


Tokens e renovação

O token de acesso do Player dura 15 minutos; o SDK o renova 90 segundos antes de expirar, no lugar, sem derrubar a conexão. A renovação em si vale por 30 dias: um Player que volta em até 30 dias depois da última sessão entra de novo direto.

O ID do Player e o token de renovação ficam salvos no aparelho, em PlayerPrefs por padrão, um por client key e plataforma. Uma build com outra client key não encontra o Player salvo e começa um novo. PlayerPrefs não é um armazenamento seguro: em um jogo em produção, defina PlayerSessionStore com a sua própria implementação de IPlayServPlayerSessionStore, que guarde esses dados em um lugar seguro.


Quando a sessão é perdida

A plataforma pode encerrar uma sessão: o Player foi banido, a sessão foi revogada ou as contas foram mescladas. A conexão é fechada, o SDK apaga a sessão salva e desconecta, e PlayServAuth.SessionLost é disparado uma vez.

PlayServAuth.SessionLost += info =>
{
    if (info.CanRetry) ShowSignIn();       // sign in again, then Connect()
    else ShowBlocked(info.Reason);         // don't retry
};
MotivoQuandoCanRetry
SessionRevokedA sessão foi revogada, por exemplo em Players.Sim
SessionMergedA conta do Player foi mesclada em outra.Sim
RefreshRejectedA plataforma recusou renovar a sessão.Sim
ExpiredWithoutRefreshO token expirou e não foi renovado a tempo.Sim
BannedO Player foi banido.Não
CredentialRevokedA client key usada pelo jogo foi revogada.Não

Não tente de novo após um banimento ou uma key revogada

Quando CanRetry é false, conectar de novo falha do mesmo jeito. Avise o Player e, no caso de uma key revogada, distribua uma build com uma key válida.

SessionLost não é disparado quando você mesmo faz o logout.


Erros

EventoÉ disparado para
PlayServ.OnTransportErrorProblemas de conexão: uma conexão recusada ou interrompida, ou a plataforma desconectando o jogo.
PlayServ.OnErrorErros que não pertencem a uma chamada específica. Os erros de uma chamada voltam no resultado dela.
CódigoSignificado
00001A plataforma recusou a conexão: a client key ou o token do Player é inválido, ou falta algo obrigatório.
02004É necessária uma sessão de Player, e o jogo conectou sem uma.
02003A plataforma desconectou o jogo.
01002Esta versão do SDK não é mais suportada: atualize o SDK.
01003Esta versão do jogo não é aceita: atualize o jogo.
02001A plataforma atingiu o limite de conexões. Tente de novo mais tarde.
02002A plataforma está em manutenção e recusa conexões.

Próximos passos

Atualizado em 19 de out. de 2026