Conjuntos

Como funciona

Conjunto é um aglomerado de vários itens que são vendidos como uma única unidade.

Principais características:

• Adicionar itens de diferentes tipos a um pacote:
  • moeda virtual (incluindo a moeda dependente da plataforma)
  • pacote de moedas virtuais
  • chaves de jogo para plataformas pré-selecionadas
  • itens virtuais, incluindo itens de tempo limitado
  • conjuntos
• Configure o preço do conjunto em moedas reais e virtuais. Certifique-se de selecionar uma moeda padrão, neste caso.
• Conjunto grátis.
• Limitando a quantidade de conjuntos disponíveis para compra.
• Limitando o tempo de exibição de conjuntos na loja.

• Via PlayFab – para moedas virtuais, itens virtuais, itens de tempo limitado, e conjuntos, se a integração PlayFab estiver ativada.
• Por e-mail – para chaves de jogo.
• Através do seu próprio sistema de entrega, usando dados do webhook Pagamento bem-sucedido do pedido. Esse método se aplica a todos os tipos de itens se:
  • A integração PlayFab não foi usada.
  • Você preferir gerenciar a entrega de itens aos usuários no seu próprio servidor.

1. Ao comprar, se a inclusão de conteúdos do conjunto não estiver desabilitada, todos os itens inclusos no conjunto serão passados na matriz items como uma lista de itens individuais. Se o conjunto contiver outro conjunto, seus conteúdos também serão passados como itens individuais.

Quando um conjunto é reembolsado, por exemplo, devido a um cancelamento de uma transação, um webhook Cancelamento de pedido é enviado. Use os dados do webhook para deduzir os itens comprados da conta do usuário.

Restrições:

• Não é possível adicionar o mesmo conjunto ao conjunto.
• Não é possível criar um conjunto vazio.
• As vendas do conjunto são pausadas depois que você fica sem chaves para vender e essas chaves estiverem incluídas no conjunto.

Limitação do número de conjuntos disponíveis para compra

Você pode limitar a compra de conjuntos. Por exemplo, você pode limitar:

• o número de conjuntos por usuário
• conjuntos de boas-vindas que só estão disponíveis para compra uma vez

Se o usuário tiver atingido o limite especificado, o conjunto não será exibido no catálogo. Se o conjunto contiver um pacote de moedas virtuais ou item com um limite de compra e o usuário já tiver comprado o valor permitido, o pacote não será exibido no catálogo.

Você pode exibir o número máximo disponível de pacotes e o número restante de pacotes que está disponível para o usuário.

Para definir um limite de compra ao criar um conjunto na Conta de Distribuidor, defina a opção Limit number of times one user can buy this bundle como On e especifique o número de vezes que o conjunto pode ser comprado.

Você pode usar os métodos da subseção Catálogo do grupo de métodos Pacotes para obter informações sobre conjuntos.

Na resposta, você receberá as seguintes informações, além de informações sobre o conjunto:

• o número máximo de conjuntos que um usuário pode comprar
• o número restante de conjuntos disponíveis para o usuário comprar

