Criar cadeia de recompensas

Como funciona

O sistema de recompensa encoraja os usuários a fazer compras na loja usando moedas reais. Para cada compra, eles podem ganhar pontos de valor e progredir por uma cadeia de recompensas. Se os usuários fazem parte de clãs, a compra deles contribui pontos de valor para o clã inteiro.

Exemplo de uma cadeia de recompensas com pontos de valor ganhos por compra:

Glossário

Pré-requisitos

Certifique-se de que sua loja contém itens que os usuários podem comprar para ganhar pontos de valor.

Antes de criar uma cadeia de recompensas de clã, configure os clãs de usuários.

Criar pontos de valor

Para criar pontos de valor:

1. Abra seu projeto na Conta de Distribuidor e vá para a seção LiveOps > Canvas.

2. Na área da lista de pontos de valor, clique no ícone +.

3. Escolha um tipo de ponto de valor — Pontos de valor individuais ou Pontos de valor de clã. O tipo de ponto de valor é definido na etapa de criação e não pode ser alterado posteriormente.

4. Adicione uma imagem (opcional).

5. Insira um nome.

6. Insira um SKU único para o ponto de valor.

7. Clique em Next.

8. Atribua pontos de valor:

   1. Clique em Add affected item.

   2. Selecione os itens e especifique quantos pontos de valor os usuários recebem por comprar cada item.

   3. Clique em Select.

   Se sua loja ainda não contém itens, você pode salvar as configurações atuais e retornar a esta etapa mais tarde.

9. Clique em Next.

10. Verifique as configurações dos pontos de valor.

11. Clique em Create.

Criar cadeia de recompensas

Para criar uma cadeia de recompensas:

1. Abra seu projeto na Conta de Distribuidor e vá para a seção LiveOps > Canvas.
2. Prossiga para criar recompensas de uma das seguintes maneiras:
   1. Na barra de ferramentas, clique no ícone + e selecione Reward chain.
   2. Na área da lista de cadeias de recompensas, clique no ícone +.
   3. Abra o menu de contexto em qualquer lugar do canvas e selecione Reward chain.

3. Escolha um tipo de cadeia — Cadeia de recompensas individual ou Cadeia de recompensas de clã. O tipo de cadeia de recompensas é definido na etapa de criação e não pode ser alterado posteriormente.

4. Especifique os parâmetros básicos da cadeia:

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

5. Clique em Next.

6. Configure os pontos de valor — crie novos pontos de valor ou selecione entre os existentes.

7. Clique em Next.

8. Adicione uma recompensa para cada etapa da cadeia. Para adicionar uma recompensa para uma única etapa:

   1. Clique em Add new step.

   2. Selecione os itens que os usuários recebem como recompensa para esta etapa e especifique a quantidade para cada item.

   3. Clique em Add item.

9. Na lista de etapas, especifique a quantidade necessária de pontos de valor para reivindicar a recompensa. Os pontos de valor alocados para cada etapa subsequente devem ser maiores que os da anterior. O limite máximo é de 100.000 pontos de valor por etapa.

10. Para alterar a ordem das recompensas na cadeia, arraste a linha para a posição desejada usando o ícone ☰ (opcional).

11. Depois de adicionar as recompensas para cada etapa, clique em Next.

12. Especifique o período de validade da cadeia de recompensas: um fuso horário, data inicial e data final. Se você não quiser indicar o final do período de validade, marque a caixa No end date.

Observação

Para adicionar outro período de validade da cadeia de recompensas, clique em Add period. Se uma cadeia tem múltiplos períodos de validade, cada um deve ter uma data final. A cadeia termina no último segundo do minuto especificado. Por exemplo, se um horário de término estiver definido para 12:00, a cadeia ocorrerá até 12:00:59.

Se você usar os mesmos pontos de valor para múltiplas cadeias de recompensa, deixe pelo menos 15 minutos entre o término de um período da cadeia e o início do próximo. Os pontos de valor e o progresso das etapas são redefinidos por um trabalho em segundo plano que roda às :00, :15, :30 e :45 de cada hora (não exatamente no final do período). Se o próximo período começar antes de um desses horários, os usuários ainda podem ter seu saldo anterior. Se você quiser redefinir o progresso das etapas imediatamente, chame o método de API Redefinir cadeia de recompensas.

13. Para redefinir automaticamente o progresso na cadeia de recompensas, ative a opção Reset value points.

14. 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 cronograma de atualização.

15. Se você deseja personalizar a cadeia de recompensas:

    1. Ative a opção Personalized reward chain.

    2. Selecione uma das opções de exibição da cadeia:

       • Display to eligible users — neste caso, a cadeia é exibida apenas para usuários autorizados que atendem às condições especificadas.

       • Display to ineligible users — para tal cadeia, você não precisa especificar as condições de personalização — ela é aplicada por padrão. Isso significa que é exibida para usuários não autorizados, bem como em casos em que nenhuma cadeia de recompensas personalizada correspondente é encontrada para o usuário autorizado.

    3. Se você selecionar a opção Display to eligible users, especifique a condição:

       1. Especifique o tipo de atributo do usuário — string, número ou data.

       2. Selecione o atributo do usuário na lista suspensa.

       3. Selecione o operador de comparação.

       4. Especifique o valor do atributo do usuário.

    4. Para adicionar mais condições, clique em Add condition e preencha os campos exibidos (opcional).

16. Clique em Next.

17. Verifique a cadeia.

18. Para ativar a cadeia imediatamente (opcional), ative a opção Create in Active status.

19. Clique em Create.

Observação

Cadeias ativas não podem ser editadas. Para alterar as configurações de uma promoção, primeiro desative-a.

Você pode ativar ou desativar a cadeia das seguintes maneiras:

• Do cartão da cadeia de recompensas
• Da lista de cadeias de recompensas
• Enquanto edita a cadeia

Exibição do sistema de recompensas

Exibição via construtor de sites

Para garantir que o sistema de recompensas funcione corretamente, a autenticação do usuário deve ser configurada. Para usuários não autorizados, as cadeias de recompensa de clã e individuais são exibidas sem progresso.

Os usuários autorizados que não são membros de um clã veem somente a cadeia de recompensas individuais. As cadeias de recompensa de clã são exibidas 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. Se seu site incluir múltiplas páginas, selecione a que você precisa:
   1. Selecione o título da página atual no topo do construtor.
   2. Selecione a página necessária na lista suspensa.
4. Na área principal do construtor, escolha um lugar onde você deseja adicionar um novo bloco e selecione Add block.
5. Escolha o bloco Reward system.

6. Na lista suspensa, escolha uma cadeia de recompensas.

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

9. 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.

Especificações de configuração 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}

Especificações de configuração 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.