Ative o Buy Button via links externos à Web Shop

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.

• Um fluxo simples — pressionar o Buy Button abre a compra da Web Shop para um item específico, permitindo que os usuários retornem automaticamente ao jogo após um pagamento de sucesso.
• Suporte a uma vasta gama de métodos de pagamento, incluindo pagamentos com um clique via Apple Pay para possibilitar compras móveis rápidas e familiares.
• Configuração rápida — se sua Web Shop já estiver configurada, você só precisa adicionar um link com parâmetros ao jogo.
• Integração imediata — se você ainda não tem a Web Shop, você pode rapidamente começar criando a Web Shop instantaneamente, adicionando links de pagamento ao seu jogo e fazendo a publicação.

Essa opção de integração dá a você acesso não só à integração do Buy Button como também à experiência Web Shop completa, incluindo recursos como personalizações, programa de indicações, sistema de fidelidade, códigos promocionais e mais.

Confira a integração via Xsolla Mobile SDK se estiver usando uma Web Shop personalizada que não seja feita no Site Builder e esteja procurando integrar a Pay Station diretamente no seu jogo.

Como funciona

1. O usuário abre o aplicativo no iOS.
2. O usuário toca no Buy Button ao lado do item desejado.
3. O aplicativo inicializa um navegador com o link da Web Shop que inclui os parâmetros user-id, purchase-sku e redirect-url.
4. A Web Shop automaticamente autentica o usuário e exibe a interface de pagamento para o item selecionado.
5. O usuário escolhe um método de pagamento e conclui a compra.
6. O usuário é redirecionado automaticamente de volta ao jogo via link profundo.
7. O aplicativo recebe a confirmação de compra através de um webhook e entrega o item comprado.

Como obtê-lo

1. Crie uma Web Shop:
   1. Crie um projeto na Conta de Distribuidor.
   2. Configure um modelo.
   3. Crie um catálogo de itens.
   4. Configure a autenticação de usuários.
   5. Configure webhooks para conceder compras ao usuário.
   6. Teste o site.
   7. Publique o site.
2. Adicione a lógica ao seu app iOS para mostrar o botão com o link de compra apenas a usuários nos Estados Unidos:
   1. Adicione o botão ao seu jogo.
   2. Detecte a vitrine iOS.

Início rápido

Cadastre uma Conta de Distribuidor e crie um projeto

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.

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

Configure o modelo Web Shop

1. Abra seu projeto na Conta de Distribuidor.
2. Na página principal do projeto, selecione Change focus e então Enable Buy Button via link-outs to Web Shop.
3. Na etapa Create your Web Shop page, selecione Create template.

4. Selecione o tipo de Web Shop:
   • Loja de página única — um site onde todas as seções são colocadas em uma única página.
   • Portal multipágina na web — um site com três páginas separadas: uma página principal, uma página de catálogo de itens e uma página de notícias.

5. Selecione Continue.
6. Na aba Express, adicione um link ao seu jogo na App Store. Isso permite que você rapidamente crie um site personalizado para o seu jogo: a imagem do seu jogo, título, nome do desenvolvedor e esquema de cores são adicionados automaticamente durante a criação do site.
7. Selecione Create Web Shop.

Configure o catálogo de itens

No lado da Xsolla, você precisa criar um catálogo dos itens que pretende vender no jogo. Você pode escolher os seguintes métodos para configurar seu catálogo:

• Import items: envie um arquivo JSON para adicionar rapidamente seu catálogo a uma Conta de Distribuidor.
• Use API calls: ideal para atualizações automatizadas ou de larga escala.
• Import your catalog from App Store, Google Play, or PlayFab: transfira um catálogo existente diretamente de uma plataforma externa.
• Set up the catalog manually: adicione e edite itens diretamente na Conta de Distribuidor.

Configure a autenticação do usuário

Para conceder compras à conta no jogo do usuário, configure uma autenticação via ID de usuário no jogo.

Você também precisa configurar um gerenciamento de webhooks para verificar que o usuário existe. Esse webhook fornece uma validação adicional quando a Web Shop é aberta via link direto no jogo, e é necessário para a autenticação do usuário em casos onde a Web Shop é acessada fora do cliente do jogo.

Para configurar a autenticação:

1. Do lado do seu aplicativo, implemente a manipulação do webhook de validação do usuário.

Ao receber um webhook, o aplicativo deve fazer o seguinte:

• Procurar um usuário por seu ID passado no webhook.
• Dependendo do resultado, enviar um dos seguintes códigos de status:
  • Código HTTP 200 com uma resposta do webhook se um usuário for encontrado
  • Código HTTP 404 se o ID do usuário não for encontrado
• Enviar atributos de usuário para personalização.

2. Abra seu projeto na Conta de Distribuidor e acesse a seção Storefronts > Websites.
3. No painel do site necessário, selecione Open Site Builder.
4. Vá para o bloco Login settings.

5. Selecione a opção ID do usuário.

6. Na lista suspensa, selecione Novo login.

7. Insira o URL para receber webhooks. Esse URL pode ser diferente do especificado em Project settings > Webhooks.

