Sistema de recompensa

Glossário

Como funciona

O sistema de recompensas permite que você incentive usuários a fazerem compras na loja usando moedas reais. Se os usuários fazem parte de clãs, suas compras contribuirão pontos de valor ao clã deles inteiro.

Você pode criar cadeias de recompensa individuais e de clã e conceder recompensas aos usuários pelos itens comprados. O jogo pode incluir múltiplas cadeias de recompensa de qualquer tipo. Cada cadeia deve ter no máximo 31 etapas. Para cada nível, você define a quantidade de pontos de valor necessária para concluí-lo.

Você também pode criar uma cadeia de recompensas personalizada. A personalização permite que você exiba a cadeia somente a um grupo especificado de usuários autorizados com base no atributo deles. Uma cadeia de recompensas personalizada pode ser designada para um usuário individual ou um clã.

Em cada etapa na cadeia de recompensas, um usuário pode receber entre 1 e 10 recompensas. Um clã também recebe entre 1 e 10 recompensas por membro em cada etapa.

Você pode recompensar os usuários com os seguintes tipos de item:

• itens virtuais
• moedas virtuais
• pacotes de moedas virtuais
• conjuntos

Para garantir que o sistema de recompensas funcione corretamente, a autenticação de usuário deve ser configurada. Para usuários não autenticados, ambas as cadeias de recompensa, individuais e de clã, são exibidas sem progresso. Os usuários autenticados que não fazem parte de um clã só conseguem ver a cadeia de recompensas individual deles. As cadeias de recompensa de clãs aparecem como indisponíveis.

Fluxo do usuário

1. O usuário acessa o site.
2. O usuário vê o catálogo de itens, sistema de recompensas e a quantidade de pontos de valor disponível para cada item.
3. O usuário faz login.
4. O usuário agora pode ver seu progresso atual no sistema de recompensas.
5. O usuário faz uma compra e progride pela cadeia de recompensas.

Como obtê-lo

Para configurar um sistema de recompensas, você precisará dos seguintes dados:

• data inicial e final do sistema de recompensa

• uma imagem, descrição, SKUs e nomes de pontos de valor que permitem o progresso na cadeia de recompensas individual ou de clã
• o número de pontos de valor
• itens na cadeia de recompensas

Veja os exemplos abaixo.

Cadeia de recompensas:

Descrição	Exemplo
Nome	Fragmento
Texto explicativo	Para obter recompensas, colete os fragmentos.
SKU	ExemploSKU003
Imagem ou seu URL

Implemente do seu lado:

• exibição de elementos do sistema de recompensa na loja:
  • o número de pontos de valor que são concedidos por comprar itens no catálogo
  • pontos de valor
  • passos
  • cadeias de recompensas
  • o saldo dos pontos de valor do usuário autorizado
  • recompensas
• envio dos dados do clã do usuário ao Login Xsolla

Configuração através da Conta de Distribuidor

Antes de criar uma cadeia de recompensas, você precisa criar pontos de valor, recompensas e itens que os usuários e um clã poderão comprar para ganhar pontos de valor.

Criar pontos de valor

Para criar pontos de valor:

1. No seu projeto na Conta de Distribuidor, acesse a seção Store > Live-ops and promotion tools.
2. Na aba Rewards, clique em Create value points.

3. Especifique os seguintes parâmetros:
   • Adicione uma imagem (opcional).
   • Insira um SKU exclusivo para os pontos de valor.
   • Indique se os pontos de valor serão usados por um clã.
   • Forneça um nome para os pontos de valor.

4. Clique em Next.
5. Selecione o SKU do item virtual e especifique a quantidade de pontos de valor que o usuário receberá pela compra.
6. Clique em + para adicionar a quantidade de itens necessários.
7. Clique em Save.

Os pontos de valor criados são exibidos acima da cadeia de recompensas. Os pontos de valor de clã são marcados de acordo. Para alterar as configurações para um ponto de valor específico, clique em Editar na fileira correspondente.

Criar cadeia de recompensas

Para criar a cadeia de recompensas:

1. No seu projeto na Conta de Distribuidor, acesse a seção Store > Live-ops and promotion tools.
2. Clique em Create reward.

3. Escolha o tipo New reward chain — Individual reward chain ou Clan reward chain.
4. Especifique os seguintes parâmetros. Se você escolher uma cadeia de recompensas individual:
   1. Especifique o nome da cadeia de recompensas.
   2. Forneça uma descrição.
   3. Na lista suspensa, selecione os pontos de valor.

