Como usar o Pay Station em combinação com a autenticação PlayFab

Se você já implementou a autenticação de usuários no seu aplicativo usando o PlayFab, você pode gerar um token de pagamento no lado do PlayFab e então passá-lo ao lado do cliente no aplicativo para abrir a interface de pagamento.

Usando essa opção de integração, você deve implementar a lógica para determinar o país e moeda do usuário a ser usado para pagar pela compra de forma independente.

Fluxo de integração:

1. Crie um projeto.

1. Cadastre sua Conta de Distribuidor e crie um novo projeto. Você precisará do ID do projeto criado nas próximas etapas.

2. Configure um catálogo:
   • Crie um catálogo de itens no lado Xsolla. Você pode adicionar itens manualmente ou importá-los do Google Play PlayFab.
   • Implemente a obtenção e exibição do catálogo no lado do cliente do aplicativo usando o SDK.

3. Configure a compra de um item:
   • Crie um pedido com os dados do usuário e do item no lado do cliente no aplicativo usando o script PlayFab cloud.
   • Implemente a abertura da interface de pagamento no lado do cliente no seu aplicativo usando o SDK.

4. Configure o rastreamento do status do pedido.

Criar projeto

Cadastre sua Conta de Distribuidor

A Conta de Distribuidor é a ferramenta principal para configurar recursos da Xsolla, bem como trabalhar com análises e transações.

Os dados sobre a empresa e o seu aplicativo especificados durante o cadastro serão usados para criar um rascunho de contrato de licenciamento com a Xsolla e para gerar recomendações sobre soluções que sejam mais adequadas a você. Você pode alterar os dados mais tarde, mas o fornecimento dos dados corretos durante o cadastro acelera o processo de assinatura do contrato de licenciamento.

Para se cadastrar, vá para Conta de Distribuidor e crie um conta.

Crie um projeto na Conta de Distribuidor

Caso tenha múltiplos aplicativos, recomendamos criar um projeto separado para cada aplicativo. Com base nos dados especificados durante a criação do projeto, a Xsolla gera recomendações sobre as soluções mais adequadas a você.

Para criar um novo projeto:

1. Abra a Conta de Distribuidor.
2. No menu lateral, clique em Create project.

3. Insira o nome do seu projeto em inglês (obrigatório).

4. Escolha uma ou várias plataformas de lançamento do seu jogo (obrigatório).
5. Adicione um link para o seu jogo. Se o seu jogo ainda não tiver um site, adicione um link para a fonte que inclui informações sobre o jogo (obrigatório).
6. Escolha a engine do jogo.
7. Escolha suas opções de monetização ou o plano utilizado.
8. Especifique se o jogo já foi lançado. Se o jogo não tiver sido lançado, especifique a data de lançamento planejada.
9. Clique em Create project. Você verá uma página com os produtos Xsolla recomendados para você.

Durante o processo de integração, você precisa fornecer o ID do projeto, que pode ser encontrado na Conta de Distribuidor ao lado do nome do seu projeto.

Configure o catálogo

Crie itens a Conta de Distribuidor

Para adicionar itens virtuais com configurações básicas ao catálogo:

1. Abra seu projeto na Conta de Distribuidor.
2. Clique em Store no menu lateral.
3. No painel Virtual Items, clique em Connect.
4. Na lista suspensa, selecione Create item.

5. Defina as configurações básicas do item nos seguintes campos:
   • Image (opcional)
   • SKU (ID único do item)
   • Item name
   • Description (opcional)

6. Especifique o preço do item:
   1. Defina a opção Price in real currency como On.
   2. No campo Default currency, altere a moeda (opcional) e especifique o preço do item.
   3. Se você alterou a moeda no campo Default currency, selecione a mesma moeda no campo Price in real currency.

7. Altere o status do item para Available.

8. Clique em Create item.

Instale e configure o SDK

1. Baixe o Epic Games Launcher.
2. Crie um novo projeto Unreal Engine.

