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

Внутриигровой магазин

  • Руководство по интеграции

  • Возможности

  • Инструкции

  • Расширения

  • Справочники

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

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

    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. В ответе вернутся ID заказа и платежный токен. Заказу будет присвоен статус New.
    3. Откройте платежный интерфейс.

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

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

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

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

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

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

    1. Используйте метод покупки корзины Create order with all items from current cart. В ответе вернутся ID заказа и платежный токен. Заказу будет присвоен статус 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-режим). Тестирование вы можете выполнять с помощью тестовых карт и с любого аккаунта.

    Примечание

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

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

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

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

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

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

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

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

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

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

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

    WebSocket API

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

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

    1. Для того чтобы WebSocket-сервер и клиент могли идентифицировать сообщения со статусом заказа, сформируйте ID канала (порядок параметров важен): 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. Тело сообщения содержит ID заказа и его статус:

    Copy
    Full screen
    Small screen

    {
    "order_id": int,
    "status": string
    }
    

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

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

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

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

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

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

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

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