Você pode ler mais sobre como configurar ou atualizar restrições nas instruções Limites para o usuário.

 1{
 2  "items": [
 3    {
 4      "sku": "kg_1",
 5      "name": "kg_10.00_bundle",
 6      "type": "bundle",
 7      "description": "pricePoint_44056_1",
 8      "image_url": null,
 9      "long_description": null,
10      "attributes": {
11        "external_id": "genre",
12        "name": "Genre",
13        "values": [
14          {
15            "external_id": "genre_e3364991f92e751689a68b96598a5a5a84010b85",
16            "value": "Casual"
17          },
18          {
19            "external_id": "genre_eba07bfd0f982940773cba3744d97264dd58acd7",
20            "value": "Strategy"
21          },
22          {
23            "external_id": "genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8",
24            "value": "Mobile"
25          }
26        ]
27      },
28      "is_free": false,
29      "order": 999,
30      "groups": [],
31      "price": {
32        "amount": 9.99,
33        "currency": "USD",
34        "amount_without_discount": 9.99
35      },
36      "total_content_price": {
37        "amount": 10.99,
38        "currency": "USD",
39        "amount_without_discount": 10.99
40      },
41      "media_list": [],
42      "virtual_prices": [],
43      "can_be_bought": true,
44      "bundle_type": "standard",
45      "limits": {
46        "$ref": "./Catalog_item_limits.yaml"
47      },
48      "content": [
49        {
50          "sku": "big_rocket",
51          "name": "Big Rocket",
52          "description": "Big Rocket - short description.",
53          "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
54          "type": "virtual_currency",
55          "quantity": 100,
56          "virtual_item_type": "non_consumable",
57          "attributes": {
58            "external_id": "size",
59            "name": "Size",
60            "values": [
61              {
62                "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
63                "value": "Large"
64              }
65            ]
66          },
67          "is_free": false,
68          "groups": [],
69          "price": {
70            "amount": 10.99,
71            "currency": "USD",
72            "amount_without_discount": 10.99
73          },
74          "virtual_prices": [],
75          "limits": {
76            "per_user": {
77              "total": 5,
78              "available": 5
79              },
80            "per_item": null
81           },
82          }
83        }
84      ]
85    }
86  ]
87}

Limitando o tempo de exibição de conjuntos na loja

• manter a relevância do catálogo em um determinado momento, por exemplo, durante as vendas de fim de ano
• crie um conjunto com antecedência sem exibi-lo no catálogo
• motive os usuários a comprar conjuntos exibindo um temporizador ao lado do item

Para definir um limite de tempo de exibição de um conjunto na loja pela Conta de Distribuidor, selecione Time period e especifique o fuso horário, o período inicial e o período final. Para não indicar o fim do período de exibição do conjunto, marque a caixa No end date.

Para definir um limite de tempo para exibir um conjunto na store via API, passe os seguintes parâmetros na chamada de API Criar conjunto ou Atualizar conjunto:

• periods[0].date_from com a data e hora do início do período de exibição do item no formato YYYY-MM-DDThh:mm:ss±TMZ, onde TMZ é o indicador de fuso horário no formato GMT hh:mm.

• periods[0].date_until com a data e hora do final do período de exibição do item no formato YYYY-MM-DDThh:mm:ss±TMZ, onde TMZ é o indicador de fuso horário no formato GMT hh:mm. Para não indicar o final do período de exibição de um item, passe null.

Você pode configurar vários períodos para exibir um conjunto na loja. Para fazer isso, no método Criar conjunto ou Atualizar conjunto, passe uma matriz de objetos com as datas de início e término de todos os períodos.

Exemplo:

 1"periods": [
 2      {
 3        "date_from": "2022-06-10T14:00:00+03:00",
 4        "date_until": "2022-06-30T14:00:00+03:00"
 5      },
 6       {
 7        "date_from": "2022-07-10T14:00:00+03:00",
 8        "date_until": "2022-07-30T14:00:00+03:00"
 9      },
10       {
11        "date_from": "2022-08-10T14:00:00+03:00",
12        "date_until": "2022-08-30T14:00:00+03:00"
13      }
14]

Quem pode usar

Para parceiros que desejam vender conjuntos de itens por um preço inferior ao total inicial de todos os itens do conjunto, o que aumenta as vendas e ajuda a obter novos jogadores.

Como obtê-lo

Fluxo de integração

1. Configure um conjunto.
2. Implemente a obtenção de conjuntos em um catálogo.

Configuração de conjunto

• via Conta de Distribuidor
• via métodos de API

Configuração através da Conta de Distribuidor

1. Abra seu projeto na Conta de Distribuidor e vá para a seção Items catalog > Bundles.
2. Selecione + e selecione Criar conjunto da lista suspensa.
3. Adicione:
   • Imagem (opcional).
   • SKU.
   • Um ou diversos grupos aos quais o conjunto deveria pertencer.
   • Nome.
   • Descrição (opcional).
   • Conteúdos.
