Vista geral
O sistema de notificações de jogos do Steam foi concebido para entregar notificações a utilizadores offline acerca de jogos multijogador com jogabilidade assíncrona, como um jogo de xadrez.
O objetivo desta API é permitir que os utilizadores sejam notificados quando é necessário que realizem uma ação para que a sessão de uma partida possa continuar. No exemplo do jogo de xadrez, o estado da sessão é atualizado depois de cada jogador mover uma peça. De seguida, o Steam irá enviar notificações para os utilizadores, com base no estado da sessão da partida, para os alertar quando for a vez de jogarem.
Responsabilidades do jogo
Um típico jogo offline deve gerir a sessão de uma partida e atualizar a situação de cada utilizador com estados que irão, por sua vez, enviar uma notificação ao utilizador para que saiba quando precisa de entrar no jogo para realizar uma ação. Assim que as ações forem realizadas, espera-se que o jogo atualize a sessão da partida novamente com estados atualizados para todos os utilizadores na sessão.
Responsabilidades do Steam
O Steam fará a gestão da notificação de utilizadores na sessão de partidas com base nos estados fornecidos pelo jogo e nas definições específicas selecionadas pelo utilizador para o jogo. Será apresentado ao utilizador um alerta na aplicação Steam e no browser quando for necessário realizar uma ação num jogo.
Requisitos
A API de notificações de jogos é fornecida por métodos da Web API e requer uma chave de editora válida. As chamadas aos métodos da Web API devem originar de um servidor hospedado separado do cliente do jogo; a chave de editora não deve estar incluída em nenhum código do cliente do jogo.
Autenticação de contas externas
Para chamar as APIs de notificações de jogos, deve primeiro estabelecer a identidade do utilizador do Steam atual do seu jogo. Pode fazê-lo de duas formas: um cliente do jogo pode gerar um ticket de sessão para autenticação e passá-lo de volta ao seu servidor, ou um jogo baseado na web pode confirmar o utilizador via OpenID. Instruções para tal estão disponíveis no artigo
Associação de contas de serviços de terceiros a contas Steam. É importante que não confie na identidade de utilizadores em mensagens enviadas diretamente do cliente do jogo para o servidor, pois estas mensagens podem ser manipuladas.
No caso de jogos que usam contas externas, use as instruções acima mas armazene o SteamID do utilizador no seu sistema.
API de notificações de jogos
Vista geral técnica
A API de notificações de jogos é escrita e exposta por Web APIs e requer 4 parâmetros passados em cada método:
- appid (o ID de aplicação do seu jogo).
- format (o formato do resultado. Recomenamos json como o valor de retorno).
- input_json (codificação em json de todos os parâmetros necessários para um método).
- key (a chave de editora a passar com cada chamada).
A API irá retornar um código de estado HTTP 200 se a operação for bem-sucedida, com detalhes no corpo da mensagem (caso aplicável).
Valores constantes
UserState
Uma string definida como uma das seguintes:
- waiting – O utilizador está a aguardar por outros jogadores e não está a bloquear nenhuma ação. Não será enviada nenhuma notificação para o utilizador, por estar à espera que algo aconteça.
- ready – O utilizador está pronto e a sessão da partida está à espera de uma resposta do utilizador. Uma notificação será enviada para o utilizador até que este estado seja removido.
- done – A partida terminou para este utilizador, que será notificado acerca da conclusão da partida. Não é necessária nenhuma ação por parte do utilizador.
Estruturas de dados (JSON)
Todas as estruturas de dados são representadas no formato JSON.
Variable
{
"key": "nome", // string
"value": "valor" // string
}
LocalizedText
{
"token": "value", // string mapeada para um token de tradução
"variables":
[
// Array de "Variable" (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" (acima),
"time_created": "100000", // Data e hora no formato de Era Unix (segundos desde 1 de janeiro de 1970).
"time_updated": "200000", // Data e hora no formato de Era Unix (segundos desde 1 de janeiro de 1970).
// Valor de 64 bits fornecido pelo developer quando a sessão é criada, que será passado ao jogo quando for iniciado.
// Permite associar facilmente o objeto da sessão ao seu backend. Não é usado internamente pelo Steam.
"context": "31415926",
"user_status":
[
// Array 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 partidas especificas
Os utilizadores poderão ver todas as sessões de partidas ativas na respetiva página de perfil na Comunidade Steam. Além do estado da partida, é exibido um botão para que o Steam inicie o jogo com parâmetros de arranque específicos que definem a sessão da partida. Quando um jogo é iniciado desta forma, o parâmetro de arranque "_sessionid" é enviado para o jogo. Pode receber este parâmetro ao usar
ISteamApps::GetLaunchQueryParam.
Exemplo:
const char *pchSessionID = ISteamApps()->GetLaunchQueryParam("_sessionid");
Um jogo que pode ser iniciado diretamente numa partida desta forma deve chamar a interface no arranque do jogo, determinar se a string de ID de sessão está presente e válida para o utilizador atual e, por fim, carregar a partida.
Tradução
A tradução é fornecida pelo developer do jogo através de uma ferramenta de tradução pertencente à configuração da aplicação. Cabe a si definir a tradução em cada idioma para todas as strings introduzidas na ferramenta de tradução. As strings que não estiverem traduzidas no idioma do jogador irão aparecer em inglês.
A API de notificações de jogos 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 traduzida em idiomas diferentes através da ferramenta de tradução na configuração da sua aplicação. Um único token pode conter várias instâncias variáveis que podem ser substituídas durante a execução com base no contexto da partida quando o texto estiver para ser gerado. Um exemplo seria:
#InvitationText = "{{user}} has invited you to play a game of Chess."No exemplo acima, a versão inglesa de #InvitationText contém uma única variável, chamada "user". Sempre que quiser apresentar esta mensagem de texto a um utilizador quando "SteamUserName" o convidar para uma partida, terá de atualizar o objeto LocalizationText com as seguintes propriedades:
"message":
{
"token": "#InvitationText",
"variables":
[
{ "key": "user", "value": "Michael" }
]
}
Quando o jogador ver este estado, irá depois ver esta mensagem (no respetivo idioma): "Michael has invited you to play a game of Chess."
Tokens de tradução podem ser enviados na secção "Tradução de notificações assíncronas" do separador "Comunidade" na página de definições do Steamworks para a aplicação.
Cada idioma pode ser enviado individualmente em ficheiros VDF no seguinte formato:
"lang"
{
"Language" "english"
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
Também tem a opção de enviar os tokens de todos os idiomas num só ficheiro, no seguinte formato:
"lang"
{
"english"
{
"Tokens"
{
"TheNameOfTheToken" "The localized text associated with the token"
"TheNameOfAnotherToken" "The localized text associated with the second token"
}
}
"portuguese"
{
"Tokens"
{
"TheNameOfTheToken" "O texto traduzido associado ao token"
"TheNameOfAnotherToken" "O texto traduzido associado ao segundo token"
}
}
}
