Visão geral
Notificações de jogo Steam é um sistema para a transmissão de notificações off-line a usuários para jogos com partidas multijogadoras assíncronas, como Xadrez.
O propósito da API é notificar usuários de que há uma ação pendente em uma sessão de partida em andamento. No exemplo de Xadrez, o estado da sessão é atualizado após o movimento de cada jogador. O Steam então enviará notificações aos usuários com base no estado da sessão de partida para alertá-los quando for a vez de jogarem.
Responsabilidades do jogo
Um jogo off-line típico cuida de uma sessão de partida, atualizando a situação de cada jogador com estados que, por sua vez, enviarão uma notificação ao usuário para que saibam que precisam iniciar o jogo e realizar uma ação. Ao iniciar e realizar as ações no jogo, espera-se que este atualize a sessão de partida novamente com estados atualizados para todos os usuários na sessão.
Responsabilidades do Steam
O Steam cuidará da notificação de usuários em uma sessão de partida com base nos estados informados pelo jogo e as configurações específicas selecionadas pelo usuário para o jogo. Um alerta será exibido no cliente Steam e no navegador quando houver uma ação pendente para um jogo.
Requisitos
A API de notificações de jogo é oferecida por métodos da Web API e requer uma chave de distribuidora válida. As chamadas aos métodos da Web API devem originar de um servidor hospedado separado do cliente do jogo — a chave de distribuidora não deve ser integrada a qualquer código do cliente do jogo.
Autenticação e contas externas
Para chamar as APIs de notificações de jogo, é necessário primeiro estabelecer a identidade do usuário Steam atual do jogo. É possível fazê-lo de duas formas: o cliente do jogo pode gerar um ticket de sessão para autenticação e passá-lo de volta ao servidor, ou um jogo baseado na web pode verificar o usuário com OpenID. Instruções para tal estão disponíveis
aqui. É importante não confiar na identidade do usuário nas mensagens enviadas diretamente do cliente do jogo para o servidor, por ser possível modificá-las.
Para jogos que usam contas externas, use as instruções acima, mas armazene o ID Steam do usuário no sistema.
API de notificações de jogo
Visão geral técnica
A API de notificações de jogo é escrita e exposta por Web APIs e requer 4 parâmetros em cada método:
- appid (o ID de aplicativo do jogo);
- format (o formato do resultado. Recomendamos valor de retorno json);
- input_json (os parâmetros exigidos por um método, codificados em um JSON);
- key (a chave de distribuidora a passar com cada chamada).
A API retornará um código de estado HTTP 200 se bem-sucedida, com detalhes no corpo da mensagem (se aplicável).
Valores constantes
UserState
Uma string definida como uma das abaixo:
- waiting — O usuário está aguardando outros jogadores e não está bloqueando nenhuma ação. Nenhuma notificação será enviada ao usuário por estar aguardando uma ação de outro usuário;
- ready — O usuário está pronto — a sessão de partida está aguardando uma resposta do usuário. Uma notificação será enviada ao usuário até este estado ser removido;
- done — A partida foi concluída para o usuário. O usuário será notificado da conclusão da partida, mas nenhuma ação é exigida.
Estruturas de dados (JSON)
Todas as estruturas de dados são representadas no formato JSON.
Variable
{
"key": "nome_da_chave", // string
"value": "valor_da_chave" // string
}
LocalizedText
{
"token": "valor", // string mapeada a um token de tradução
"variables":
[
// Vetor de objetos "Variable" (descritos acima)
]
}
UserStatus
{
"steamid": "76561197960265729", // uint64
"state": // Uma das constantes "UserState" (descritas acima),
"title": // Um objeto "LocalizedText" (descrito acima),
"message": // Um objeto "LocalizedText" (descrito acima)
}
Session
{
"sessionid": "1", // uint64
"title": // Um objeto "LocalizedText" (descrito acima),
"time_created": "100000", // // Horário no formato de Era Unix (segundos desde 1º de janeiro de 1970)
"time_updated": "200000", // // Horário no formato de Era Unix (segundos desde 1º de janeiro de 1970)
// Valor de 64 bits informado pelo desenvolvedor quando a sessão é criada e que será passado ao jogo na sua inicialização.
// Use-o para vincular o objeto de sessão ao objeto no seu backend. Não é usado internamente pelo Steam.
"context": "31415926",
"user_status":
[
// Vetor de objetos "UserStatus" (descritos acima)
]
}
RequestedSession
{
"sessionid": "1", // uint64
"include_all_user_messages": "0" // bool
}
APIs comuns disponíveis
Consulte
IGameNotificationsService para ver a lista completa.
Iniciar sessões de partida específicas
Usuários terão como ver todas as sessões de partida ativas na respectiva página de perfil na Comunidade Steam. Juntamente com o estado da partida, há um botão para que o Steam inicie o jogo com parâmetros de inicialização específicos que definem a sessão de partida. Quando um jogo é iniciado dessa forma, um parâmetro de inicialização "_sessionid" será passado ao jogo. Para recuperá-lo, use a função
ISteamApps::GetLaunchQueryParam.
Exemplo:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Um jogo que permite carregar uma partida diretamente desta forma deve chamar a interface na inicialização do jogo, determinar se a string de ID de sessão está presente e válida para o usuário atual e então, carregar a partida.
Localização
A localização é informada pelo desenvolvedor do jogo por uma ferramenta de localização que é parte da configuração do aplicativo. Você é responsável por definir a tradução de cada idioma para cada string informada na ferramenta de localização. As strings que não estiverem traduzidas no idioma do usuário serão exibidas em inglês.
A API de notificações de jogo permite a tradução das seguintes propriedades:
Cada
LocalizedText é composto de dois componentes:
Um token é uma chave que começa com o símbolo "#" e representa uma string localizada em diferentes idiomas por meio da ferramenta de localização da configuração de aplicativo. Um único token pode conter várias variáveis, que são substituídas em tempo de execução dependendo do contexto da partida no momento da geração do texto. Um exemplo seria:
#InvitationText = "{{user}} has invited you to play a game of Chess."No exemplo acima, a tradução em inglês para #InvitationText contém uma única variável, chamada "user". Quando quiser exibir essa mensagem de texto a um usuário quando "SteamUserName" o convidar para uma partida, atualize o objeto LocalizationText com as seguintes propriedades:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Quando o usuário vir o estado, esta será a mensagem (no seu idioma local — exemplo aqui em português): "Michael convidou você para uma partida de xadrez.".
Os tokens de tradução podem ser enviados na página de configurações do Steamworks para o aplicativo > aba "Comunidade" > seção "Notificações assíncronas".
Cada idioma pode ser enviado em um arquivo VDF separado, semelhante a:
"lang"
{
"Language" "brazilian"
"Tokens"
{
"TheNameOfTheToken" "O texto traduzido associado ao token"
"TheNameOfAnotherToken" "O texto traduzido associado ao segundo token"
}
}
Também é possível enviar os tokens para todos os idiomas em um único arquivo, no formato:
"lang"
{
"english"
{
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
"brazilian"
{
"Tokens"
{
"TheNameOfTheToken" "O texto traduzido associado ao token"
"TheNameOfAnotherToken" "O texto traduzido associado ao segundo token"
}
}
}
