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ção | Padrão | Significado |
|---|---|---|
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. |
GameVersion | 1.0.0 | A versão da sua build, enviada como está. |
EnableAutomaticPlayerAuthentication | ligado | Faz o login de um Player anônimo ao conectar. |
AnonymousDisplayName | — | O nome de exibição de um Player anônimo recém-criado. |
PlayerSessionStore | PlayerPrefs | Onde a sessão do Player fica guardada entre uma execução e outra; veja Tokens e renovação. |
KeepAlivePingIntervalMs · KeepAlivePongTimeoutMs | 30000 · 10000 | O intervalo de verificação que a plataforma espera e quanto tempo aguardar pela resposta. |
TimeoutSeconds | 120 | O 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.
| Estado | Significado |
|---|---|
| Offline | Sem conexão: antes de Connect(), depois de Disconnect() ou depois de uma conexão que falhou. |
| Connecting | Abrindo a conexão. |
| Handshaking | Conectado, aguardando a plataforma aceitar o jogo e o Player. |
| Online | Pronto. Dados, Events e chamadas de Functions funcionam. |
| Reconnecting | A 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:
| Tentativa | Quando |
|---|---|
| Primeira tentativa | 2 segundos depois da queda. |
| Tentativas seguintes | Depois de 1 segundo, dobrando a cada vez até 30 segundos. |
| Cada tentativa | Expira depois de 30 segundos. |
| Desiste | Nunca 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
};
| Motivo | Quando | CanRetry |
|---|---|---|
SessionRevoked | A sessão foi revogada, por exemplo em Players. | Sim |
SessionMerged | A conta do Player foi mesclada em outra. | Sim |
RefreshRejected | A plataforma recusou renovar a sessão. | Sim |
ExpiredWithoutRefresh | O token expirou e não foi renovado a tempo. | Sim |
Banned | O Player foi banido. | Não |
CredentialRevoked | A 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.OnTransportError | Problemas de conexão: uma conexão recusada ou interrompida, ou a plataforma desconectando o jogo. |
PlayServ.OnError | Erros que não pertencem a uma chamada específica. Os erros de uma chamada voltam no resultado dela. |
| Código | Significado |
|---|---|
00001 | A 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. |
02003 | A plataforma desconectou o jogo. |
01002 | Esta versão do SDK não é mais suportada: atualize o SDK. |
01003 | Esta versão do jogo não é aceita: atualize o jogo. |
02001 | A plataforma atingiu o limite de conexões. Tente de novo mais tarde. |
02002 | A plataforma está em manutenção e recusa conexões. |
Próximos passos
- Login do usuário — faça o login de Players com Apple, Google, Facebook, Epic ou Steam
- Conectar o seu jogo — instale e configure o SDK
- Gerenciamento de API keys — a client key que o seu jogo usa
Atualizado em 19 de out. de 2026