Configure webhooks para conceder compras ao usuário

Webhooks são notificações sobre eventos ocorrendo no sistema. Quando um evento específico ocorre, a Xsolla envia uma solicitação HTTP, transmitindo os dados do evento ao seu servidor do jogo. Esses webhooks são essenciais para o cliente do jogo e/ou servidor para receber notificações sobre pagamentos bem-sucedidos ou mal-sucedidos e tentativas de autenticação de usuários.

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

Testando webhooks

Na aba Payments and Store, você pode testar os seguintes webhooks:

Validação de usuário (“notification_type”:“user_validation”):

 1curl -v 'https://your.hostname/your/uri' \
 2-X POST \
 3-H 'Accept: application/json' \
 4-H 'Content-Type: application/json' \
 5-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
 6-d '{
 7    "notification_type":"user_validation",
 8    "settings": {
 9      "project_id": 18404,
10      "merchant_id": 2340
11    },
12    "user": {
13        "ip": "127.0.0.1",
14        "phone": "18777976552",
15        "email": "email@example.com",
16        "id": "1234567",
17        "name": "John Smith",
18        "country": "US"
19    }
20}'

Pagamento bem-sucedido do pedido (“notification_type”: “order_paid”):

  1curl -v 'https://your.hostname/your/uri' \
  2-X POST \
  3-H 'Accept: application/json' \
  4-H 'Content-Type: application/json' \
  5-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
  6-d '{
  7    "notification_type": "order_paid",
  8    "items": [
  9      {
 10        "sku": "com.xsolla.item_1",
 11        "type": "virtual_good",
 12        "is_pre_order": false,
 13        "quantity": 3,
 14        "amount": "1000",
 15        "promotions": [
 16          {
 17            "amount_without_discount": "6000",
 18            "amount_with_discount": "5000",
 19            "sequence": 1
 20          },
 21          {
 22            "amount_without_discount": "5000",
 23            "amount_with_discount": "4000",
 24            "sequence": 2
 25          }
 26        ],
 27        "custom_attributes":
 28          {
 29            "purchased": 0,
 30            "attr": "value"
 31          }
 32      },
 33      {
 34        "sku": "com.xsolla.item_new_1",
 35        "type": "bundle",
 36        "is_pre_order": false,
 37        "quantity": 1,
 38        "amount": "1000",
 39        "promotions": []
 40      },
 41      {
 42        "sku": "com.xsolla.gold_1",
 43        "type": "virtual_currency",
 44        "is_pre_order": false,
 45        "quantity": 1500,
 46        "amount": null,
 47        "promotions": []
 48      }
 49    ],
 50    "order": {
 51      "id": 1,
 52      "mode": "default",
 53      "currency_type": "virtual",
 54      "currency": "sku_currency",
 55      "amount": "2000",
 56      "status": "paid",
 57      "platform": "xsolla",
 58      "comment": null,
 59      "invoice_id": "1",
 60      "promotions": [
 61        {
 62          "amount_without_discount": "4000",
 63          "amount_with_discount": "2000",
 64          "sequence": 1
 65        }
 66      ],
 67      "promocodes": [
 68        {
 69          "code": "promocode_some_code",
 70          "external_id": "promocode_sku"
 71        }
 72      ],
 73      "coupons": [
 74        {
 75          "code": "WINTER2021",
 76          "external_id": "coupon_sku"
 77        }
 78      ]
 79    },
 80    "user": {
 81      "external_id": "id_xsolla_login_1",
 82      "email": "gc_user@xsolla.com"
 83    },
 84    "billing": {
 85      "notification_type": "payment",
 86      "settings": {
 87        "project_id": 18404,
 88        "merchant_id": 2340
 89      },
 90      "purchase": {
 91          "subscription": {
 92              "plan_id": "b5dac9c8",
 93              "subscription_id": "10",
 94              "product_id": "Demo Product",
 95              "date_create": "2014-09-22T19:25:25+04:00",
 96              "date_next_charge": "2014-10-22T19:25:25+04:00",
 97              "currency": "USD",
 98              "amount": 9.99
 99          },
100          "total": {
101              "currency": "USD",
102              "amount": 200
103          },
104          "promotions": [{
105              "technical_name": "Demo Promotion",
106              "id": 853
107          }],
108          "coupon": {
109              "coupon_code": "ICvj45S4FUOyy",
110              "campaign_code": "1507"
111          }
112        },
113      "transaction": {
114          "id": 1,
115          "external_id": 1,
116          "payment_date": "2014-09-24T20:38:16+04:00",
117          "payment_method": 1,
118          "payment_method_name": "PayPal",
119          "payment_method_order_id": 1234567890123456789,
120          "dry_run": 1,
121          "agreement": 1
122      },
123      "payment_details": {
124          "payment": {
125              "currency": "USD",
126              "amount": 230
127          },
128          "vat": {
129              "currency": "USD",
130              "amount": 0,
131              "percent": 20
132          },
133          "sales_tax": {
134              "currency": "USD",
135              "amount": 0,
136              "percent": 0
137          },
138          "direct_wht": {
139              "currency": "USD",
140              "amount": 0,
141              "percent": 0
142          },
143          "payout_currency_rate": "1",
144          "payout": {
145              "currency": "USD",
146              "amount": 200
147          },
148          "country_wht": {
149              "currency": "USD",
150              "amount": 2,
151              "percent": 10
152          },
153          "user_acquisition_fee": {
154              "currency": "USD",
155              "amount": 2,
156              "percent": 1
157          },
158          "xsolla_fee": {
159              "currency": "USD",
160              "amount": 10
161          },
162          "payment_method_fee": {
163              "currency": "USD",
164              "amount": 20
165          },
166          "repatriation_commission": {
167              "currency": "USD",
168              "amount": 10
169          }
170      }
171    }
172 ,
173  "custom_parameters": {
174    "parameter1": "value1",
175    "parameter2": "value2"
176  }
177}'

