SDK para Unity / Como usar o Pay Station em combinação com a autenticação PlayFab
  Voltar aos Documentos

SDK para Unity

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.

  1. 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.

  1. 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.

  1. Configure o rastreamento do status do pedido.

Aviso

Para concluir a integração e começar a aceitar pagamentos reais, você precisará assinar um contrato de licenciamento com a Xsolla.

Você pode assinar o contrato de licenciamento em qualquer etapa da integração, mas tenha em mente que o processo de análise pode levar até 3 dias úteis.

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.

Observação

A senha da Conta de Distribuidor pode conter letras latinas, números e caracteres especiais e deve conter pelo menos:

  • 8 caracteres
  • um dígito
  • uma letra maiúscula
  • uma letra minúscula

Para garantir a segurança da senha, recomendamos:

  • alterar sua senha pelo menos uma vez a cada 90 dias
  • usar uma nova senha diferente de suas últimas 4 senhas
  • usar uma senha única que não corresponda a outras senhas que você usa
  • não armazenar sua senha num lugar de fácil acesso
  • usar gerenciadores de senha para armazenar a sua senha

A Conta de Distribuidor usa autenticação em duas etapas e envia um código de confirmação a cada tentativa de autenticação.

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.

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

Observação
Após criar o projeto, será possível adicionar idiomas adicionais e nomes de projeto traduzidos na seção Project settings.

  1. Escolha uma ou várias plataformas de lançamento do seu jogo (obrigatório).
  2. 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).
  3. Escolha a engine do jogo.
  4. Escolha suas opções de monetização ou o plano utilizado.
  5. Especifique se o jogo já foi lançado. Se o jogo não tiver sido lançado, especifique a data de lançamento planejada.
  6. 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

Aviso

Você precisa criar um catálogo no lado da Xsolla. Você pode adicionar itens manualmente ou importá-los pelo Google Play ou PlayFab. Ao importar pelo Google Play, você poderá importar no máximo 100 itens por vez.

Essas instruções fornecem etapas para a configuração básica de um item virtual. Mais tarde, você poderá adicionar outros itens ao catálogo (moeda virtual, conjuntos, chaves de jogo), criar grupos de itens, configurar campanhas promocionais, preços regionais, etc.

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.

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

  1. 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.

Observação
Para garantir que as chamadas de API da obtenção de catálogo estejam funcionando corretamente, certifique-se de que a moeda padrão e a lista de moedas na qual os preços são especificados correspondam a todos os itens.

  1. Altere o status do item para Available.

  1. Clique em Create item.

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

  1. Baixe o SDK do CDN ou GitHub.
  2. Descompacte o pacote.
  3. No menu principal, vá paraq Assets > Import Package > Custom Package e selecione o SDK baixado.
  4. No menu principal, vá para Window > Xsolla > Edit Settings.
  5. Vá para o painel Inspector. No campo Project ID, especifique o ID do projeto que pode ser encontrado na Conta de Distribuidor próxima ao nome do seu projeto.

  1. No lado do cliente no aplicativo, adicione a interface para exibir o catálogo de produtos.
  2. Implemente a solicitação de catálogos de itens pelos servidores Xsolla.

Observação

Para obter uma lista de itens virtuais, use o método SDK GetCatalog. Você também pode obter informações sobre os itens de catálogo usando outros métodos SDK.

Para um tutorial passo a passo sobre criar uma página de catálogo, consulte Exibição do catálogo de itens.

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 Criar token de pagamento para compra. 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.

Observação

O projeto PlayFab deve ser criado e o PlayFab SDK já deve estar integrado no seu projeto Unity.

Os Cloud Scripts PlayFab não oferecem suporte direto a funções com gatilhos HTTP, portanto, são usadas funções do Azure para implementar o recebimento de webhooks.

Para começar com as funções Azure, crie uma conta Azure e prepare seu ambiente de desenvolvimento. Essa instrução descreve os passos no ambiente de desenvolvimento com as seguintes configurações:

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.

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

  1. Especifique as novas configurações de projeto:
    1. Selecione um idioma para o seu projeto de função — C#.
    2. Selecione um runtime .NET — .NET 8.0 Isolated (LTS).
    3. Selecione um modelo para a primeira função do seu projeto — HTTP trigger.
    4. Insira um nome de função — GetXsollaPaymentToken.
    5. Insira um namespace — My.Functions.
    6. Selecione um nível de autorização — Anonymous.
    7. Selecione como você gostaria de abrir seu projeto — Open in current window.

  1. Como resultado, o Visual Studio Code gerará um projeto C# e abrir o arquivo GetXsollaPaymentToken.cs gerado.

  1. Modifique o arquivo GetXsollaPaymentToken.cs:

