Настройка продажи игровых ключей

Buy Button позволяет монетизировать игры через сайт самой игры, продавая за реальную или виртуальную валюту игровые ключи.

Продажа игровых ключей возможна по прямой ссылке, через интерфейс магазина или через виджет.

ТоварСпособ продажи
Одна копия игры (игровой ключ).Прямая ссылка, виджет или интерфейс магазина. При продаже через интерфейс магазина используйте метод быстрой покупки без создания корзины.
Несколько копий игры (игровых ключей) или разные игры в составе корзины.Интерфейс магазина. Используйте Site Builder или интегрируйте In-Game Store & Buy Button API.

Вы можете продавать игровые ключи неавторизованным и авторизованным пользователям.

Использование авторизации позволяет:

Вы можете авторизовывать пользователей с помощью продукта Login или вашей собственной системы авторизации. Подробная информация о настройке приведена в инструкции.

Для открытия платежного интерфейса используется ссылка:

Copy
Full screen
Small screen
https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}
Примечание

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

Для тестирования оплаты используйте тестовое окружение, добавив в ссылку параметр mode=sandbox.

Добавьте в ссылку следующие данные:

  • YOUR-ITEM-TYPE — тип товара:
    • game — игра; game_key — игра на конкретной платформе.
    • bundle — бандл.
  • YOUR-PROJECT-ID — ID проекта из раздела Настройки проекта > Общие настройки > ID проекта в Личном кабинете.
  • YOUR-ITEM-SKU — артикул пакета игровых ключей. Для продажи игры на конкретной платформе необходимо получить артикул с помощью запроса Get games list (как правило, этот артикул выглядит как unit_name_drm_sku).

  • Внешний вид платежного интерфейса: тема (темная — dark или светлая — default), размер и другие параметры. Укажите в URL ссылки параметр ui_settings и в качестве значения передайте JSON-объект settings.ui в кодировке Base64. Пример URL с настройками UI:
Copy
Full screen
Small screen
https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&ui_settings=ewoJCQkic2l6ZSI6ICJzbWFsbCIsCgkJCSJ0aGVtZSI6ICJkYXJrIgoJCX0=
  • Токен для передачи информации о пользователе. Используется только при продаже игровых ключей для авторизованных пользователей. Формируется в зависимости от типа аутентификации. Пример URL с токеном:
Copy
Full screen
Small screen
https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&xsolla_login_token={ACCESS_TOKEN}
Примечание
При проведении платежа сервер Xsolla отправляет запрос на URL-адрес вебхука, чтобы удостовериться, что пользователь существует в игре. Чтобы избежать ошибок при тестировании оплаты, перейдите в Личный кабинет > Настройки проекта > Вебхуки и установите переключатель в положение Выкл. Если вы хотите использовать вебхуки, реализуйте успешную обработку вебхука Проверка существования пользователя.
  1. Пример URL-адреса для тестирования:
Copy
Full screen
Small screen
https://purchase.xsolla.com/pages/buy?type={YOUR-ITEM-TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR-ITEM-SKU}&mode=sandbox

Продажа через интерфейс магазина

Вы можете продавать игровые ключи через интерфейс магазина. Для создания магазина вы можете:

Для продажи пакетов игровых ключей, используя In-Game Store & Buy Button API:

  1. Для отображения каталога используйте метод Get games list.
  2. Реализуйте покупку игровых ключей:

Чтобы методы работали корректно, выберите подходящий способ аутентификации пользователей.
Примечание
При продаже игры через In-Game Store & Buy Button API необходимо реализовать на клиенте выбор конкретной платформы. В качестве артикула необходимо передавать значение параметра items.unit_items.sku из запроса на получение списка игр.

Продажа через виджет

Вы можете добавить виджет для продажи игровых ключей на свою страницу и кастомизировать его. Чтобы скопировать код виджета перейдите в раздел Кастомизация виджета после создания пакета ключей в Личном кабинете.

Если игра продается на одной платформе, в виджете будет указана цена игры на этой платформе.