Se você escolher uma cadeia de recompensas de clã:
1. Na lista suspensa Clan type, escolha um tipo de clã.
2. Defina os parâmetros da cadeia de recompensas de clã:
   1. Especifique o nome da cadeia de recompensas.
   2. Forneça uma descrição.
   3. Especifique um título para o cabeçalho pop-up da cadeia de recompensas.
   4. Especifique o texto para a dica pop-up (o que os usuários devem fazer para ganharem recompensas para o clã).
   5. Adicione uma imagem (opcional).
   6. Na lista suspensa, escolha os pontos de valor.

5. Clique em Next.
6. Clique em Add new step.
7. Especifique os seguintes parâmetros e clique em Save:
   1. Nome da etapa.
   2. Quantidade necessária de pontos de valor para resgatar a recompensa.
   3. Quantia necessária de itens virtuais para a etapa.
8. Clique em Next.

9. Se quiser personalizar a cadeia de recompensas:

   1. Defina a opção Personalized reward chain como ativa.
   2. Selecione uma das opções de exibição da cadeia e clique em Next:
      • Show reward chain to specific users. Quando ativada, a cadeia será exibida apenas a usuários autorizados que cumprirem as condições especificadas.
      • Show reward chain to users who don't meet conditions. Quando ativada, a cadeia é exibida apenas se não houver uma cadeia de recompensas correspondente para o usuário — por exemplo, se o usuário não estiver autorizado ou seus atributos não corresponderem a nenhuma cadeia personalizada.
   3. Se você selecionou exibir a cadeia a usuários específicos:
      1. Clique em Add condition e defina as condições de personalização:
         • User attribute é uma característica de usuário, tal como país ou idade. Atributos são configurados na seção de Login.
         • Attribute type define o formato do valor de atributo: cadeia de caracteres, número, ou data.
         • Comparison operator determina como o valor do atributo de usuário é comparado à condição especificada — por exemplo, equals, greater than, less than, ou contains.
         • Attribute value é o valor especificado para comparação. Por exemplo, se o atributo do usuário for a idade, o tipo de atributo será "número", a operação de comparação será "maior do que", e o valor do atributo será "18", e assim a cadeia será exibida somente para usuários com mais de 18 anos de idade.
      2. Para adicionar outra condição de personalização, clique em Add condition.
   4. Clique em Next.

10. Crie a quantidade necessária de etapas e clique em Save.

11. Clique em Next.
12. Especifique o período de validade da cadeia de recompensas.
13. Se você deseja que a cadeia de recompensas seja renovada em um momento específico, defina a opção Make reward chain renewable como On e especifique o modo de atualização.

12. Clique em Save.

1. No catálogo de recompensas, selecione a cadeia de recompensas.
2. Clique em ••• e escolha Activate na lista suspensa.

Configuração de um bloco Sistema de recompensas no Site Builder

Para adicionar um bloco Sistema de recompensas a uma página no Site Builder:

1. Na sua Conta de Distribuidor, acesse o Site Builder.
2. No painel do site desejado, clique em Abrir Site Builder.

3. Clique em Adicionar bloco no modelo de site.
4. Escolha Sistema de recompensas na lista de blocos.

5. Na lista suspensa, escolha uma cadeia de recompensas configurada no Shop Builder.

6. Personalize o botão e cores do texto (opcional).
7. Clique em Prévia no canto superior direito do construtor para conferir seu sistema de recompensas. Clique em Publicar para publicar o site.

Configure por meio de chamadas de API

Você pode usar métodos da subseção Admin do grupo de métodos Cadeias de recompensa e pontos de valor para gerenciar o sistema de recompensas.

1. Crie pontos de valor que concedem acesso a recompensas pela API Criar pontos de valor.
2. Atribua pontos de valor a itens específicos pela API Definir pontos de valor para itens — os usuários receberão esses pontos após comprarem os itens.

3. Crie um sistema de recompensas pela API Criar cadeia de recompensas. Para criar uma cadeia de recompensas personalizada, passe a condição de exibição namatriz attribute_conditions.

   Você pode especificar se uma cadeia de recompensas personalizada deve ser exibida a um usuário que não tem o atributo definido na condição. Para fazer isso, passe true no parâmetro can_be_missing.

   Você também pode definir uma cadeia de recompensas que é exibida a um usuário se nenhuma cadeia personalizada correspondente for encontrada. Para fazer isso, passe false no parâmetro is_always_visible.