Copy
Full screen
Small screen
using System.Text;
using System.Net.Http.Headers;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

namespace My.Function
{
    public class GetXsollaPaymentToken
    {
        private readonly ILogger<GetXsollaPaymentToken> _logger;

        private const int PROJECT_ID = ""; // Your Xsolla project ID
        private const string API_KEY = ""; // Your Xsolla API key

        public GetXsollaPaymentToken(ILogger<GetXsollaPaymentToken> logger)
        {
            _logger = logger;
        }

        [Function("GetXsollaPaymentToken")]
        public async Task<IActionResult> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req)
        {
            _logger.LogInformation("GetXsollaPaymentToken function processed a request.");

            // Reading the request body
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            _logger.LogInformation("Request body: " + requestBody);

            // Deserializing request body JSON
            dynamic data = JsonConvert.DeserializeObject(requestBody);

            // Extracting necessary data from JSON
            string uid = data.FunctionArgument.uid;
            string sku = data.FunctionArgument.sku;
            string returnUrl = data.FunctionArgument.returnUrl;

            // Creating payload for Xsolla API
            var payload = new
            {
                user = new
                {
                    id = new { value = uid },
                    country = new { value = "US", allow_modify = false }
                },
                purchase = new
                {
                    items = new[]
                    {
                        new { sku = sku, quantity = 1 }
                    }
                },
                sandbox = true,
                settings = new
                {
                    language = "en",
                    currency = "USD",
                    return_url = returnUrl,
                    ui = new { theme = "63295aab2e47fab76f7708e3" }
                }
            };

            // Constructing Xsolla API URL
            string url = $"https://store.xsolla.com/api/v3/project/{PROJECT_ID}/admin/payment/token";

            // Sending request to Xsolla API
            using (HttpClient client = new HttpClient())
            {
                // Adding authorization header
                string headerValue = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{PROJECT_ID}:{API_KEY}"));
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", headerValue);

                // Serializing payload to JSON
                var jsonPayload = JsonConvert.SerializeObject(payload);
                var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

                // Making POST request to Xsolla API
                var xsollaRes = await client.PostAsync(url, content);

                // Checking response from Xsolla API
                if (xsollaRes.IsSuccessStatusCode)
                {
                    // Reading successful response content
                    string responseContent = await xsollaRes.Content.ReadAsStringAsync();
                    return new OkObjectResult(responseContent);
                }
                else
                {
                    // Returning status code in case of failure
                    return new StatusCodeResult((int)xsollaRes.StatusCode);
                }
            }
        }
    }
}

  1. No script, especifique os valores das constantes:

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

    • 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. 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.

  1. 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.

  1. 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:

Copy
Full screen
Small screen
{

 "FunctionArgument": {

   "uid": "1D384D9EF12EAB8B",

   "sku": "booster_max_1",

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

 }

}
Observação
Você pode especificar qualquer valor para o ID de usuário (uid). Como o SKU de item (sku), especifique o SKU do item virtual que você adicionou na Conta de Distribuidor anteriormente.

  1. 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:

