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 de jogo — itens virtuais, pacotes de moedas virtuais e conjuntos
• venda de jogos e DLCs via chaves de jogo

• Itens gratuitos oferecidos nos marcos de projeto ou datas especiais, tal como um aniversário, para recompensas os usuários pela fidelidade deles.
• Add-ons gratuitos para os usuários que já compraram o jogo base, como recompensa de fidelidade.
• Pacotes de iniciante gratuitos disponibilizados na loja da web para atrair novos usuários ao jogo.

Configuração de itens gratuitos

Configure na Contra de Distribuidor

1. Abra seu projeto na Conta de Distribuidor e acesse a seção Items catalog > All items.
2. Selecione Add e então Virtual items na lista suspensa.

3. Especifique os seguintes parâmetros:
   • Imagem (opcional).
   • SKU.
   • Um ou diversos grupos aos quais o conjunto deve pertencer.
   • Nome.
   • Descrição (opcional).
4. Na seção de configurações Price, selecione Free item.
5. Para limitar a quantidade de itens disponíveis para compra, ative a opção Limit number of times one user can buy this item e insira a quantidade desejada.
6. Para configurar a frequência de redefinição do limite:
   1. Na lista suspensa, selecione um período:
      • Daily.
      • Weekly.
      • Monthly.
      • Custom interval — isso é calculado a partir da data inicial de exibição do conjunto.
      • No regular refresh.
   2. Defina o cronograma de redefinição com base no período selecionado.
7. Configure como o conjunto é exibido na loja:
   • Selecione o status.
   • Defina um limite de tempo de exibição para o item (opcional): especifique o fuso horário e o início e fim do período. Se você não quiser indicar o fim do período de exibição, marque a caixa No end date.
8. Configure os atributos do item (opcional) usando uma das seguintes opções:
   • Adicione atributos e seus valores no formato JSON.
   • Crie atributos e valores manualmente, e vincule-os aos itens específicos.
9. Selecione Create item.

Configuração 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 moedas virtuais ou Atualizar pacote de moedas virtuais
• Criar conjunto ou Conjunto de atualização

• limits com a quantidade especificada
• limits.recurrent_schedule com o limite de frequência de redefinição especificado

Exibir itens gratuitos no catálogo

Itens gratuitos são exibidos no catálogo dependendo de como ele é implementado — pelo construtor de sites ou via API.

Exibição via site builder

Para exibir itens gratuitos no seu site:

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

4. Na seção Store, no campo Item type, selecione o tipo de item gratuito e especifique seu grupo, se aplicável.
5. Configure um layout de cartão de item.
6. Depois de fazer todas as alterações necessárias e preparar seu site para o lançamento:
   1. No canto superior direito do construtor de sites, selecione Publish.
   2. Marque as caixas próximas às páginas que deseja publicar.
   3. Selecione Publish.

Obtenção de informações de itens gratuitos via API

Se seu catálogo foi configurado usando uma API, os dados do item gratuito são retornados através de chamadas na subseção Catálogo:

• Obter lista de itens virtuais
• Obter lista de moedas virtuais
• Obter lista de pacotes de moedas virtuais
• Obter lista de pacotes
• Obter lista de jogos

Concessão de 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 contém tanto itens gratuitos quanto pagos, 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 contém apenas itens gratuitos, use as chamadas de API Criar pedido com carrinho grátis ou Criar pedido com carrinho gratuito específico. Nesse caso, a interface de pagamento não é utilizada.

Em ambos os casos, a Xsolla envia o Pagamento bem-sucedido do pedido com os dados dos itens usados para conceder os itens ao usuário. Para itens gratuitos, o parâmetro order.invoice_id no webhook fica 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, moedas virtuais e itens são concedidos ao inventário PlayFab do usuário automaticamente.
• Se você usar um sistema de entrega personalizado, todos os itens virtuais e moedas são concedidos do seu lado. Recomendamos configurar um gerenciador de webhooks para receber dados de pedido no seu backend. Os dados necessários são inclusos no webhook Pagamento bem-sucedido do pedido.