4. Defina o preço do conjunto:
1. Defina os preços ou crie um conjunto grátis:
1. Para criar um conjunto grátis, no campo Pago ou Grátis, selecione Conjunto grátis.
2. Para definir um preço, no campo Pago ou Grátis, selecione Conjunto pago e especifique o preço em moedas reais ou virtuais. Se necessário, configure preços regionais.
2. Defina um limite de compra para o conjunto (opcional). Para fazer isso, defina a opção Limitar quantidade de vezes que um usuário pode comprar o conjunto como Ligada e especifique a quantidade de conjuntos que cada usuário pode comprar.
5. Selecione Avançar.
6. Configure a exibição do conjunto na loja:
   • Mude o status para Disponível.
   • Defina um limite de tempo para exibir conjuntos na loja (opcional). Para fazer isso, selecione Período e especifique o fuso horário, o começo e o fim do período. Se você não quiser indicar o fim do período de exibição, marque a caixa Nenhuma data final.
7. Selecione Avançar.
8. Confira as configurações e selecione Salvar.

Configuração por meio de métodos de API

Adicione a chave de jogo ao conjunto

Para adicionar uma chave de jogo para uma plataforma selecionada a um conjunto, passe uma matriz de content com SKUs das plataformas necessárias para os métodos Criar conjunto ou Atualizar conjunto.

1"content": [{
2     “sku”: “brilliant_game_sku_steam”,
3     “quantity”: 1
4  }
5]

Configuração de restrições regionais

Para configurar restrições regionais para um conjunto, passe uma matriz com IDs de regions suportadas para os métodos Criar conjunto ou Atualizar conjunto.

1"regions": [{
2     “id”: 123
3  }, {
4     “id”: 456
5  }
6]

Configuração de preços regionais

Para configurar preços regionais para um conjunto, passe uma matriz de prices com configurações para as regiões aos métodos Criar conjunto ou Atualizar conjunto.

 1"prices": [
 2      {
 3        "amount": 100,
 4        "currency": "USD",
 5        "is_enabled": true,
 6        "is_default": true
 7      },
 8      {
 9        "amount": 200,
10        "currency": "CZK",
11        "country_iso": "CZ",
12        "is_enabled": false,
13        "is_default": false
14      }
15    ]

Obter conjuntos em um catálogo

Configurando informações de item em webhooks

Você pode configurar quais dados de itens são inclusos nos webhooks Pagamento do pedido bem-sucedido e Cancelamento do pedido pela matriz items.

Habilitação da inclusão de parâmetros adicionais

Habilite a inclusão de parâmetros adicionais que indicam:

• se o item é grátis (is_free)
• se o item é um bônus (is_bonus)
• se o item faz parte de um conjunto (is_bundle_content)

Para receber esses parâmetros, você deve trocar seus webhooks para a versão 2 usando a chamada de API Atualizar informações sobre as configurações do webhook. Na versão 1 (padrão), esses parâmetros não estão disponíveis.

Exemplo de uma matriz de items com parâmetros adicionais:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      },
14      {
15        "sku": "com.xsolla.gold_1",
16        "type": "virtual_currency",
17        "is_pre_order": false,
18        "is_free": false,
19        "is_bonus": false,
20        "is_bundle_content": true,
21        "quantity": 1500,
22        "amount": "[null]",
23        "promotions": []
24      }
25 ],

Desativação da inclusão de conteúdos de conjunto

Por padrão, webhooks incluem todos os tipos de itens do conjunto como uma lista de itens individuais. Você pode configurar o webhook para incluir apenas o conjunto em si, sem listar seus conteúdos.

Nesse caso, os itens inclusos no conjunto não são inclusos na matriz items. Na matriz exibida acima, o item com o SKU com.xsolla.gold_1, que é parte do conjunto, é excluído.

Exemplo de uma matriz de items quando o conteúdo do conjunto está desativado:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "Is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ],

Para desativar a inclusão de conteúdos do conjunto, entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.