Teste o site no modo sandbox

Para testar o funcionamento do site no modo sandbox:

1. Abra seu projeto na Conta de Distribuidor e acesse a seção Storefronts > Websites.
2. Selecione Open Site Builder no painel do site necessário.
3. Selecione Preview.

4. Selecione um item e clique no botão de compra.
5. Escolha o grupo Card de métodos de pagamento.
6. Insira os dados do cartão bancário de teste. Insira quaisquer valores nos campos restantes. Você também pode especificar detalhes incorretos (número do cartão, data de validade ou CVV) para gerar um erro.

Publique o site

1. Para melhorar o desempenho do seu site:

   a. No bloco SEO Settings, defina os parâmetros que serão usados pelos motores de busca e para a prévia de páginas nas redes sociais: envie um favicon, especifique o título e descrição da loja, adicione uma imagem de prévia.

   b. Configure as traduções do site.

   c. Faça alterações no domínio (opcional). Para fazer isso, acesse a seção Storefronts > Websites e selecione Configure no painel do seu site. Na seção Domain, edite o valor Xsolla domain, ou configure o seu próprio domínio.

2. Depois de fazer todas as alterações necessárias e sua loja virtual estiver pronta para o lançamento, selecione Publish.

Adicione um botão com um link de compra ao seu jogo

Adicione um botão ao seu jogo que redireciona o usuário à Web Shop para pagar pelo item selecionado. O botão deve conter um link no seguinte formato: https://yourwebshop.xsolla.site/?user-id=<USER_ID>&purchase-sku=<ITEM_SKU>&redirect-url=<RETURN_TO_GAME_URL>, onde:

• yourwebshop.xsolla.site é um link ao seu site da Web Shop.
• user-id é o ID de usuário no seu sistema.
• purchase-sku é o SKU do item desejado no catálogo da Web Shop.
• redirect-url é o endereço URL de uma página na web (ex.: https://example.com/success) ou um link profundo (ex.: mygame://open) para o qual o usuário é redirecionado após fazer um pagamento. Ao usar um link profundo, certifique-se de que:
  • você está usando o formato correto, incluindo tanto o esquema quanto o trajeto (ex.: mygame://open), e não só o esquema (mygame://)
  • o link profundo seja gerenciado dentro do seu aplicativo móvel do jogo.

Para encontrar o SKU do item (usando um item virtual como exemplo):

1. Abra seu projeto na Conta de Distribuidor e acesse a seção Items catalog > Virtual items.
2. Navegue até o grupo de itens onde o item se encontra.
3. Copie o SKU da linha do item específico abaixo de seu nome.

Detectar vitrine iOS

Para determinar se você pode exibir o Buy Button, recupere a informação storefront no lançamento inicial do aplicativo após a instalação, ou em lançamentos subsequentes se necessário. A vitrine já pode estar disponível como parte da sua implementação StoreKit existente ou fornecida pelo seu Parceiro de Medição Móvel (MMP). Se o código de país da vitrine for “USA”, ative a funcionalidade para exibir o Buy Button.

Garanta que sua implementação seja flexível o bastante para suportar países adicionais no futuro, pois as condições regulamentárias e políticas de plataforma podem mudar.

Observe que o valor da vitrine no dispositivo não é alterado a menos que o usuário explicitamente atualize sua região Apple ID nas configurações do sistema.

1let countryCode = await Storefront.current?.countryCode
2let showBuyButton = countryCode == "USA"

Recursos adicionais

Você pode fornecer acesso rápido aos recursos da Web Shop para os usuários usando parâmetros de consulta no URL do site. Para mais detalhes, consulte as instruções sobre o uso de parâmetros de consulta.

Análises avançadas no AppsFlyer

Ao utilizar links externos para permitir que os usuários façam compras na interface de pagamento da web diretamente do jogo, você ainda pode rastrear as compras deles e medir o valor vitalício (LTV) com um Parceiro de Medição Móvel (MMP), tal como a AppsFlyer. A Xsolla suporta dois tipos de integração para permitir o rastreamento fluido da aquisição de usuários, redirecionamento e atividades de compra tanto em plataformas móveis quanto na web.

Escolha um tipo que se adeque às suas necessidades para manter a visibilidade completa nas suas campanhas e receitas: