Ative o Buy Button com compras personalizadas

Porque isso é importante

Após atualizações recentes das políticas da Apple em certas regiões, os desenvolvedores agora têm a permissão de guiarem seus usuários de seus aplicativos a sites externos para realizarem pagamentos por itens virtuais.

Agora você pode adicionar botões visíveis, banners, mensagens e outros chamados à ação que levam os usuários diretamente do seu jogo à compra do item usando um sistema seguro feito no navegador (à sua Web Shop ou interface de pagamento) com um único clique, sem violar as regras da Apple ou correr o risco de sofrer penalidades.

A integração do Buy Buttion via Headless checkout é ideal se você deseja criar sua própria interface de pagamento personalizada e criar uma experiência de usuário única. Essa opção de integração permite que os usuários prossigam de forma fluída do jogo à compra em um navegador usando uma vasta gama de métodos de pagamento, incluindo pagamentos com um clique via Apple Pay, para criar uma experiência de compra móvel rápida e familiar.

Headless checkout é uma solução de aceitação de pagamento com base na arquitetura de aplicação headless, onde a funcionalidade é acessível via API. Essa abordagem separa a lógica comercial e backend da interface.

Para usar o Headless checkout para aplicativos de jogos iOS:

1. Crie sua própria loja.
2. Integre o Headless checkout na sua loja.
3. Adicione um link no seu jogo que direciona os usuários à sua loja.

Se você estiver procurando pela opção de integração mais rápida com pouca programação, confira a integração com base na Web Shop.

Se você estiver usando uma Web Shop personalizada que não foi construída com o Xsolla Site Builder e quiser integrar uma interface de pagamento pré-pronta no seu jogo, confira a integração via Xsolla Mobile SDK.

Como funciona

Fluxo do usuário:

1. O usuário abre o aplicativo do jogo no iOS.
2. O usuário clica no botão de compra próximo ao item desejado.
3. Sua loja é aberta em um navegador na web. Para garantir uma experiência de usuário fluída, implemente a autorização end-to-end.
4. O usuário seleciona um item e faz uma compra sem sair da loja.
5. O usuário é redirecionado ao aplicativo do jogo após uma transação bem-sucedida.
6. O aplicativo recebe a confirmação da compra via webhook.

Fluxo de integração

1. Criação de um projeto na Conta de Distribuidor e assine o contrato de licenciamento com a Xsolla.
2. Crie um catálogo de itens.
3. Implemente interações backend: crie um token e configure webhooks.
4. Instale o SDK.
5. Integre o SDK no lado do aplicativo.
6. Adicione um link ao seu jogo que leva os usuários à sua loja onde o Headless checkout está integrado.

Crie um projeto e assine o contrato de licenciamento

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

Para se cadastrar, acesse Conta de Distribuidor e crie uma conta. Para criar um projeto, selecione Create project no menu lateral e forneça quaisquer informações necessárias. Você pode modificar as configurações mais tarde.

Para assinar o contrato de licenciamento, acesse a seção Contratos & Taxas > Contratos e preencha o formulário do contrato.

Criar catálogo de itens

Produtos de Compra No App (IAP) são representados através de itens virtuais no ecossistema Xsolla. Eles possuem um nome, descrição, SKU e um preço. Para configurar seu SKU de catálogo de produtos IAP, você pode:

1. Enviar um arquivo JSON para adicionar rapidamente seu catálogo à Conta de Distribuidor.
2. Crie um catálogo de itens usando as chamadas API da seção de documentação Virtual items & currency > Admin.

Implementação da interação backend

Criar token

Configure webhooks

Para habilitar webhooks:

1. No seu projeto dentro da Conta de Distribuidor, vá para a seção Configuração do projeto > Webhooks.
2. No campo Webhook server, especifique o URL do servidor, onde você deseja receber webhooks no formato https://example.com. Você também pode especificar o URL que encontrar em uma ferramenta para testar webhooks.
3. Uma chave secreta para assinar webhooks de projeto é gerada por padrão. Se quiser gerar uma nova chave secreta, clique no ícone de atualização.
4. Clique em Enable webhooks.

Para a operação completa da loja no jogo e gerenciamento de pagamento, é necessário implementar o processamento dos webhooks principais:

Instalação do SDK

1. Instale o SDK como um pacote npm executando o comando:

1npm install --save @xsolla/pay-station-sdk

2. Inicialize o SDK passando parâmetros do ambiente:

1import { headlessCheckout } from '@xsolla/pay-station-sdk';
2
3await headlessCheckout.init({
4  sandbox: true,
5});

3. Passe o token de pagamento para o SDK inicializado:

1await headlessCheckout.setToken(accessToken);

Integre o SDK no lado do aplicativo

Depois de instalar e inicializar o SDK:

1. Inicialize a interface de pagamento especificando o ID do método de pagamento. O método headlessCheckout.form.init retorna um objeto usado para ter mais interação com a interface de pagamento.

1await headlessCheckout.form.init({
2  paymentMethodId: 3175, // Apple Pay payment ID
3});

2. Adicione a manipulação do evento show_fields para a exibição de campos adicionais.

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'show_fields':
4      this.handleShowFieldsAction(nextAction);
5  }
6});

3. Adicione os seguintes componentes à marcação HTML da interface de pagamento.
   • Componentes obrigatórios:
     • psdk-legal — Para exibir informações sobre documentos legais.
     • psdk-total — Para exibir a quantia total da compra.
   • Componentes do formulário de pagamento. Você pode usar o componente psdk-payment-form integrado ou criar elementos da interface de pagamento manualmente usando componentes de uso pronto.
   • O componente do botão de pagamento — psdk-apple-pay. Você também pode usar o componente psdk-submit-button que já inclui psdk-apple-pay.

1<psdk-legal></psdk-legal>
2<psdk-total></psdk-total>
3
4
5<psdk-payment-form></psdk-payment-form>
6<psdk-apple-pay text="Apple Pay"></psdk-apple-pay>

4. Adicione a manipulação do evento check_status para a alteração de status do pagamento.

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'check_status': {
4      showStatus = true;
5    }
6  }
7});

5. Adicione o componente psdk-status à marcação HTML da interface de pagamento para exibir um status de pagamento.

1@if (showStatus) {
2  <psdk-status></psdk-status>
3}

Como detectar a loja digital iOS

Para determinar a loja digital iOS atual e ajustar a funcionalidade do SDK com base na região, use os seguintes trechos de códigos:

1[SKPaymentQueue loadCurrentStorefrontCountryCodeWithCompletion:^(NSString* _Nullable countryCode) {
2    settings.enablePayments = countryCode && [countryCode isEqualToString:@"USA"];
3
4    [[SKPaymentQueue defaultQueue] startWithSettings:settings];
5}];

1SKPaymentQueue.loadCurrentStorefrontCountryCode { countryCode in
2    settings.enablePayments = countryCode == "USA"
3
4    SKPaymentQueue.default().start(settings)
5}

O método loadCurrentStorefrontCountryCode recupera o código do país de três letras de forma assíncrona para a loja digital atual. Você pode usar essa informação para ativar ou desativar a funcionalidade do SDK para regiões específicas.

Alternativamente, você pode usar a Storefront nativa da Apple diretamente, como exibido abaixo:

1let storefront = await Storefront.current   
2let countryCode = storefront?.countryCode
3
4settings.enablePayments = countryCode == "USA"
5
6SKPaymentQueue.default().start(settings)

Pagamento com um clique via Apple Pay

O pagamento com um clique permite que os usuários paguem com a Apple Pay, um método de pagamento nativo, familiar e seguro nos dispositivos suportados. Para configurar o pagamento com um clique:

1. Crie uma solicitação para habilitar essa opção. Para fazer isso:

   a. Abra sua Conta de Distribuidor e vá para a seção Support Hub.

   b. Clique em Submit request.

   

   c. Na janela que surgir, preencha os seguintes campos:

   • Summary. Por exemplo, a configuração do pagamento com um clique via Apple Pay.
   • Description. Especifique o domínio usado para abrir a interface de pagamento, como amazing.store.com.
   • Project ID. Selecione um ID de projeto na lista suspensa. Se você quiser configurar a opção de pagamento com um clique para múltiplos projetos, especifique os IDs deles no campo Description.

   d. Clique em Send.

2. Espere pelo arquivo de associação do domínio. Essa etapa é realizada pela Xsolla:
   1. A Xsolla cadastra seu domínio com a Apple.
   2. A Xsolla recebe o arquivo de associação do domínio da Apple.
   3. A Xsolla envia um e-mail a você com o arquivo de associação do domínio e fornece instruções sobre aonde deve enviá-lo.

3. Atualize o script de inicialização do SDK conforme exibido abaixo:

1const config: InitialOptions = {
2  isWebview: false,
3  theme: 'default',
4  language: parameters.language,
5  topLevelDomain: 'amazing.store.com',
6  isApplePayInstantFlowEnabled: true
7};
8
9await initHeadlessCheckoutLib(config);