Sistema de recompensa

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

Configuração do sistema de recompensas

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.

Para criar itens manualmente no seu projeto na Conta de Distribuidor, acesse a seção Items catalog > All items. Encontre informações detalhadas sobre esse e outros métodos para criar itens na seção Catálogo de itens da documentação.

Para criar pontos de valor:

1. Abra seu projeto na Conta de Distribuidor e vá para a seção LiveOps > Rewards.
2. Selecione Create value points.

3. Especifique os seguintes parâmetros:
   • Adicione uma imagem (opcional).
   • Insira um nome.
   • Insira um SKU exclusivo.
   • Se você estiver criando pontos de valor de clã, ative a opção Use as clan value points. Essa configuração não pode ser alterada depois que os pontos de valor são criados.
   • Atribua pontos de valor: selecione os itens e especifique quantos pontos de valor os usuários recebem por comprar cada item. Se sua loja não contiver nenhum item, você poderá salvar as configurações atuais e retornar a essa etapa mais tarde.

4. Selecione Add row para inserir a quantidade de posições desejada.
5. Selecione Create value points.

Para criar a cadeia de recompensas:

1. Abra seu projeto na Conta de Distribuidor e vá para a seção LiveOps > Rewards.
2. Clique em Create reward.

3. Escolha o tipo da cadeia — 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:
   • Nome da etapa.
   • Quantidade necessária de pontos de valor para resgatar a recompensa.
   • Quantidade necessária de itens virtuais para a etapa.
8. Selecione Save.

9. Adicione a quantidade necessária de etapas e selecione Save.

10. Se você quiser personalizar a cadeia de recompensas:

    1. Ative a opção Personalized reward chain.
    2. Selecione uma das opções de exibição da cadeia e então selecione Next:
       • Exibição da cadeia de recompensas a usuários específicos. Defina as condições de personalização. A cadeia é exibida somente a usuários autorizados que cumprem as condições especificadas.
       • Exibição da cadeia de recompensas a usuários que não cumprem as condições. A cadeia é exibida somente se nenhuma cadeia de recompensas correspondente é encontrada para o usuário — por exemplo, se o usuário não está autorizado ou se seus atributos não correspondem a nenhuma cadeia personalizada.
11. Clique em Next.
12. Especifique o período de validade da cadeia de recompensas.
13. Você pode ativar a opção Set time limit e definir a data e horário de validade para a cadeia de recompensas.
14. Para redefinir automaticamente o progresso na cadeia de recompensas, marque a caixa de seleção Refresh user progress after the chain ends.
15. Se você deseja que a cadeia de recompensas seja renovada em um momento específico, ative a opção Make reward chain renewable e especifique o modo de atualização.

16. Selecione Create.

1. No seu projeto na Conta de Distribuidor, acesse LiveOps tools > Rewards.
2. Na fileira da cadeia desejada, selecione ••• e então Activate na lista suspensa.

Configuração via 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.

Exibição do sistema de recompensas

Exibição via construtor de sites

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.

Para exibir cadeias de recompensas no seu site:

1. No seu projeto na Conta de Distribuidor, acesse a seção Storefronts > Websites.
2. Selecione seu site e pressione Open Site Builder.
3. Na área principal do construtor, escolha um lugar onde você deseja adicionar um novo bloco e selecione Add block.
4. Escolha o bloco Reward system.
5. Na lista suspensa, escolha uma cadeia de recompensas.

6. Personalize o botão e cores do texto (opcional).
7. Para ver uma prévia da cadeia, selecione Preview no canto superior direito do construtor.

8. Para aplicar as alterações, publique seu site:
   1. No canto superior direito do construtor de sites, selecione Publish.
   2. Marque as caixas que ao lado das páginas que deseja publicar.
   3. Selecione Publish.

Exibição de especificados dos pontos de valor no construtor de sites

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.

Exibição das cadeias de recompensa via chamadas de API

1. Na interface do seu aplicativo, implemente os elementos para exibir etapas da cadeia de recompensas.
2. Implemente a lógica para trabalhar com cadeias usando as seguintes chamadas de API do lado do cliente do grupo Cadeias de recompensas e pontos de valor:

3. Garanta que os itens sejam corretamente concedidos ao usuário.

Configuração do clã de um usuário

Se você não estiver usando o construtor de sites, você precisa passar o clã do usuário nos atributos do usuário no Xsolla Login para a cadeia de recompensas do clã funcionar corretamente. Para fazer isso:

1. Defina o esquema de atributos no Xsolla 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. Para adicionar ou atualizar o atributo clan_id, use os métodos de atualização de atributos e passe a matriz attributes com o valor do clã clan_id no corpo da solicitação.

 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 você usar a autorização via Xsolla Login, chame a API Atualizar o clã do usuário atual para atualizar o clã do usuário. Se os atributos contiverem um novo clã, o usuário receberá qualquer recompensa não reivindicada da cadeia de recompensas do clã anterior, e a afiliação de clã dele será atualizada. Se o usuário costumava ser membro de um clã, mas hoje não faz mais parte de um, sua associação de clã será revogada. A resposta a esses métodos inclui as recompensas que o usuário já reivindicou.

Exibição de especificações na Web Shop

Depois de configurar o esquema do atributo, implemente passar os dados de 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    {
 9      "key": "clan_id"
10    }
11  ]
12}

Exibição de especificações via API

Você pode passar os valores de atributo atuais diretamente durante a autorização do usuário se você estiver usando a API Autenticar por ID personalizado.