Itens gratuitos

Como funciona

Itens gratuitos são itens que os usuários podem obter sem gastar moedas reais ou virtuais.

Itens gratuitos estão disponíveis nos seguintes cenários:

• venda de itens no jogo — itens virtuais, pacotes de moeda virtual e conjuntos
• venda de jogos e DLC via Chaves do Jogo

Casos de uso:

• Itens gratuitos oferecidos em marcos do projeto ou datas especiais, como aniversário, para recompensar a fidelidade dos usuários.
• Complementos gratuitos para usuários que já compraram o jogo base, como recompensa de fidelidade.
• Pacotes iniciais gratuitos disponíveis na loja na web para atrair novos usuários para o jogo.

Itens virtuais gratuitos, moedas virtuais e conjuntos estão disponíveis somente para usuários autorizados. Chaves de jogo gratuitos estão disponíveis tanto para usuários autorizados quanto não autorizados. Os limites na quantidade de itens gratuitos podem ser configurados somente para usuários autorizados.

Configurar itens gratuitos

2. Clique em Create manually e selecione Virtual items na lista suspensa.

3. Na seção General settings, informe:
   1. SKU
   2. um ou mais grupos aos quais o item deve pertencer (opcional)
   3. nome
   4. descrição breve
   5. descrição estendida — para adicioná-la, ative a Opção correspondente (opcional)

4. Na seção Media, faça upload de uma ou mais imagens ou vídeos (opcional) — do seu dispositivo ou via um link. Na loja criada com o editor de sites da Xsolla, todos os cartões de item exibem o arquivo marcado como Main, enquanto os demais arquivos ficam disponíveis apenas em cartões de item com galeria de mídia. O arquivo marcado como Main também é retornado nas respostas das Chamadas de API de obtenção do catálogo.

5. Na seção Price settings, selecione Free item.

6. Para limitar a quantidade de itens disponíveis para compra:
   1. Ative a Opção na seção Limits e especifique a quantidade.
   2. Configure a frequência de redefinição do limite. Para isso, selecione um período na lista suspensa:
      1. Daily.
      2. Weekly.
      3. Monthly.
      4. Custom interval. O intervalo é calculado a partir da data de início de exibição do item na loja.
      5. No regular refresh.
   3. Defina a programação de redefinição especificando os parâmetros correspondentes ao período selecionado.

7. Para configurar um limite de tempo de exibição para o item (opcional):

   1. Ative a Opção na seção Add specific display period.
   2. Especifique o fuso horário e o início e o fim do período.

   Para deixar o fim do período de exibição do item sem especificação, ative a Opção No end date.

8. Configure os Atributos usando uma das opções a seguir (opcional):
   1. Adicione atributos e seus valores no Formato JSON.
   2. Crie manualmente atributos e seus valores e vincule-os aos itens.

9. Clique em Create.
10. Na janela que abrir, selecione o Status do item e clique em Continue.

O item criado aparecerá na seção All items.

Configurar via API

Para tornar um item gratuito, passe “is_free”: true no corpo da solicitação ao chamar as seguintes chamadas de API Admin:

• Criar item virtual ou Atualizar item virtual
• Criar jogo, Atualizar jogo por ID ou Atualizar jogo por SKU
• Criar moeda virtual ou Atualizar moeda virtual
• Criar pacote de moeda virtual ou Atualizar pacote de moeda virtual
• Criar conjunto ou Atualizar conjunto Se você quiser limitar a quantidade de itens gratuitos que um usuário pode receber, passe os seguintes parâmetros nas Chamadas de API de criação ou atualização do item:
  • limits com a quantidade especificada
  • limits.recurrent_schedule com a frequência de redefinição do limite especificada

Você também pode configurar o limite de tempo de exibição do item na loja e definir restrições regionais.

Exibir itens gratuitos no catálogo

Itens gratuitos são exibidos no catálogo dependendo de como ele é implementado — por meio do site builder ou via API.

Exibir via site builder

Para exibir itens gratuitos no seu site:

1. Crie itens gratuitos.
   2. No seu projeto na Conta de Distribuidor, vá para a seção Storefronts > Websites.
   3. No painel do site desejado, clique em Open Site Builder.

   

2. No projeto na sua conta para jogos de celular, vá para a seção Web Shop.
3. Clique no painel do site desejado.

4. Se o seu site incluir várias páginas, selecione a necessária:
   1. Clique no título da página atual na parte superior do builder.
   2. Selecione a página desejada na lista suspensa.
