Подключите Buy Button для кастомной формы оплаты

Почему это важно

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

Теперь можно размещать кнопки, баннеры, сообщения и другие элементы, которые перенаправляют пользователей напрямую из игры к оплате товара в браузере (в ваш Web Shop или платежный интерфейс) в один клик, без риска нарушить правила Apple.

Интеграция Buy Button через Headless checkout подходит вам, если вы хотите настроить кастомный платежный интерфейс и создать уникальный пользовательский опыт. Этот вариант интеграции позволяет пользователям перейти из игры к оплате покупки в браузере с помощью широкого выбора способов оплаты, включая оплату в один клик с помощью Apple Pay, что обеспечивает быстрый и привычный сценарий оплаты на мобильных устройствах.

Headless checkout — это решение для приема платежей, основанное на архитектурном подходе headless-приложений, функциональность которых доступна по API. Такой подход предполагает отделение серверной части и бизнес-логики от пользовательского интерфейса.

Чтобы использовать Headless checkout в игровых iOS-приложениях:

1. Создайте собственный магазин.
2. Интегрируйте Headless checkout в ваш магазин.
3. Добавьте ссылку в игру, которая будет перенаправлять пользователей в ваш магазин.

Если вам нужно быстрое low-code решение, рассмотрите интеграцию на основе Xsolla Web Shop.

Если вы используете собственный Web Shop не на базе Xsolla Site Builder и заинтересованы в интеграции готового платежного интерфейса в свою игру, вы можете использовать интеграцию через Xsolla Mobile SDK.

Как это работает

Cценарий пользователя:

1. Пользователь запускает игру на iOS-устройстве.
2. Пользователь нажимает кнопку покупки рядом с нужным товаром.
3. Ваш магазин открывается в веб-браузере. Чтобы обеспечить непрерывный пользовательский опыт, реализуйте сквозную авторизацию пользователя.
4. Пользователь выбирает товар и совершает покупку, не покидая магазин.
5. Пользователь перенаправляется обратно в игровое приложение после успешной оплаты.
6. Приложение получает подтверждение покупки через вебхук.

Сценарий интеграции

1. Создайте проект в Личном кабинете и подпишите лицензионное соглашение с Xsolla.
2. Создайте каталог товаров.
3. Реализуйте серверное взаимодействие: создайте токен и настройте вебхуки.
4. Установите SDK.
5. Интегрируйте SDK на стороне приложения.
6. Добавьте в вашу игру ссылку, которая будет перенаправлять пользователя в ваш магазин, в котором интегрирован Headless checkout.

Регистрация в Личном кабинете и создание проекта

Личный кабинет — основной инструмент для настройки возможностей Xsolla, а также для работы с аналитикой и транзакциями.

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

Чтобы подписать соглашение, в Личном кабинете перейдите в раздел Договоры и налоги > Договоры и заполните форму.

Создание каталога товаров

В экосистеме Xsolla внутриигровые покупки (IAP) представлены в виде виртуальных предметов. Каждый предмет имеет название, описание, артикул (SKU) и цену. Чтобы настроить каталог IAP, вы можете:

1. Загрузить JSON-файл, чтобы быстро добавить каталог в Личный кабинет.
2. Создать каталог товаров с помощью методов API из раздела документации Виртуальные предметы и валюта > Admin.

Реализация серверного взаимодействия

Создание токена

Настройка вебхуков

Чтобы включить получение вебхуков:

1. В проекте в Личном кабинете перейдите в раздел Настройки проекта > Вебхуки.
2. В поле Сервер для вебхуков укажите адрес сервера, на который вы хотите получать вебхуки (формат: https://example.com). Также можно указать тестовый URL, полученный в инструменте для тестирования вебхуков.
3. Секретный ключ проекта для подписи вебхуков генерируется по умолчанию. Если вы хотите изменить его, нажмите значок обновления.
4. Нажмите Получать вебхуки.

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

Установка SDK

1. Установите SDK как npm-пакет, используя команду:

1npm install --save @xsolla/pay-station-sdk

2. Инициализируйте SDK, передав параметры окружения:

1import { headlessCheckout } from '@xsolla/pay-station-sdk';
2
3await headlessCheckout.init({
4  sandbox: true,
5});

3. Передайте платежный токен для инициализированного SDK.

1await headlessCheckout.setToken(accessToken);

Интеграция SDK на стороне приложения

После установки и инициализации SDK:

1. Инициализируйте платежный интерфейс с указанием ID способа оплаты. Метод headlessCheckout.form.init возвращает объект, который используется для дальнейшей работы с платежным интерфейсом.

1await headlessCheckout.form.init({
2  paymentMethodId: 3175, // Apple Pay payment ID
3});

2. Добавьте обработку события show_fields для отображения дополнительных полей.

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'show_fields':
4      this.handleShowFieldsAction(nextAction);
5  }
6});