Пример: Купить сейчас за $10.

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

Пример: Купить от $10.

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

Вы также можете отобразить в виджете цену на конкретной платформе, указав название платформы в параметре drm.

Пример кода виджета:

Copy
Full screen
Small screen
    <div id="xsolla-buy-button-widget"></div>
          <script>
              var options = {
                  project_id: "101010",
                  sku: "my_key",
                  user: {
                      auth: "9qs9VyCIQQXBlzJQcfETIKWZDvhi4Sz1"
                  drm: "steam",
                  item_type: "unit",
                  api_settings: {
                      sandbox: true,
                  },
                  widget_ui: {
                      target_element: "#xsolla-buy-button-widget",
                      theme: {
                          foreground: "green",
                          background: "light"
                      },
                  },
    
                 payment_widget_ui: {
                      lightbox: {
                          height: '700px',
                          spinner: 'round'
                      }
                }
              };
              var s = document.createElement('script');
              s.type = "text/javascript";
              s.async = true;
              s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.8/widget.min.js";
              s.addEventListener('load', function (e) {
                  var widgetInstance = XBuyButtonWidget.create(options);
              }, false);
              var head = document.getElementsByTagName('head')[0];
              head.appendChild(s);
          </script>
          <style>
              #xsolla-buy-button-widget {
    
              /* place code for button positioning here */
                margin: 10px  
              }
    
              /* Styles the button itself */
              .x-buy-button-widget.x-buy-button-widget__tiny
                .x-buy-button-widget-payment-button {
                background-color: #ff005b;
                color: black;
              }     
          </style>
    
    Примечание
    Параметры виджета

    ПараметрТипОписание
    project_id
    integerID проекта, в который загружены игровые ключи или бандлы с игровыми ключами, внутриигровые товары или бандлы с товарами.
    item_type
    arrayТип предмета. Может принимать значения virtual_good, virtual_currency, game_key, unit. Тип unit используется, когда есть несколько платформ распространения игры.
    sku
    stringУникальный ID предмета.
    drm
    stringАртикул платформы распространения игры, например, steam. Позволяет отобразить цену на конкретной платформе.
    api_settings
    stringНастройки для выбора окружения и хоста:
    • host — хост для выполнения запросов. Значение по умолчанию — store.xsolla.com.
    • api_host — хост для выполнения запросов API. Значение по умолчанию — store.xsolla.com/api.
    • sandbox — установите значение true, чтобы протестировать процесс оплаты. Для обработки платежей будет использоваться sandbox-secure.xsolla.com вместо secure.xsolla.com (см. Тестирование процесса оплаты).
    user
    arrayМассив с данными о пользователе.
    user.auth
    stringАвторизационный токен пользователя: JSON Web Token или Pay Station access token.
    user.locale
    stringЛокаль пользователя. Определяет язык текста кнопки покупки и платежного интерфейса. Используется двубуквенный код языка по ISO_639-1.
    widget_ui.theme
    objectЦветовая тема виджета, определяющая его внешний вид. Может принимать значения {foreground:[‘blue’,‘red’,‘green’,‘gold’], background:[’light’,‘dark’]}.
    widget_ui.template
    stringШаблон. Возможные значения:
    • standard (по умолчанию) — изображение, название игры и стилизованная кнопка;
    • simple — только кнопка без применения стилей.
    widget_ui.target_element
    stringЭлемент страницы, на котором должен отображаться виджет (должен использоваться селектор jQuery, например, #widget-example). Обязательный.

    Параметры, определяющие внешний вид интерфейса оплаты

    ПараметрТипОписание
    payment_ui
    objectПараметры внешнего вида платежного интерфейса.
    payment_widget_ui
    objectОбъект с параметрами, которые определяют внешний вид платежного интерфейса.
    payment_widget_ui.lightbox
    objectОбъект с опциями модального окна, в котором открывается платежный интерфейс.
    lightbox.width
    stringШирина lightbox. Значение по умолчанию null. Если установлено значение null, ширина lightbox соответствует ширине платежного интерфейса.
    lightbox.height
    stringВысота lightbox. Значение по умолчанию 100%. Если установлено значение null, высота lightbox соответствует высоте платежного интерфейса.
    lightbox.zIndex
    integerСвойство, отвечающее за положение объекта, по умолчанию 1000.
    lightbox.overlayOpacity
    integerНепрозрачность подложки виджета (0 — полностью прозрачная, 1 — полностью непрозрачная). Значение по умолчанию — 60% (.6).
    lightbox.overlayBackground
    stringФон для верхнего слоя, по умолчанию #000000.
    lightbox.contentBackground
    stringФон фрейма, по умолчанию #ffffff. Обратите внимание, что настройка влияет только на фон фрейма lightbox и не меняет фон окна платежного интерфейса.
    lightbox.spinner
    stringТип прелоадера, может принимать значение xsolla или round, по умолчанию xsolla.
    lightbox.spinnerColor
    stringЦвет прелоадера.
    payment_widget_ui.childWindow
    objectНастройки дочернего окна, в котором открывается платежный интерфейс. Работает для мобильной версии.
    payment_widget_ui.childWindow.target
    stringСвойство, определяющее, где должно быть открыто дочернее окно. Может принимать значения _blank, _self, _parent. Значение по умолчанию — _blank.

    Методы виджета

    • var widgetInstance = XBuyButtonWidget.create(options) — создает экземпляр виджета и отображает его на странице.
    • widgetInstance.on(event, handler) — привязывает функцию обработчика событий к виджету.
      • event (string) — тип события.
      • handler (function) — функция, которая будет выполняться при срабатывании события.
    • widgetInstance.off(event, handler) — удаляет обработчик событий.
      • event (string) — тип события.
      • handler (function) — функция обработчика, ранее привязанная к событию.

    Список событий:

    ПараметрОписание
    initИнициализация виджета.
    openОткрытие виджета.
    loadСобытие после загрузки платежного интерфейса.
    closeСобытие после закрытия платежного интерфейса.
    statusСобытие, когда пользователь попадает на страницу статуса.
    status-invoiceСобытие, когда пользователь попадает на страницу статуса, но платеж еще не завершен.
    status-deliveringСобытие, когда пользователь попадает на страницу статуса, платеж завершен, мы прислали оповещение о платеже.
    status-doneСобытие, когда пользователь попадает на страницу статуса, платеж успешно зачислен.
    status-troubledСобытие, когда пользователь попадает на страницу статуса, но платеж не прошел.

    Вы можете получить доступ к списку событий, используя объект XBuyButtonWidget.eventTypes.

    Кастомизация кнопки

    1. Откройте проект в Личном кабинете.
    2. В боковом меню нажмите Магазин.
    3. В панели Игровые ключи нажмите Настроить.
    4. Выберите нужный вам игровой ключ и перейдите на вкладку Кастомизация виджета.
    Примечание
    Если игровых ключей нет, создайте их.
    1. В блоке Кастомизировать выберите цвет фона.
    Примечание
    Также вы можете задать объекту theme свойство background с пустым значением.
    1. Код при добавлении на страницу наследует стили. Чтобы их переопределить, добавьте стили, приведенные ниже.
    Внимание
    Рекомендуется добавить стили в тег style под тегом script, который вы получили на вкладке Кастомизация виджета для приоритета стилей виджета.
    Copy
    Full screen
    Small screen
    /* This should be used for button positioning but note this technically repositions the entire widget */
    #xsolla-buy-button-widget {
      /* place code for button positioning here */
    }
    
    /* Styles the button itself */
    .x-buy-button-widget.x-buy-button-widget__tiny
      .x-buy-button-widget-payment-button {
      background-color: #ff005b;
      color: black;
    }
    
    /* Button on hover */
    .x-buy-button-widget.x-buy-button-widget__tiny
      .x-buy-button-widget-payment-button:hover {
      background-color: #ff005b;
    }
    
    /* The following are style overrides to leave you with just the button */
    
    /* space immediately surrounding button */
    .x-buy-button-widget-button-block.x-buy-button-widget-button-block__light {
      background-color: white;
    }
    
    /* space above button (including game title area) */
    .x-buy-button-widget.x-buy-button-widget__tiny
      .x-buy-button-widget-game-logo {
      height: 200px;
      background-image: none !important;
      background-color: white;
    }
    
     /* Game title (located right above button) */
    .x-buy-button-widget-game-name.x-buy-button-widget-game-name__light {
      display: none !important;
    }
    
    Внимание
    • Важно вставить скопированный код виджета, поскольку приведенные выше имена ID или классов и сам фрагмент кода используются вместе с ним (шаг 5).
    • Вы также можете скопировать приведенный выше код, но, возможно, его придется адаптировать под ваши потребности. Комментарии к коду (строки 1, 3, 5, 11, 16, 18, 22, 29) помогут определить зависимости для каждого CSS-правила и для будущих стилей. Например, если вы хотите, чтобы у вас осталась только кнопка (а не весь виджет), вам нужно заменить фоновый цвет вашей страницы в местах, где цвет задан как white — в строках 20 и 27.

    Как создать несколько кнопок или артикулов

    Используйте Xsolla Pay2Play Widget Simple Integration 4 buttons, чтобы получить примеры кода для создания нескольких кнопок.

    Структура этого кода аналогична коду виджета Buy Button. Пример миграции:

    Copy
    Full screen
    Small screen
    <div id="xsolla-buy-button-widget"></div>
    <div id="xsolla-buy-button-widget-2"></div>
        <script>
          var options = {
            project_id: "191204",
            sku: "789",
            item_type: "unit",
            api_settings: {
              sandbox: false,
            },
            widget_ui: {
              target_element: "#xsolla-buy-button-widget",
              theme: {
                foreground: "gold",
                background: "",
              },
            },
            payment_widget_ui: {
              lightbox: {
                height: "700px",
                spinner: "round",
              },
            },
          };
          // options for second buy button - note the different SKU and target_element
          var options2 = {
            project_id: "191204",
            sku: "123",
            item_type: "unit",
            api_settings: {
              sandbox: false,
            },
            widget_ui: {
              target_element: "#xsolla-buy-button-widget-2",
              theme: {
                foreground: "gold",
                background: "",
              },
            },
            payment_widget_ui: {
              lightbox: {
                height: "700px",
                spinner: "round",
              },
            },
          };
          var s = document.createElement("script");
          s.type = "text/javascript";
          s.async = true;
          s.src = "https://cdn.xsolla.net/embed/buy-button/3.1.4/widget.min.js";
    
    // one event listener per widget instance. repeat for more buttons, passing in different SKUs
          s.addEventListener(
            "load",
            function (e) {
              var widgetInstance = XBuyButtonWidget.create(options);
            },
            false
          );
          s.addEventListener(
            "load",
            function (e) {
              var widgetInstance2 = XBuyButtonWidget.create(options2);
            },
            false
          );
          var head = document.getElementsByTagName("head")[0];
          head.appendChild(s);
        </script>
    
    Внимание
    • Строки 1 и 2 содержат div для каждой кнопки. У каждого div есть свой уникальный ID.
    • Объект с именем options2 содержит параметры для второй кнопки (начиная со строки 26). У вас будет набор таких объектов options, аналогично приведенным выше, для каждой кнопки Купить. Обратите внимание на разные sku (строка 28) и target_element (строка 34, указывающая на div в строке 2).
    Была ли статья полезна?
    Спасибо!
    Что может сделать страницу еще лучше? Сообщение
    Жаль, что так произошло
    Расскажите, почему статья не была полезна. Сообщение
    Спасибо за обратную связь!
    Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
    Оценить страницу
    Оценить страницу
    Что может сделать страницу еще лучше?

    В другой раз

    Спасибо за обратную связь!

    Продолжить чтение

    Последнее обновление: 22 января 2024

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

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