3. Baixe e instale o SDK:
   1. Para baixar e instalar o SDK do Unreal Engine Marketplace:
      1. Vá para a página do SDK no Unreal Engine Marketplace.
      2. Clique em Open in Launcher.

1. 1. 3. Vá para o Epic Games Launcher.

1. 1. 4. Clique em Install to Engine.
      5. Abra seu projeto Unreal Engine no Unreal Editor.
      6. Vá para a seção Settings > Plugins > Installed > Xsolla SDK. Marque a caixa Enabled e clique em Restart Now para salvar as configurações e recarregar o Unreal Editor.

1. 2. Para baixar e instalar o SDK do GitHub:
      1. Baixe o pacote com o SDK para a sua versão do engine.
      2. Descompacte o pacote.
      3. Mova a pasta do SDK para o diretório plugins na raíz do seu projeto Unreal Engine.

4. Vá para Settings > Project Settings > Plugins > Xsolla Settings > General.
5. No campo Project ID, especifique o ID de projeto, que pode ser encontrado na Conta de Distribuidor próximo ao nome do seu projeto.

Exibição do catálogo no lado do cliente no aplicativo

Crie uma classe para o item de catálogo

1. Em Content Browser, vá para o diretório Content.
2. Chame o menu contextual e selecione Blueprint Class.

3. Na seção All Classes, selecione Object e clique em Select.

4. Especifique StoreItemData como o nome da classe.
5. Abra o diagrama da classe criada.
6. No painel My Blueprint, clique em Add New e selecione Variable.
7. No painel Details:

1. 1. Especifique StoreItem no campo Variable Type.
   2. Marque as caixas Instance Editable e Expose on Spawn.

8. Salve e feche o diagrama StoreItemData.

Crie widget do item do catálogo

1. Em Content Browser, vá para o diretório Content. Chame o menu contextual e selecione User Interface > Widget Blueprint.
2. Especifique StoreItem como o nome do diagrama.
3. Abra o diagrama criado.
4. No painel Hierarchy, chame o menu contextual para o elemento CanvasPanel. Selecione Replace With > Overlay.

5. Posicione os primitivos de interface do painel Palette como exibido abaixo. Pela imagem de um item, título e descrição, marque a caixa Is Variable no painel Details.

6. Abra uma visualização Graph.
7. Clique em Class settings.
8. No painel Details, vá para Interfaces > Implemented Interfaces.
9. Clique em Add e selecione UserObjectListEntry. Essa é uma interface UE padrão que permite que a primitiva da interface implemente um comportamento normal para o elemento da lista.:

10. Adicione a lógica ao evento OnListItemObjectSet:
    1. No painel My Blueprint, chame o menu contextual para a seção Interfaces e selecione Implement event.

1. 2. Adicione nodos como exibido abaixo:

11. Salve e feche o diagrama StoreItem.

Crie o widget para a página de catálogo

1. Em Content Browser, vá para o diretório Content e selecione User Interface > Widget Blueprint no menu contextual.
2. Especifique WBP_Store como o nome do diagrama.
3. Abra o diagrama criado.
4. Na área de exibição de itens, adicione o elemento List View e nomei-o como StoreListView.

5. No painel Details, no campo Entry Widget Class, selecione a classe criada anteriormente para o item (StoreItem).
6. Vá para a visualização Graph.
7. Vincule o método SDK GetVirtualItems ao nodo EventConstruct, como exibido na figura abaixo.

8. No painel My Blueprint, clique em Add New e selecione Variable.
9. No painel Details:
   1. No campo Variable Type, selecioneString.
   2. Marque as caixas Instance Editable e Expose on Spawn.
   3. Especifique PlayFabId como nome.

10. Salve e feche o widget WBP_Store.
11. Adicione a lógica de exibição de diretório. Abaixo está um exemplo de implementação de diretório após uma autenticação de usuário bem-sucedida.

Configure a compra de itens

Para criar um pedido com dados de usuário e item no lado Xsolla, adicione uma função cloud ao projeto que utiliza a chamada de API Create payment token for purchase. Essa chamada retornará um token de pagamento, que é necessário para abrir a interface de pagamento e fazer uma compra.

