Integração fluída da web com o jogo

Como funciona

A integração fluída da web ao jogo permite que você configure o envio de dados do seu site para o jogo nos parâmetros URL. Você pode transmitir um token de autorização do usuário, dados de campanha de marketing ou outras informações.

Fluxos de usuários

Existem os seguintes cenários do usuário ao implementar a integração fluída da web ao jogo:

• Clicar em um link para baixar o instalador do inicializador a partir do site.
• Clicar em um link ao inicializador a partir do site.
• Inicializar o jogo a partir do inicializador.

Quando um usuário clica em um link para baixar o instalador do inicializador a partir do site:

1. O usuário abre o site.
2. O usuário segue o link ao instalador do inicializador.
3. O usuário baixa o instalador do inicializador com o link que contém uma senha única.
4. O usuário instala o inicializador.
5. O inicializador recebe o valor do parâmetro common_payload através de uma senha única.
6. O usuário clica no botão Play no inicializador.
7. O inicialziador confere a presença e validade do parâmetro common_payload:
   • Se a verificação for bem-sucedida, o inicializador inicia o jogo com os argumentos obtidos no parâmetro common_payload.
   • Se a verificação não for bem-sucedida:
     • Se o URL do site estiver configurado na Conta de Distribuidor dentro do nome do arquivo executável, o inicializador redireciona o usuário para esse endereço.
     • Se o URL do site não estiver configurado na Conta de Distribuidor dentro do nome do arquivo executável — o inicializador inicia o jogo sem o argumento common_payload.

Quando um usuário clica em um link ao inicializador a partir do site e o inicializador já foi instalado, o seguinte fluxo ocorre:

1. O usuário abre o site.
2. O usuário clica em um link que leva ao inicializador.
3. O inicializador salva o valor dos parâmetros payload, common_payload e expires_jn no URL.
4. O usuário clica em Play no inicializador.
5. O inicializador confere a presença e validade dos parâmetros payload e common_payload:
   • Se a verificação for bem-sucedida, o inicializador inicia o jogo com os argumentos obtidos nos parâmetros payload e common_payload.
   • Se a verificação não for bem-sucedida:
     • Se o URL do site estiver configurado na Conta de Distribuidor dentro do nome do arquivo executável, o inicializador redireciona o usuário para esse endereço.
     • Se o URL do site não estiver configurado na Conta de Distribuidor dentro do nome do arquivo executável — o inicializador inicia o jogo sem os argumentos payload e common_payload.

Quando um usuário inicia o jogo a partir do inicializador, o seguinte fluxo ocorre:

1. O usuário abre o inicializador.
2. O usuário clica em Play no inicializador.
3. O inicializador confere a presença e validade dos parâmetros payload e common_payload:
   • Se a verificação for bem-sucedida, o inicializador inicia o jogo com os argumentos obtidos a partir dos parâmetros payload e common_payload.
   • Se a verificação não for bem-sucedida:
     • Se um URL foi especificado nas configurações da Conta de Distribuidor, o inicializador redireciona o usuário para o URL.
     • Se o URL do site não estiver configurado na Conta de Distribuidor dentro do nome do arquivo executável, o inicializador redireciona o jogo para esse endereço — o inicializador inicia o jogo sem os argumentos payload e common_payload.

Como obtê-lo

Para configurar a integração fluída da web com o jogo:

1. Defina as configurações na Conta de Distribuidor.
2. Adicione um link para o seu site.
3. Implemente o processamento dos dados recebidos no parâmetro de carga no lado do jogo.

Definição de configurações na Conta de Distribuidor

1. Abra seu projeto na Conta de Distribuidor e acesse a seção Distribution > Launcher.
2. Encontre o inicializador no painel e selecione Editar inicializador.
3. Na seção Jogos, selecione Configurar à direita do seu jogo.
4. Vá para a seção Compilações.
5. Vá para a aba Arquivos executáveis.
6. Adicione o argumento --x_payload_url ao campo Nome do arquivo executável para cada sistema operacional. No valor do argumento, passe o URL do site onde o link ou botão se encontra. O valor deve ser codificado usando o padrão Base64.

Por exemplo, se o nome do arquivo executável for game.exe e o URL do site do jogo for http://example.com/start_play, insira game.exe –x_payload_url aHR0cDovL2V4YW1wbGUuY29tL3N0YXJ0X3BsYXk= no campo Executable file.

Adição de um link para o site

Adicione um link ou botão ao seu site que abrirá o URL no formato xl-<launcher-id>://game/<game-id>?payload=<payload>&common_payload=<common_payload>&expires_in=<expires_in>, onde:

• <launcher-id> e <game-id> — são identificadores do inicializador e do jogo que você pode encontrar no URL da sua Conta de Distribuidor: https://publisher.xsolla.com/<merchant-id>/projects/<project-id>/new-launcher/<launcher-id>/game/<game-id>.
• <payload> — os dados que devem ser passados ao jogo.
• <common_payload> — os dados do usuário que devem ser passados ao inicializador, que é o mesmo para todos os jogos.
• <expires_in> — a validade dos dados passados nos parâmetros payload e common_payload no formato Unix time em milissegundos.

 1function getAuthToken() {
 2    return 'YOUR DATA HERE';
 3}
 4
 5function getDeeplink(launcherID, gameID) {
 6    const encodedPayload = btoa(getAuthToken());
 7    const expiresIn = new Date();
 8    expiresIn.setHours(expiresIn.getHours() + 1); // Payload data will be fresh for 1 hour
 9 return `xl-${launcherID}://game/${gameID}?payload=${encodedPayload}&expires_in=${expiresIn.getTime()}`;
10}
11
12// Put that `href` to button or link address
13const href = getDeeplink(123, 4567);

Integração do lado do jogo

O inicializado passa os dados recebidos no parâmetro payload como o valor do argumento –xsolla-payload da linha de comando, como demonstrado no exemplo abaixo. Ele também confere a presença e validade dos dados passados no parâmetro common_payload e os passa como o valor do argumento –xsolla-common-payload da linha de comando, como demonstrado no exemplo abaixo.

Exemplo de iniciar um jogo quando os dados são criptografados usando Base64:

1game.exe ---xsolla-payload <payload> --xsolla-common-payload <common_payload> WU9VUiBEQVRBIEhFUkU=