Персонализация каталога товаров
Это руководство показывает, как:
- персонализировать каталог с помощью атрибутов, созданных на вашей стороне (для партнеров, которые используют Pay Station Access Token для авторизации пользователей);
- задать правила ввода атрибутов в виде JSON-схемы и добавить атрибуты пользователю на стороне Xsolla (для партнеров, которые используют Xsolla Login для авторизации пользователей);
- создать правило отображения каталога;
- получить каталог товаров для пользователя с разными значениями атрибутов.
Предварительные действия
Перед тем как начать, убедитесь, что:
- Вы создали каталог внутриигровых предметов или игровых ключей, для которых будет настраиваться персонализация.
- Вы ознакомились с разделом Атрибуты пользователей (для партнеров, которые используют Xsolla Login для авторизации пользователей).
- В настройках вашего варианта авторизации в разделе База пользователей > Пользователи добавлены пользователи, для которых вы сможете добавить атрибуты (для партнеров, которые используют Xsolla Login для авторизации пользователей).
Персонализация при использовании Pay Station Access Token для авторизации пользователей
Если вы используете Pay Station Access Token для авторизации пользователей, вы можете передать атрибуты при получении токена. В этом случае для персонализации вам потребуется:
- Создать атрибуты в вашей системе.
- Добавить атрибуты пользователям в вашей системе.
- Реализовать в вашей системе логику обновления значений атрибутов, когда они меняются у пользователя в игре.
- Создать правила отображения каталога с вашими атрибутами.
- Передать атрибуты при получении Pay Station Access Token.
- Полученный токен использовать в методах запроса каталога товаров.
Персонализация при использовании Xsolla Login для авторизации пользователей
Если вы используете Xsolla Login для авторизации пользователей вам потребуется:
- Создать JSON-схему атрибутов пользователя на стороне Xsolla и указать в ней атрибуты (опционально).
- Cоздать JSON-схему атрибутов пользователя и передавать только атрибуты, которые указаны в JSON-схеме. Для этого в JSON-схеме в объекте
additionalProperties
установите значениеfalse
. Автоматически будет осуществляться проверка указанных атрибутов. - Cоздать JSON-схему атрибутов пользователя и передавать как атрибуты, указанные в JSON-схеме, так и дополнительные атрибуты, которые не указаны в JSON-схеме. Для этого в JSON-схеме в поле
additionalProperties
установите значениеtrue
. Автоматически будет осуществляться проверка только указанных в JSON-схеме атрибутов. - Не создавать JSON-схему атрибутов пользователя. В этом случае вы можете передавать любые атрибуты. Проверка атрибутов не будет осуществляться.
properties
, чтобы обеспечить автоматическую проверку ключей и значений атрибутов.- Добавить атрибуты пользователям и обновлять значения атрибутов, используя Login API.
- Создать правила отображения каталога с созданными атрибутами.
- Реализовать получение JWT пользователя. Список методов получения JWT вы можете найти в примере.
- Использовать полученный токен в методах запроса каталога товаров.
Есть несколько способов добавить атрибуты пользователю:
- Используйте методы обновления атрибутов:
- Используйте эти методы, чтобы добавить атрибуты пользователю, а также для обновления значений атрибутов. Для персонализации каталога необходимо поддерживать значения атрибутов в актуальном состоянии: обновляйте значения атрибутов в Xsolla, когда они меняются у пользователя в игре.
- Пример: Пользователь достиг нового уровня, завершил квест или совершил покупку.
- Вы можете обновлять значения как одного атрибута, так и нескольких атрибутов одновременно. Исключением являются атрибуты, которые указаны в JSON-схеме как обязательные — без указания значений обязательных атрибутов вы не сможете вызвать методы API обновления атрибутов.
- Мы рекомендуем использовать метод Update user’s read-only attributes from server для работы с атрибутами пользователя. Данный метод позволяет создать атрибуты, значения которых пользователь не может менять.
- Если вы используете решение Web Shop с аутентификацией через ID пользователя, вы можете передавать актуальные значения атрибутов в вебхуке при авторизации пользователя.
- Передайте актуальные значения атрибутов непосредственно при авторизации пользователя, если вы используете метод Auth by custom ID. В данном методе вы можете передавать массив с актуальными значениями атрибутов пользователя.
“attr_type”: “server”
и “read_only”: “true”
.Пример настройки персонализации
Данный пример показывает, как настроить персонализацию каталога: товар Medium crystal set отображается только пользователям, которые купили игру MyTestGame.
Создание схемы атрибутов
Добавьте схему с атрибутами, соответствующими названию игры и количеству покупок. Для этого укажите в схеме:- Атрибут
“game”
с типом“string”
— название игры, которую покупает пользователь. Атрибут“game”
указан как обязательный. Вы не сможете вызвать методы обновления атрибутов, если не передадите атрибут“game”
. Атрибут
“purchase_number”
с типом“integer”
— количество покупок пользователя.
- json
{
"$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 проекта в Личном кабинете, который указан под названием вашей игры.
Обратите внимание, что названия параметров в методах API различаются в разных продуктах:
- project_id — ID проекта в Личном кабинете при работе с IGS API.
- publisher_project_id — ID проекта в Личном кабинете при работе с Login API.
- projectId — ID проекта Авторизации в Личном кабинете при работе с Login API.
Предварительно получите серверный токен, используя метод Generate JWT.
Затем перейдите к методу Update user’s read-only attributes from server.
Тело запроса с массивом
- json
{
"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.
Для этого:
- В Личном кабинете перейдите в Store > Управление каталогом > Правила отображения каталога.
- Нажмите Создать правило и заполните необходимые поля:
- ключ атрибута в поле Атрибут пользователя —
game
; - тип —
string
; - оператор сравнения —
equal to
; - значение —
MyTestGame
.
- ключ атрибута в поле Атрибут пользователя —
- Укажите товар, который будет отображаться в случае выполнения условия. В примере ниже указан Medium crystal set, который будет отображаться для пользователей с игрой MyTestGame.
- Проверьте правило, активируйте его и сохраните.
Получение токена
Получение Xsolla Login JWT
Получите токен пользователя, которому был добавлен атрибутgame
со значением MyTestGame
.Вы можете получить Xsolla Login JWT как после успешной авторизации пользователя на клиенте, так и на стороне сервера без участия пользователя. Используйте один из множества способов авторизации, которые предлагает Xsolla Login:
- 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”
в объекте
Пример тела запроса:
- json
{
"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 User JWT или Pay Station Access Token.Получение каталога товаров с помощью Xsolla Login JWT
Получите каталог, используя токен пользователя, которому добавлен атрибут game
со значением MyTestGame
. Для этого в методе Получение списка виртуальных предметов необходимо указать:
- полученный JWT пользователя в заголовке авторизации;
- ID проекта в Личном кабинете в path-параметре.
В ответе приходит три товара:
- Empire Key;
- Small crystal pack;
- Medium crystal set, для которого настроено правило персонализации.
Вы можете проверить ответ при получении каталога товаров, если значение атрибута не совпадает с указанным в правиле. Для тестирования вы можете передать атрибуты непосредственно при получении токена методом Auth by custom ID.
game
со значением OtherGame
:- json
"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
}
]
Метод Получение списка виртуальных предметов с полученным токеном возвращает два товара: Empire Key и Small crystal pack. Medium crystal set, на который действует персонализация, не приходит в ответе.
Для сравнения теперь передайте атрибут game
со значением MyTestGame
.
Массив MyTestGame
:
- json
"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
}
]
Укажите полученный токен при запросе каталога в методе Получение списка виртуальных предметов.
В ответе с данным токеном Medium crystal set приходит:
Получение каталога товаров с помощью Pay Station Access Token
Чтобы получить персонализированный каталог товаров, в методе Получение списка виртуальных предметов необходимо указать:
- полученнный Pay Station Access Token в заголовке авторизации;
- ID проекта в Личном кабинете в path-параметре.
В ответе приходит три товара:
- Empire Key;
- Small crystal pack;
- Medium crystal set, для которого настроено правило персонализации.
Вы можете проверить ответ при получении каталога товаров, если у пользователя нет атрибута game
со значением MyTestGame
.
При получении Pay Station Access Token удалите объект
Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.