5. Na seção Store, no campo Item type, selecione o tipo de item gratuito e especifique seu grupo, se aplicável.
6. Configure um layout do cartão do item.
7. Depois de fazer todas as alterações necessárias e preparar seu site para o lançamento:
   1. No canto superior direito do site builder, clique em Publish.
   2. Marque as caixas ao lado das páginas que você deseja publicar.
   3. Clique em Publish.

Depois que o site for publicado, uma seção com itens gratuitos ficará disponível. Se os itens não forem exibidos, verifique se o Status deles está definido como Available e se não há limite de exibição baseado em tempo ativo.

Obter informações de itens gratuitos via API

Se o seu catálogo for configurado via API, os dados de itens gratuitos são retornados pelas chamadas disponíveis na subseção Catalog:

• Obter lista de itens virtuais
• Obter lista de moedas virtuais
• Obter lista de pacotes de moeda virtual
• Obter lista de conjuntos
• Obter lista de jogos

Conceder itens gratuitos aos usuários

A maneira como um pedido com itens gratuitos é processado depende se o carrinho foi usando durante a compra.

Se um usuário comprar um item sem usar um carrinho, use a Chamada de API Criar pedido com item gratuito especificado.

Se um usuário comprar itens usando um carrinho, os seguintes cenários são possíveis:

• Se o carrinho do usuário contiver itens pagos e gratuitos, use as Chamadas de API de Criação de Pedido Criar pedido com todos os itens de um carrinho específico ou Criar pedido com todos os itens do carrinho atual. Nesse caso, o usuário conclui o pagamento pela interface de pagamento.
• Se o carrinho do usuário contiver apenas itens gratuitos, use as Chamadas de API Criar pedido com carrinho gratuito ou Criar pedido com carrinho gratuito específico. Nesse caso, a interface de pagamento não é usada.

  Em ambos os casos, a Xsolla envia o Webhook Pagamento bem-sucedido do pedido com os dados do item usados para conceder os itens ao usuário. Para itens gratuitos, o parâmetro order.invoice_id no Webhook é definido como null.

Exemplo de um objeto de pedido para itens gratuitos:

 1{
 2  "method": "POST",
 3  "url": "https://mybestgame.com/xsolla/notification",
 4  "body": {
 5    "items": [
 6      {
 7        "sku": "gift_direct_game_reward-supercoin",
 8        "type": "virtual_currency",
 9        "is_pre_order": false,
10        "quantity": 500,
11        "amount": "0",
12        "promotions": [
13
14        ]
15      },
16      {
17        "sku": "package-500_supercoin",
18        "type": "bundle",
19        "is_pre_order": false,
20        "quantity": 1,
21        "amount": "0",
22        "promotions": [
23
24        ]
25      },
26      {
27        "sku": "xsolla-giveaway_offer_11_14_22",
28        "type": "bundle",
29        "is_pre_order": false,
30        "quantity": 1,
31        "amount": "0",
32        "promotions": [
33
34        ]
35      }
36    ],
37    "notification_type": "order_paid",
38    "order": {
39      "id": 12345678,
40      "mode": "default",
41      "currency_type": "unknown",
42      "currency": null,
43      "amount": "0",
44      "status": "paid",
45      "platform": "xsolla",
46      "comment": null,
47      "invoice_id": null,
48      "promotions": [
49
50      ]
51    },
52    "user": {
53      "external_id": "1234567812345678",
54      "email": null
55    }
56  },
57  "headers": {
58    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
59    "Accept": "application/json",
60    "Content-Type": "application/json"
61  },
62  "type": "webhook_payment",
63  "callback_parameters": {
64    "order_id": 12345678
65  }
66}

Dependendo das configurações de integração do seu projeto, os itens são concedidos ao usário de uma das seguintes maneiras:

• Se você integrou o PlayFab, as moedas virtuais e os itens são concedidos automaticamente ao inventário do usuário no PlayFab.
• Se você usa um sistema de entrega personalizado, todos os itens virtuais e moedas são concedidos do seu lado. Recomendamos configurar um manipulador de Webhook para receber os dados do pedido no seu backend. Os dados necessários estão incluídos no Webhook Pagamento bem-sucedido do pedido. Consulte a seção Configurar o rastreamento do Status do Pedido para mais detalhes sobre essa e outras opções de obtenção de dados de compra.