4. Ative o sistema de recompensas pela API Acionar cadeia de recompensas.

Você também modificar, desativar, ou excluir o sistema de recompensas e remover pontos de valor dos itens.

Recursos para exibir o sistema de recompensas na interface da loja

Recursos para exibir pontos de valor

Você pode selecionar múltiplas cadeias de recompensas dentro de um único bloco e escolher como elas são exibidas — ou em uma lista ou em abas. Você pode personalizar a aparência de cada cadeia de recompensas individualmente.

Cartões de itens exibem os pontos de valor apenas para as cadeias de recompensas que foram adicionadas ao site. Porém, quando os usuários compram itens, os membros do clã recebem pontos de valor para todas as cadeias de recompensas ativas, independentemente de serem exibidas no site.

Exemplo:

Você tem 2 cadeias de recompensa configuradas: uma cadeia de recompensas individual e uma cadeia de recompensas de clã. A cadeia individual tem um ponto de valor chamado Crystal, e a cadeia de clã tem um ponto de valor chamado Magic Bubble.

No catálogo de item, há um item de nome Sword com pontos de valor atribuídos. Quando um membro de clã compra este item, ele recebe 20 Crystals e 40 Magic Bubbles.

Ao adicionar o bloco Store no construtor e selecionar o tipo e grupo de itens que contém o item Sword:

1. Se nenhuma cadeia de recompensas for adicionada ao site, o item Sword não exibirá qualquer ponto de valor.
2. Se apenas uma cadeia de recompensas individual foi adicionada e estiver ativa, o item Sword exibirá apenas 20 Crystals.
3. Se apenas uma cadeia de recompensas de clã foi adicionada e estiver ativa, o item Sword exibirá apenas 40 Magic Bubbles.
4. Se ambas as cadeias de recompensa individual e de clã foram adicionadas e estiverem ativas, o item Sword exibirá tanto 20 Crystals quanto 40 Magic Bubbles.

Para os membros do clã, 40 Magic Bubbles serão exibidos como o valor ativo.

Para usuário sem um clã, 40 Magic Bubbles serão exibidos como um valor bloqueado.

Definindo o clã do usuário

A Xsolla não cria clãs nem armazena informações sobre os membros do clã. Você precisa implementar o sistema de clãs do seu lado e passar dados relacionados ao clã usando atributos de usuário.

Para garantir o envio e processamento correto dos dados de clã:

1. Defina o esquema de atributos no Login. Adicione o atributo clan_id.

Exemplo do esquema de atributo no Login:

 1{
 2	"$schema": "https://json-schema.org/draft/2020-12/schema",
 3	"additionalProperties": false,
 4	"description": "JSON Schema example for user attributes. Not the actual schema.",
 5	"properties": {
 6
 7		"clan_id": {
 8			"description": "name of clan",
 9			"type": "string"
10		},
11		"custom-id": {
12			"description": "custom-id of a user.",
13			"type": "number"
14		},
15		"had_ban": {
16			"description": "Whether the user was banned.",
17			"type": "boolean"
18		},
19		"last_purchase": {
20			"description": "Date of user's last purchase.",
21			"type": "string"
22		},
23	},
24	"required": [],
25	"title": "Example",
26	"type": "object"
27}

2. Implemente o envio dos dados do clã do usuário:

• Ao autenticar por ID de usuário, passe o clã do usuário na resposta do webhook Validação do usuário na WebShop durante a autorização:
• Para adicionar ou atualizar o atributo clan_id, passe uma matriz de clan_id objetos com a chave de atributo attributes.

Exemplo de uma resposta de webhook:

 1{
 2  "user": {
 3    "id": "1234567890",
 4    "picture": "https://example.com",
 5    "name": "test-name"
 6  },
 7  "attributes": [
 8    {
 9     "key": "clan_id",
10     "value": "beetles"
11    }
12  ]
13}

• Se o usuário saiu do clã e não ingressou em outro, você precisa passar o valor clan_id no campo removing_keys.

Exemplo de uma resposta de webhook:

 1{
 2  "user": {
 3    "id": "1234567890",
 4    "picture": "https://example.com",
 5    "name": "test-name"
 6  },
 7  "removing_keys": [
 8    "key": "clan_id"
 9  ]
10}

• Se o site utiliza autorização via Xsolla Login, use a API Atualizar clã do usuário atual para atualizar o clã do usuário.