Внутриигровой магазин / Интеграция магазина в игру

Интеграция магазина в игру

После того как вы создали и настроили товары (виртуальные предметы, виртуальные валюты, бандлы, ключи) в Личном кабинете, добавьте магазин в вашу игру:

  1. Реализуйте отображение каталога товаров.
  2. Реализуйте логику продажи товаров.

Отображение каталога товаров

Примечание
Для работы с API Иксоллы вы можете использовать готовые методы SDK для игровых движков и платформ:

Реализуйте отображение каталога с помощью методов In-Game Store & Buy Button API:

ЗадачаМетод
Отобразить полный список виртуальных предметов, добавленных в ваш магазинGet virtual items list
Отобразить на клиенте список групп виртуальных предметов, доступных для продажиGet item groups list
Отобразить на клиенте список виртуальных валют, доступных для продажи в вашем магазинеGet virtual currency list
Отобразить полный список пакетов виртуальных валют, добавленных в ваш магазинGet virtual currency package list
Отобразить полный список бандлов виртуальных валют, добавленных в ваш магазинGet list of bundles

Продажа товаров

Вы можете продавать товары следующими способами:

  1. Быстрая покупка одного товара. В этом случае вы можете продавать один артикул товара, но в любом количестве. Например, 100 одинаковых зелий.
  2. Покупка корзины пользователя. В этом случае игрок предварительно наполняет корзину и может добавлять и убирать товары, изменять их количество в одном заказе.

Быстрая покупка

  1. Используйте метод Create order with specified item. В ответе вы получите токен.
  2. Откройте платежный интерфейс, используя полученный токен.

Примечание
Информация о скидке (персонализированной или связанной с покупкой) будет доступна пользователю только в платежном интерфейсе. Использование промокодов не предусмотрено.
Примечание
Для работы с API Иксоллы вы можете использовать готовые методы SDK для игровых движков и платформ:

Покупка корзины

Реализуйте логику:

  1. Наполнение корзины и получение токена:
    • На клиенте — если вы хотите самостоятельно реализовать корзину в своем приложении.
    • На сервере — если вы хотите использовать решение Иксоллы (методы In-Game Store & Buy Button API) для управления корзиной.
  2. Открытие платежного интерфейса.

Наполнение и покупка корзины на клиенте

Самостоятельно реализуйте логику добавления и удаления товаров в корзину. Также необходимо учитывать, что до вызова метода наполнения корзины у вас не будет информации о том, какие акции будут применены при покупке. Это означает, что итоговая стоимость и сведения о добавленных бонусных предметах будут неизвестны.

  1. После наполнения корзины игроком используйте метод Fill cart with items для наполнения корзины. В ответе вернется текущая информация о выбранных товарах — цены до и после применения скидок, бонусные товары.
  2. Используйте метод покупки корзины Create order with all items from current cart. В ответе вернутся идентификатор заказа и платежный токен. Заказу будет присвоен статус New.
  3. Откройте платежный интерфейс.

Примечание
Для работы с API Иксоллы вы можете использовать готовые методы SDK для игровых движков и платформ:

Наполнение и покупка корзины на сервере

Этот вариант наполнения корзины может занимать значительное время на настройку, поскольку каждое изменение корзины может сопровождаться вызовом большего количества методов API.

Выполните следующие действия:

  1. Измените корзину:

Примечание
Если вы хотите получить актуальное состояние корзины, используйте метод Get current user’s cart.

  1. Используйте метод покупки корзины Create order with all items from current cart. В ответе вернутся идентификатор заказа и платежный токен. Заказу будет присвоен статус New.
  2. Откройте платежный интерфейс.

Открытие платежного интерфейса

Чтобы оплатить товары, необходимо открыть платежный интерфейс с токеном, полученным в результате использования метода Create order with all items from current cart.

Реализуйте открытие платежного интерфейса одним из способов:

  • В новом окне. Для открытия платежного интерфейса в браузере используйте ссылку: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, где ACCESS_TOKEN — полученный при создании заказа токен.
  • В виджете. Используйте скрипт Xsolla PayStation Widget (файл README содержит инструкции по выполнению).

Тестирование платежей

Вы можете протестировать систему оплаты, используя тестовый режим (sandbox-режим). Тестирование вы можете выполнять с помощью тестовых карт и с любого аккаунта.

Примечание
После проведения первого реального платежа в силу вступает строгая политика платежей в тестовом режиме. Проведение платежей будет доступно только для пользователей, которые указаны в Личном кабинете в разделе Настройки компании > Пользователи.

Для включения или отключения тестового режима вам необходимо изменить значение параметра sandbox в теле запроса методов быстрой покупки и покупки корзины. По умолчанию тестовый режим выключен.

Получение статуса заказа пользователя

Существуют следующие способы получить статус заказа пользователя:

  1. На стороне сервера с помощью вебхуков.
  2. На стороне клиента с помощью WebSocket API или IGS&BB API.

Получение статуса заказа на стороне сервера с помощью вебхуков

После того как вы настроили обработку вебхуков на вашем сервере, вы можете использовать их для получения статуса заказа и информации о заказе.

Получение статуса заказа на стороне клиента с помощью WebSocket API или IGS&BB API

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

  1. WebSocket API.
  2. Простые запросы (Short-polling).

WebSocket API

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

Выполните следующие действия:

  1. Для того чтобы WebSocket-сервер и клиент могли идентифицировать сообщения со статусом заказа, сформируйте идентификатор канала (порядок параметров важен): Channel_id: order_id=$orderId&project_id=$projectId.
  2. Чтобы подписаться на нужный канал, подключитесь по протоколу WebSocket к URL-адресу: wss://store-ws.xsolla.com/sub/order/status?order_id=$orderId&project_id=$projectId. Тело сообщения содержит идентификатор заказа и его статус:

Copy
Full screen
Small screen
{
"order_id": int,
"status": string
}

Возможны следующие статусы заказа:

  • New — заказ создан и еще не оплачен.
  • Paid — заказ оплачен.
  • Done — заказ полностью доставлен (в том числе отправлены все чеки, выполнены доставки на стороне Иксоллы, внешних платформ и т.д.).
  • Canceled — заказ отменен, оплата возвращена пользователю.

Рекомендуемое ожидание ответа через веб-сокет — 5 минут. После этого (или если с веб-сокетом есть какие-либо проблемы), рекомендуется использовать простые запросы.

Простые запросы (short-polling)

Чтобы получить детальную информацию о товарах в заказе после перехода в нужный статус, используйте API-метод Get order.

Примечание
Используется периодический опрос статуса заказа — простой HTTP-запрос, который получает текущий статус заказа, а также информацию по нему. Рекомендуемая задержка между запросами — 3 секунды.
Прогресс интеграции
Спасибо за обратную связь!
Последнее обновление: 30 ноября 2022

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

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