Limitações:

• você precisa passar o país do usuário ou o endereço IP do usuário ao solicitar o token de pagamento.
• Se você não passar a moeda no token, ela é determinada pelo país.
• Se você passar a moeda no token, o usuário paga nessa concorrência.

Adicione o script cloud ao seu projeto

1. Abra o Visual Studio Code e vá para a aba Azure.
2. Na seção Workspace, clique no ícone + e selecione Create Function.

3. Selecione o novo diretório do projeto. Um menu para criar um novo projeto aparecerá com opções de configuração.

4. Especifique as novas configurações de projeto:
   1. Selecione um idioma para o seu projeto de função — JavaScript.
   2. Selecione um modelo de programação JavaScript — model V4.
   3. Selecione um modelo para a primeira função do seu projeto — HTTP trigger.
   4. Insira um nome de função — getXsollaPaymentToken.
   5. Selecione como você gostaria de abrir seu projeto — Open in current window.

1. Como resultado, o Visual Studio Code gerará um projeto JS e abrir o arquivo getXsollaPaymentToken.js gerado.

5. Modifique o arquivo getXsollaPaymentToken.js:

const { app } = require('@azure/functions');

const projectId = ""; //your xsolla project id from publisher account
const apiKey = ""; your api key from publisher account

app.http('getXsollaPaymentToken', {
    methods: ['POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {

      var body = await request.json();

      const userId = body.uid;
      const email = body.email;
      const sku = body.sku;
      const returnUrl = body.returnUrl;

        if (!userId) {
          return {status: 400, body: 'Request body is missing' };
        }

        const payload = {
            user: {
              id: {value: userId},
              name: {
                value: email
              },
              email: {
                value: email
              },
              country: {
                value: 'US',
                allow_modify: false
              }
            },
            purchase: {
              items: [
                {
                  sku: sku,
                  quantity: 1
                }
              ]
            },
            sandbox: true,
            settings: {
              language: 'en',
              currency: 'USD',
              return_url: returnUrl,
              ui: {
                theme: '63295aab2e47fab76f7708e3'
              }
            }
          }

        let url = "https://store.xsolla.com/api/v2/project/" + projectId.toString() + "/admin/payment/token";

        return fetch(
            url,
            {
                method: "POST",
                headers: {
                'Content-Type': 'application/json',
                Authorization: 'Basic ' + btoa(`${projectId}:${apiKey}`)
                },
                body: JSON.stringify(payload)
            },
            )
            .then(xsollaRes => {
            // Handle the response data
                if (xsollaRes.ok) {
                    return xsollaRes.json();
                } else {
                    return { status: 400, body: `HTTP request failed with error: ${xsollaRes.statusText}` };
                }
            })
            .then(data => {
                return { status: 200, body: JSON.stringify(data) };
            })
            .catch(error => {
                return { status: 501, body: `Error = ${error}` };
            });
        }
});

1. No script, especifique os valores das constantes:

1. • PROJECT_ID — O ID do projeto, que você pode encontrar na sua Conta de Distribuidor próximo ao nome do projeto.

1. • API_KEY — Chave API. É mostrada na Conta de Distribuidor apenas uma vez, durante a criação, e deve ser armazenada por você. Você pode criar uma nova chave na seguinte seção:
     • Company settings > API keys
     • Project settings > API keys

Depois de adicionar um script cloud, você pode testar a chamada da função getXsollaPaymentToken localmente.

Aplicar script cloud

1. No Visual Studio Code, vá para a seção Azure > Resources e clique no ícone +.
2. Selecione Create Function App in Azure como recurso. Um menu para criar um novo aplicativo aparecerá com opções de configuração.
3. Defina as configurações do aplicativo:

1. 1. Insira o nome para o novo aplicativo de função — XsollaFunctions.
   2. Selecione um stack runtime — .NET 8 Isolated.
   3. Selecione um local para novos recursos (você pode escolher qualquer opção).

1. Espere até o grupo de recursos ser criado.

