In-Game Store / Персонализация каталога товаров
  На главную

In-Game Store

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

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

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

Примечание
Вы можете:
  • Cоздать JSON-схему атрибутов пользователя и передавать только атрибуты, которые указаны в JSON-схеме. Для этого в JSON-схеме в поле additionalProperties установите значение false. Автоматически будет осуществляться проверка указанных атрибутов.
  • Cоздать JSON-схему атрибутов пользователя и передавать как атрибуты, указанные в JSON-схеме, так и дополнительные атрибуты, которые не указаны в JSON-схеме. Для этого в JSON-схеме в поле additionalProperties установите значение true. Автоматически будет осуществляться проверка только указанных в JSON-схеме атрибутов.
  • Не создавать JSON-схему атрибутов пользователя. В этом случае вы можете передавать любые атрибуты. Проверка атрибутов не будет осуществляться.
Для персонализации каталога товаров мы рекомендуем указать атрибуты и их типы в JSON-схеме в объекте properties, чтобы обеспечить автоматическую проверку ключей и значений атрибутов.

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

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

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

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

  1. Вы можете обновлять значения как одного атрибута, так и нескольких атрибутов одновременно. Исключением являются атрибуты, которые указаны в JSON-схеме как обязательные — без указания значений обязательных атрибутов вы не сможете вызвать методы API обновления атрибутов.
Примечание
  • Передайте актуальные значения атрибутов непосредственно при авторизации пользователя, если вы используете метод Auth by custom ID. В данном методе вы можете передавать массив с актуальными значениями атрибутов пользователя.
Примечание
Рекомендуем создать серверные атрибуты, доступные только для чтения. Для этого передайте значения параметров “attr_type”: “server” и “read_only”: “true”.

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

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

Примечание
Названия Medium crystal set и MyTestGame приведены для примера. Вам следует настроить персонализацию каталога, используя товары и атрибуты в вашем проекте.
Далее рассмотрены варианты с созданием атрибутов на стороне Xsolla (авторизация пользователей через Xsolla Login) и на стороне партнера (авторизация через Pay Station Access Token). Для варианта с Pay Station Access Token вы сразу можете перейти к созданию правила отображения каталога.

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

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

Пример схемы:
Copy
Full screen
Small screen

{
	"$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 различаются в разных продуктах:

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


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

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

Copy
Full screen
Small screen
{
  "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. В Личном кабинете перейдите в Магазин > Управление каталогом > Правила отображения каталога.
  2. Нажмите Создать правило и заполните необходимые поля:
    1. ключ атрибута в поле Атрибут пользователяgame;
    2. тип — string;
    3. оператор сравнения — equal to;
    4. значение — MyTestGame.
  1. Укажите товар, который будет отображаться в случае выполнения условия. В примере ниже указан Medium crystal set, который будет отображаться для пользователей с игрой MyTestGame.
  1. Проверьте правило, активируйте его и сохраните.

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

Получение Xsolla Login JWT

Получите токен пользователя, которому был добавлен атрибут game со значением MyTestGame.
 Вы можете получить Xsolla Login JWT как после успешной авторизации пользователя на клиенте, так и на стороне сервера без участия пользователя. Используйте один из множества способов авторизации, которые предлагает Xsolla Login:

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

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

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

Copy
Full screen
Small screen

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

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

Для получения каталога товаров вызовите метод Get virtual items list, в котором для авторизации используется Xsolla Login User JWT или Pay Station Access Token.

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

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

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

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


Вы можете проверить ответ при получении каталога товаров, если значение атрибута не совпадает с указанным в правиле. Для тестирования вы можете передать атрибуты непосредственно при получении токена методом Auth by custom ID.
Примечание
Подходит только для пользователей, авторизованных с помощью Auth by custom ID.
Получите JWT пользователя, используя Auth by custom ID, и в массиве attributes передайте атрибут game со значением OtherGame:
Copy
Full screen
Small screen
"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:

Copy
Full screen
Small screen

"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 необходимо указать:

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

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


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

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

Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Оценить страницу
Оценить страницу
Что может сделать страницу еще лучше?

В другой раз

Спасибо за обратную связь!
Последнее обновление: 17 апреля 2024

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Сообщите о проблеме
Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
Укажите email-адрес, чтобы мы могли связаться с вами
Спасибо за обратную связь!