Copy
Full screen
Small screen
{"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 Unity

  1. Abra seu projeto Unity.
  2. Crie o script XsollaPlayfabSample.cs com o seguinte conteúdo:

Copy
Full screen
Small screen
using System;
using PlayFab;
using PlayFab.ClientModels;
using PlayFab.CloudScriptModels;
using UnityEngine;
using Xsolla.Core;

public class XsollaPlayfabSample : MonoBehaviour
{
    private void Start()
    {
        // Logging in anonymously
        LoginAnonymous(
            // Callback function invoked after successful login
            userId => {
                // Requesting Xsolla payment token
                GetXsollaPaymentToken(
                    userId, // PlayFab user ID received after login
                    "booster_max_1", // SKU of the product
                    orderData => {
                        // Creating Xsolla token and opening purchase UI
                        XsollaToken.Create(orderData.token);
                        XsollaWebBrowser.OpenPurchaseUI(orderData.token);

                        // Adding order for tracking
                        OrderTrackingService.AddOrderForTracking(
                            orderData.order_id,
                            true,
                            () => Debug.Log("Payment completed"),
                            onError => Debug.LogError(onError.errorMessage));
                    });
            });
    }

    private static void LoginAnonymous(Action<string> onSuccess)
    {
        // Logging in with custom ID
        PlayFabClientAPI.LoginWithCustomID(
            new LoginWithCustomIDRequest {
                CustomId = SystemInfo.deviceUniqueIdentifier, // Unique ID generated based on the device
                CreateAccount = true
            },
            result => {
                // Logging the result
                Debug.Log("Logged with playfab id: " + result.PlayFabId);

                // Invoking onSuccess callback with PlayFab ID
                onSuccess?.Invoke(result.PlayFabId);
            },
            error => { Debug.LogError(error.GenerateErrorReport()); }); // Handling login error
    }

    private static void GetXsollaPaymentToken(string userId, string sku, Action<OrderData> onSuccess)
    {
        // Creating request data for Xsolla payment token
        var tokenRequestData = new PaymentTokenRequestData {
            uid = userId, // User ID
            sku = sku, // Product SKU
            returnUrl = $"app://xpayment.{Application.identifier}" // Return URL
        };

        // Executing a function in the PlayFab cloud to get payment token
        PlayFabCloudScriptAPI.ExecuteFunction(
            new ExecuteFunctionRequest {
                FunctionName = "GetXsollaPaymentToken", // Name of Azure function
                FunctionParameter = tokenRequestData, // Data passed to the function
                GeneratePlayStreamEvent = false // Setting true if call should show up in PlayStream
            },
            result => {
                // Logging the result
                Debug.Log($"GetXsollaPaymentToken result: {result.FunctionResult}");

                // Parsing JSON result to OrderData object
                OrderData orderData = JsonUtility.FromJson<OrderData>(result.FunctionResult.ToString());

                // Invoking onSuccess callback with order data
                onSuccess?.Invoke(orderData);
            },
            error => Debug.LogError($"Error: {error.GenerateErrorReport()}")); // Handling error
    }

    // Class for payment token request data
    public class PaymentTokenRequestData
    {
        public string uid; // User ID
        public string sku; // Product SKU
        public string returnUrl; // Return URL
    }
}

  1. Crie uma nova cena.
  2. Crie um objeto de jogo vazio. Para fazer isso, vá para o menu principal e selecione GameObject > Create Empty.

  1. Adicione um script ao objeto do jogo:
    1. No painel Hierarchy, selecione o objeto.
    2. No painel Inspector, clique em Add Component e selecione o script XsollaPlayfabSample.

  1. No painel Hierarchy, chame o menu contextual e selecione UI > EventSystem.

Para testar a criação de pedidos, execute a cena clicando em Play. Como resultado, a interface de pagamento com informações do pedido deve aparecer.

O código fonte para o projeto Unity está disponível no GitHub.

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

A lógica de rastreamento de pedido está incluída no método GetXsollaPaymentToken. Para processar uma compra bem-sucedida, você precisa passar uma função que é chamada quando o status do pedido é alterado para done.

O método SDK AddOrderForTracking é usado para rastrear. Para obter informações detalhadas sobre como os métodos funcionam, consulte Rastreamento do status do pedido.

Obter status do pedido no lado do servidor

Aviso

O SDK permite que você rastreie o status do pedido no lado do cliente do seu aplicativo. Porém, recomendamos configurar o gerenciador de webhook Payment para receber informações no back-end do seu aplicativo. Isso permite que você implemente validações adicionais das compras concluídas.

Para obter a lista completa de webhooks e informações gerais sobre trabalhar com eles, consulte a documentação de webhooks.

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.

Observação

Para testar webhooks, você também pode escolher qualquer site dedicado, tal como webhook.site, ou uma plataforma, tal como ngrok.

Para propósitos de teste, você também pode adicionar um script cloud que simula o processamento bem-sucedido do webhook. O código do script está disponível no GitHub.

Para um projeto real, você precisa adicionar a lógica de validação de compra.

  1. 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.
  2. Clique em Enable webhooks.

Este artigo foi útil?
Obrigado!
Podemos melhorar alguma coisa? Mensagem
Que pena ouvir isso
Explique porque este artigo não foi útil para você. Mensagem
Obrigado pelo seu feedback!
Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.
Última atualização: 3 de Outubro de 2024

Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.

Relatar um problema
Nós sempre avaliamos nossos conteúdos. Seu feedback nos ajuda a melhorá-los.
Forneça um e-mail para que possamos responder
Obrigado pelo seu feedback!