Personalização de catálogo de itens

Esse tutorial mostra como:

• personalizar o catálogo usando atributos criados do seu lado (para parceiros que usam o Pay Station Access Token para autorizar os usuários)
• especificar as regras de validação de usuário em um JSON schema e adicionar atributos ao usuário no lado Xsolla (para parceiros que usam o Xsolla Login para autorizar usuários)
• criar regra de exibição de catálogo
• obter o catálogo de itens para um usuário com valores de atributos diferentes

Pré-requisitos

Antes de começar, certifique-se de que:

• Você criou um catálogo de itens de jogo ou chaves de jogo, para o qual a personalização será configurada.
• Você explorou a seção User attributes (para parceiros que usam o Xsolla Login para autorizar os usuários).
• Você adicionou usuários nas configurações do seu projeto Login na seção User database > Users, para os quais você pode adicionar atributos (para parceiros que usam o Xsolla Login para autorizar usuários).

Personalização usando Pay Station Access Token para autorizar usuários

Se você usa um Pay Station Access Token para autorizar usuários, você pode passar atributos ao obter o token. Nesse caso, faça o seguinte para configurar a personalização:

1. Crie atributos no seu sistema.
2. Adicione atributos aos usuários no seu sistema.
3. Implemente uma lógica para atualizar os valores de atributo quando eles forem alterados para um usuário no jogo.
4. Crie regras de exibição de catálogo com seus atributos.
5. Passe os atributos ao obter o Pay Station Access Token.
6. Use o token recebido nos métodos para solicitar o catálogo de itens.

Personalização usando o Xsolla Login para autorizar usuários

Se você usa o Xsolla Login para autorizar usuários, você precisa:

1. Criar um JSON schema para os atributos de usuário no lad da Xsolla e especificar os atributos dentro dele (opcional).

2. Adicione atributos aos usuários e atualize os valores de atributo usando a Login API.
3. Crie regras de exibição de catálogo com os atributos criados.
4. Implemente a obtenção do JWT de um usuário. Você pode encontrar uma lista de métodos para obter o JWT nesse exemplo.
5. Use o token recebido nos métodos para solicitar o catálogo de itens.

Há diversas maneiras de adicionar atributos a um usuário:

• Use métodos de atualização de atributo:
  • Atualize os atributos do usuário a partir do servidor
  • Atualize os atributos somente de leitura do usuário a partir do servidor

1. Use esses métodos para adicionar atributos a um usuário e atualize os valores do atributo. Para personalizar o catálogo, é necessário manter os valores de atributo atualizados: atualize os valores de atributo na Xsolla quando eles forem alterados para o usuário no jogo.

1. Exemplo: um usuário atinge um novo nível, conclui uma missão ou faz uma compra.

1. Você pode atualizar os valores de ambos atributos únicos e atributos múltiplos simultaneamente. A exceção são os atributos especificados como obrigatórios no JSON schema — sem especificar os valores de atributo obrigatórios, você não poderá chamar os métodos API de atualização de atributo.

• Passe os valores de atributo reais diretamente ao autorizar o usuário se você usar o método Auth by custom ID. Nesse método, você pode passar uma matriz com os valores atuais de atributos de usuário.

Exemplo de configuração de personalização

Esse exemplo mostra como configurar a personalização de catálogo: o item Conjunto de Cristal Médio é exibido apenas aos usuários que compraram o jogo MyTest Game.

Criando o schema de atributos

• Atributo “game” com o tipo “string” — o nome do jogo que o usuário está comprando. O atributo “game” é marcado como obrigatório. Não é possível chamar os métodos de atualização de atributo se você não passar o atributo “game”.

• Atributo “purchase_number” com o tipo “integer” — quantidade de compras do usuário.

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "Example",
	"description": "JSON Schema description.",
	"properties": {
		"game": {
			"description": "Name of the game played by a user.",
			"type": "string"
		},
		"purchase_number": {
			"description": "The number of purchases the user made.",
			"type": "integer"
		}
	},
	"additionalProperties": false,
	"required": [
		"game"
	],
	"type": "object"
}

Adição de atributos a um usuário

Adicione atributos a um usuário do banco de dados de usuários usando o método Update user’s read-only attributes from server.

No método Update user’s read-only attributes from server, você deve especificar:

• Token do servidor.
• Valores de atributo de usuário.
• user_id — o identificador de usuário especificado nas configurações do seu projeto Login na Conta de Distribuidor na seção User database > Users.
• publisher_id — ID de Comerciante especificado:
  • Na seção Company settings > Company.
  • No URL na barra de endereços do navegador em qualquer página da Conta de Distribuidor. O URL tem o seguinte formato: https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.