4. Na lista de recursos, selecione o XsollaFunctions, chame o menu contextual e selecione Deply to Function App.

Depois de adicionar um script cloud, você pode testar a chamada da função getXsollaPaymentToken remotamente.

Testar sciprt cloud

Para testar o script cloud (localmente ou remotamente), chame a função getXsollaPaymentToken usando Postman ou outra ferramenta. Para fazer isso:

1. No Visual Studio Code, vá para a seção Azure > Workspace > Local Project > Functions e clique em Start debugging to update this list.
2. Chame o menu contextual para a função e selecione Copy Function Url. Ao testar localmente, o URL terá a seguinte aparência — http://localhost:7071/api/getXsollaPaymentToken. Ao testar remotamente — https://xsollafunctions.azurewebsites.net/api/GetXsollaPaymentToken.

3. Use o URL copiado para chamar a função com os parâmetros especificados. Para chamar uma função do Postman:
   1. Crie uma nova solicitação GET.
   2. Forneça o URL que você copiou no passo 2.
   3. Vá para a aba Body e especifique os parâmetros da solicitação.

Exemplo de corpo de solicitação:

{

 "FunctionArgument": {

   "uid": "1D384D9EF12EAB8B",

   "sku": "booster_max_1",

   "returnUrl": "https://login.xsolla.com/api/blank"

 }

}

4. Clique em Send. Na resposta, você deve receber o JSON com os seguintes parâmetros:
   • token — token de pagamento. Necessário para abrir a interface de pagamento.
   • order_id — ID do pedido criado. Necessário para rastrear o status do pedido.

Exemplo de corpo de resposta:

{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}

Função de cadastro para obter um token de pagamento no PlayFab

1. Abra seu projeto no PlayFab.
2. No menu lateral, clique em Automation.
3. Na seção Register New Cloud Script Function, clique em Register Function.
4. Insira o nome da função — GetXsollaPaymentToken.
5. Insira o URL da função que você copiou no Visual Code Studio (veja os passos 1-2 de Testar script cloud).

Crie um pedido e abra a interface de pagamento no projeto Unreal Engine

1. Abra seu projeto Unreal Engine.
2. Abra o widget WBP_Store.
3. No painel Hierarchy, selecione StoreListView.
4. No painel Details, clique no ícone + próximo ao evento On Clicked.

5. Vá para a visualização Graph.
6. Adicione a lógica para criar um objeto PlayfabJsonObject e passar os dados a ele para criar um pedido ao nodo OnItemClicked, como exibido abaixo:

7. Adicione um chamado ao método ExecuteFunction. Passe os parâmetros functionName = getXsollaPaymentToken e FunctionParameter = PlayfabJsonObject a ele.

Configure o rastreamento de status de pedidos

É necessário rastrear o status do pedido para garantir que o pagamento foi bem-sucedido e para conceder itens ao usuário.

Obter status do pedido no lado do cliente

Para rastrear as alterações no status do pedido, use o método SDK CheckPendingOrder na parte do cliente do aplicativo. Passe os seguintes parâmetros para o método:

• AuthToken — token de autorização do usuário
• OrderId — ID do pedido recebido da compra através do carrinho de compras, compra com um clique ou compra com moeda virtual
• SuccessCallback — retorno de chamada caso a ordem seja movida para o status concluído
• ErrorCallback — retorno de chamada no caso do servidor Xsolla retornar um erro

Para informações detalhadas sobre como o método funciona, consulte a seção Rastreamento de status do pedido.

Obter status do pedido no lado do servidor

Para configurar webhooks no lado Xsolla:

1. Abra seu projeto na Conta de Distribuidor.
2. Clique em Project settings no menu lateral e vá para a seção Webhooks.
3. No campo Webhook server, insira o URL ao qual a Xsolla enviará os webhooks.

4. Copie e salve o valor do campo Secret key. Essa chave é gerada por padrão e é usada para assinar webhooks. Se quiser alterá-la, clique no ícone de atualização.
5. Clique em Enable webhooks.