3. Добавьте следующие компоненты в HTML-разметку платежного интерфейса:
   • Обязательные компоненты:
     • psdk-legal — для отображения информации о юридических документах.
     • psdk-total — для отображения общей стоимости покупки.
   • Компоненты платежной формы. Вы можете использовать встроенный компонент psdk-payment-form или вручную создать элементы платежного интерфейса, например, используя готовые компоненты.
   • Компонент кнопки оплаты psdk-apple-pay. Вы также можете использовать компонент psdk-submit-button, который уже включает в себя компонент psdk-apple-pay.

1<psdk-legal></psdk-legal>
2<psdk-total></psdk-total>
3
4
5<psdk-payment-form></psdk-payment-form>
6<psdk-apple-pay text="Apple Pay"></psdk-apple-pay>

4. Добавьте обработку события смены статуса платежа check_status.

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'check_status': {
4      showStatus = true;
5    }
6  }
7});

5. Добавьте компонент psdk-status в HTML-разметку платежного интерфейса для отображения статуса платежа.

1@if (showStatus) {
2  <psdk-status></psdk-status>
3}

Как определить регион iOS storefront

Чтобы определить текущий регион App Store (региональную витрину или iOS storefront) и адаптировать работу SDK под нужную страну, используйте следующий код:

1[SKPaymentQueue loadCurrentStorefrontCountryCodeWithCompletion:^(NSString* _Nullable countryCode) {
2    settings.enablePayments = countryCode && [countryCode isEqualToString:@"USA"];
3
4    [[SKPaymentQueue defaultQueue] startWithSettings:settings];
5}];

1SKPaymentQueue.loadCurrentStorefrontCountryCode { countryCode in
2    settings.enablePayments = countryCode == "USA"
3
4    SKPaymentQueue.default().start(settings)
5}

Метод loadCurrentStorefrontCountryCode асинхронно возвращает код страны (три символа) для текущей региональной витрины. Это позволяет включать или отключать функции SDK в зависимости от региона.

В качестве альтернативы можно использовать встроенный нативный класс Apple — Storefront, как показано ниже:

1let storefront = await Storefront.current   
2let countryCode = storefront?.countryCode
3
4settings.enablePayments = countryCode == "USA"
5
6SKPaymentQueue.default().start(settings)

Оплата в один клик с помощью Apple Pay

Оплата в один клик позволяет пользователю использовать привычный и безопасный способ оплаты Apple Pay на поддерживаемых устройствах. Чтобы настроить оплату в один клик:

1. Создайте заявку на подключение этой опции. Для этого:

   a. В Личном кабинете перейдите в раздел Support Hub.

   b. Нажмите Отправить запрос.

   

   c. В открывшемся окне заполните поля:

   • Краткое описание. Например, Подключение оплаты в один клик с помощью Apple Pay.
   • Описание. Укажите домен, по которому в вашем приложении открывается платежный интерфейс, например, amazing.store.com.
   • ID проекта. Выберите ID проекта из раскрывающегося списка. Если вы хотите подключить оплату в один клик для нескольких проектов, укажите их ID в поле Описание.

   d. Нажмите Отправить.

2. Дождитесь получения верификационного файла для вашего домена. Этот шаг выполняется на стороне Xsolla:
   1. Xsolla регистрирует ваш домен на стороне Apple.
   2. Xsolla получает верификационный файл от Apple.
   3. Xsolla отправляет вам по электронной почте полученный верификационный файл и сообщает, по какому адресу его необходимо загрузить.

3. Обновите скрипт инициализации SDK, как показано ниже:

1const config: InitialOptions = {
2  isWebview: false,
3  theme: 'default',
4  language: parameters.language,
5  topLevelDomain: 'amazing.store.com',
6  isApplePayInstantFlowEnabled: true
7};
8
9await initHeadlessCheckoutLib(config);