• publisher_project_id — ID de Projeto que você pode encontrar na sua Conta de Distribuidor próximo ao nome do projeto.

Obtenha o token do servidor preliminarmente usando o método Generate JWT.

Depois, prossiga ao método Update user’s read-only attributes from the server.

O corpo da solicitação com uma matriz de attributes tem o seguinte formato:

{
  "attributes": [
    {
      "key": "game",
      "permission": "private",
      "value": "MyTestGame"
    },
 {   
     "key": "purchase_number",
      "permission": "private",
      "value": "30"
    }

  ],
  "publisher_id": 000000,
  "publisher_project_id": 000000
}

Como resultado de executar a solicitação, o usuário que não tiver nenhum atributo agora tem atributos com os valores especificados:

Criando uma regra de exibição de catálogo

Configure uma regra para exibir o item Conjunto de Cristal Médio somente aos usuários que compraram o MyTestGame.

Para fazer isso:

1. Na Conta de Distribuidor, vá para Store > Catalog management > Catalog display rules.
2. Clique em Create rule e preencha os campos obrigatórios:
   1. chave de atributo no campo User attribute — game
   2. tipo — string
   3. operador de comparação — equal to
   4. valor — MyTestGame

3. Especifique o item que deve ser exibido se a condição for cumprida. No exemplo abaixo, o Conjunto de Cristal Médio é exibido para os usuários que possuem o MyTestGame.

4. Confira a regra, ative-a e salve-a.

Obtenção do Token

Obtenção do Xsolla Login JWT

• Auth by username and password
• Auth via social provider
• Passwordless auth by email
• Passwordless auth by phone number
• Auth via device ID
• Auth by custom ID
• E outros métodos para obter o token do usuário do grupo de métodos JWT ou OAuth.2.0

Obtenção do Pay Station Access Token

Obtenha o Pay Station Access Token com o atributo necessário. Para fazer isso, você precisa passar “game”: “MyTestGame” no objeto attributes no método Create token.

Exemplo de corpo de solicitação:

{
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 000001,
    "ui": {
      "size": "medium"
    }
  },
  "user": {
    "email": {
      "value": "email@example.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "attributes": {
      "game": "MyTestGame"
    }
  }
}

Obtendo o catálogo de itens

Obter o catálogo de itens usando o Xsolla Login JWT

Obtenha o catálogo de itens usando o token do usuário a qual você adicionou o atributo game com o valor MyTestGame. Para fazer isso, especifique o seguinte no método Get virtual items list:

• o JWT do usuário obtido no cabeçalho de autorização
• o ID do Projeto na Conta de Distribuidor como parâmetro de trajeto

A resposta inclui três itens:

• Chave do Império
• Pacote de cristais pequeno
• Conjunto de Cristal Médio, para o qual a regra de personalização foi configurada

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "OtherGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

O método Get virtual items list com o token obtido retorna dois itens: Chave do Império e Pacote de cristais pequeno. O Conjunto de Cristal Médio, que possui uma regra de personalização aplicado a ele, não é incluso na resposta.

Como comparação, agora passe o atributo game com o valor MyTestGame.

Essa é a matriz attributes no método Auth by custom ID para o usuário com o jogo MyTestGame:

"attributes": [
{
    "attr_type": "server",
    "key": "game",
    "permission": "private",
    "value": "MyTestGame",
    "read_only": true
 },
{
    "attr_type": "server",
    "key": "purchase_number",
    "permission": "private",
    "value": "30",
    "read_only": true
  }
]

Especifique o token obtido ao solicitar o catálogo de itens no método Get virtual items list.

Como resultado, o Conjunto de Cristal Médio será incluído na resposta:

Obtendo o catálogo de itens usando o Pay Station Access Token

Para obter o catálogo de itens personalizado, você precisa especificar o seguinte no método Get virtual items list:

• o Pay Station Access Token obtido no cabeçalho de autorização
• o ID do Projeto na Conta de Distribuidor como parâmetro de trajeto

A resposta inclui três itens:

• Chave do Império
• Pacote de cristais pequeno
• Conjunto de Cristal Médio, para o qual a regra de personalização foi configurada

Você pode testar a resposta ao obter o catálogo de itens se o usuário não possui o atributo game com o valor MyTestGame.

Quando você receber o Pay Station Access Token, exclua o objeto attributes e solicite o catálogo de itens novamente usando o método de lista Get virtual items. Agora, a resposta não incluirá o Conjunto de Cristal Médio.