Персонализация каталога товаров

Это руководство показывает, как:

• персонализировать каталог с помощью атрибутов, созданных на вашей стороне (для партнеров, которые используют Pay Station Access Token для авторизации пользователей);
• задать правила ввода атрибутов в виде JSON-схемы и добавить атрибуты пользователю на стороне Xsolla (для партнеров, которые используют Xsolla Login для авторизации пользователей);
• создать правило отображения каталога;
• получить каталог товаров для пользователя с разными значениями атрибутов.

Предварительные действия

Перед тем как начать, убедитесь, что:

• Вы создали каталог внутриигровых предметов или игровых ключей, для которых будет настраиваться персонализация.
• Вы ознакомились с разделом Атрибуты пользователей (для партнеров, которые используют Xsolla Login для авторизации пользователей).
• В настройках вашего варианта авторизации в разделе База пользователей > Пользователи добавлены пользователи, для которых вы сможете добавить атрибуты (для партнеров, которые используют Xsolla Login для авторизации пользователей).

Персонализация при использовании Pay Station Access Token для авторизации пользователей

Если вы используете Pay Station Access Token для авторизации пользователей, вы можете передать атрибуты при получении токена. В этом случае для персонализации вам потребуется:

1. Создать атрибуты в вашей системе.
2. Добавить атрибуты пользователям в вашей системе.
3. Реализовать в вашей системе логику обновления значений атрибутов, когда они меняются у пользователя в игре.
4. Создать правила отображения каталога с вашими атрибутами.
5. Передать атрибуты при получении Pay Station Access Token.
6. Полученный токен использовать в методах запроса каталога товаров.

Персонализация при использовании Xsolla Login для авторизации пользователей

Если вы используете Xsolla Login для авторизации пользователей вам потребуется:

1. Создать JSON-схему атрибутов пользователя на стороне Xsolla и указать в ней атрибуты (опционально).

2. Добавить атрибуты пользователям и обновлять значения атрибутов, используя Login API.
3. Создать правила отображения каталога с созданными атрибутами.
4. Реализовать получение JWT пользователя. Список методов получения JWT вы можете найти в примере.
5. Использовать полученный токен в методах запроса каталога товаров.

Есть несколько способов добавить атрибуты пользователю:

• Используйте методы обновления атрибутов:
  • Update user’s attributes from server
  • Update user’s read-only attributes from server

1. Используйте эти методы, чтобы добавить атрибуты пользователю, а также для обновления значений атрибутов. Для персонализации каталога необходимо поддерживать значения атрибутов в актуальном состоянии: обновляйте значения атрибутов в Xsolla, когда они меняются у пользователя в игре.

1. Пример: Пользователь достиг нового уровня, завершил квест или совершил покупку.

1. Вы можете обновлять значения как одного атрибута, так и нескольких атрибутов одновременно. Исключением являются атрибуты, которые указаны в JSON-схеме как обязательные — без указания значений обязательных атрибутов вы не сможете вызвать методы API обновления атрибутов.

• Передайте актуальные значения атрибутов непосредственно при авторизации пользователя, если вы используете метод Auth by custom ID. В данном методе вы можете передавать массив с актуальными значениями атрибутов пользователя.

Пример настройки персонализации

Данный пример показывает, как настроить персонализацию каталога: товар Medium crystal set отображается только пользователям, которые купили игру MyTestGame.

Создание схемы атрибутов

• Атрибут “game” с типом “string” — название игры, которую покупает пользователь. Атрибут “game” указан как обязательный. Вы не сможете вызвать методы обновления атрибутов, если не передадите атрибут “game”.

• Атрибут “purchase_number” с типом “integer” — количество покупок пользователя.

{
	"$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"
}

Добавление атрибутов пользователю

Добавьте атрибуты пользователю из базы пользователей с помощью метода Update user’s read-only attributes from server.

В методе Update user’s read-only attributes from server требуется указать:

• Серверный токен.
• Значения атрибутов пользователя.
• user_id — идентификатор пользователя, указанный в Личном кабинете в настройках проекта авторизации в разделе База пользователей > Пользователи.
• publisher_id — ID продавца указан:
  • В разделе Настройки компании > Компания.
  • Aдресной строке браузера на любой странице Личного кабинета. URL-адрес имеет вид https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.
• publisher_project_id — ID проекта в Личном кабинете, который указан под названием вашей игры.

Предварительно получите серверный токен, используя метод Generate JWT.

Затем перейдите к методу Update user’s read-only attributes from server.

Тело запроса с массивом attributes имеет следующий вид:

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

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

В результате выполнения запроса у пользователя, у которого не было атрибутов, появляются атрибуты с указанными значениями:

Создание правила отображения каталога

Задайте правило для отображения товара Medium crystal set только пользователям, которые купили игру MyTestGame.

Для этого:

1. В Личном кабинете перейдите в Store > Управление каталогом > Правила отображения каталога.
2. Нажмите Создать правило и заполните необходимые поля:
   1. ключ атрибута в поле Атрибут пользователя — game;
   2. тип — string;
   3. оператор сравнения — equal to;
   4. значение — MyTestGame.

3. Укажите товар, который будет отображаться в случае выполнения условия. В примере ниже указан Medium crystal set, который будет отображаться для пользователей с игрой MyTestGame.

4. Проверьте правило, активируйте его и сохраните.

Получение токена

Получение 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;
• и другие методы получения токена пользователя из группы методов JWT или OAuth.2.0.

Получение Pay Station Access Token

Получите Pay Station Access Token с нужным атрибутом. Для этого необходимо передать “game”: “MyTestGame” в объекте attributes в методе Create token.

Пример тела запроса:

{
  "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"
    }
  }
}

Получение каталога товаров

Получение каталога товаров с помощью Xsolla Login JWT

Получите каталог, используя токен пользователя, которому добавлен атрибут game со значением MyTestGame. Для этого в методе Get virtual items list необходимо указать:

• полученный JWT пользователя в заголовке авторизации;
• ID проекта в Личном кабинете в path-параметре.

В ответе приходит три товара:

• Empire Key;
• Small crystal pack;
• Medium crystal set, для которого настроено правило персонализации.

"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
  }
]

Метод Get virtual items list с полученным токеном возвращает два товара: Empire Key и Small crystal pack. Medium crystal set, на который действует персонализация, не приходит в ответе.

Для сравнения теперь передайте атрибут game со значением MyTestGame.

Массив attributes в Auth by custom ID для пользователя с игрой 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
  }
]

Укажите полученный токен при запросе каталога в методе Get virtual items list.

В ответе с данным токеном Medium crystal set приходит:

Получение каталога товаров с помощью Pay Station Access Token

Чтобы получить персонализированный каталог товаров, в методе Get virtual items list необходимо указать:

• полученнный Pay Station Access Token в заголовке авторизации;
• ID проекта в Личном кабинете в path-параметре.

В ответе приходит три товара:

• Empire Key;
• Small crystal pack;
• Medium crystal set, для которого настроено правило персонализации.

Вы можете проверить ответ при получении каталога товаров, если у пользователя нет атрибута game со значением MyTestGame.

При получении Pay Station Access Token удалите объект attributes и снова запросите каталог товаров методом Get virtual items list. В ответе Medium crystal set не придет.