Подключите Buy Button в игре для мгновенной покупки через Web Shop

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

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

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

• Плавный процесс покупки — нажатие на Buy Button открывает форму оплаты для конкретного товара в Web Shop, и позволяет автоматически вернуться в игру после успешного платежа.
• Поддержка широкого набора способов оплаты, включая оплату в один клик с помощью Apple Pay, которые обеспечивают быстрые и привычные сценарии покупки на мобильных устройствах.
• Быстрая настройка — если Web Shop у вас уже настроен, достаточно добавить в игру ссылку с параметрами.
• Простое подключение — если Web Shop еще не настроен, воспользуйтесь возможностью мгновенного создания Web Shop, добавьте ссылки на оплату в вашу игру и запустите продажи.

Этот способ интеграции предоставляет доступ не только к Buy Button, но и ко всем возможностям Web Shop, включая персонализацию, реферальную программу, систему вознаграждений, промокоды и другие.

Используйте интеграцию через Xsolla Mobile SDK, если вы используете собственный Web Shop, не основанный на Site Builder, и хотите встроить Pay Station напрямую в игру.

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

1. Пользователь запускает игру на iOS-устройстве.
2. Пользователь нажимает кнопку покупки рядом с нужным товаром.
3. Приложение открывает браузер со ссылкой на Web Shop, в которую включены параметры user-id, purchase-sku и redirect-url.
4. Web Shop автоматически аутентифицирует пользователя и отображает платежный интерфейс для выбранного товара.
5. Пользователь выбирает способ оплаты и завершает покупку.
6. Пользователь автоматически перенаправляется обратно в приложение.
7. Приложение получает подтверждение покупки через вебхук и начисляет купленный товар пользователю.

Как настроить

1. Создайте Web Shop:
   1. Создайте проект в Личном кабинете.
   2. Настройте шаблон.
   3. Создайте каталог товаров.
   4. Настройте аутентификацию.
   5. Настройте вебхуки.
   6. Протестируйте сайт.
   7. Опубликуйте сайт.
2. Добавьте в ваше iOS-приложение логику отображения кнопки покупки с переходом в Web Shop только для пользователей из США:
   1. Добавьте кнопку в игру.
   2. Определите iOS storefront.

Быстрый старт

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

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

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

В процессе интеграции вам потребуется ID проекта. Вы можете найти его в Личном кабинете рядом с названием проекта.

Настройка шаблона Web Shop

1. Откройте проект в Личном кабинете.
2. На главной странице проекта нажмите Изменить фокус и выберите Настройка Buy Button для перехода в Web Shop.
3. На шаге Создайте шаблон Web Shop нажмите Создать шаблон.

4. Выберите тип Web Shop:
   • Одностраничный магазин — сайт, на котором все разделы размещены на одной странице.
   • Многостраничный магазин — сайт с 3 отдельными страницами: главной, страницей товаров и страницей новостей.

5. Нажмите Продолжить.
6. На вкладке Экспресс добавьте ссылку на вашу игру в App Store. Это позволит быстро создать сайт, брендированный под вашу игру: при его создании в него автоматически добавляются изображение и название игры, имя разработчика, а также цветовая гамма.
7. Нажмите Создать Web Shop.

Настройте каталог товаров

На стороне Xsolla необходимо создать каталог товаров, которые вы продаете в игре. Вы можете выбрать один из следующих способов для настройки каталога:

• Импортируйте предметы: загрузите JSON-файл, чтобы быстро добавить каталог в Личный кабинет.
• Используйте методы API: оптимально для автоматизированных или массовых обновлений.
• Импортируйте каталог товаров из App Store, Google Play или PlayFab: перенесите существующий каталог напрямую из внешней платформы.
• Настройте каталог вручную: добавляйте и редактируйте товары прямо в интерфейсе Личного кабинета.

Настройка аутентификации пользователя

Для начисления покупок в аккаунт пользователя в игре настройте аутентификацию через ID пользователя из игры.

Вам необходимо настроить обработку вебхука для проверки существования пользователя. Этот вебхук обеспечивает дополнительную проверку при открытии Web Shop по прямой ссылке из игры и необходим для авторизации пользователя в случаях, когда магазин открывается вне игрового клиента.

Чтобы настроить аутентификацию:

1. В вашем приложении реализуйте обработку вебхука для проверки существования пользователя.

При получении вебхука приложение должно выполнять следующие действия:

• Поиск пользователя по полученному в вебхуке ID пользователя.
• Отправка одного из кодов статуса в зависимости от результатов поиска пользователя:
  • 200 HTTP-код с ответом вебхука, если пользователь найден;
  • 404 HTTP-код, если пользователь с таким ID не зарегистрирован в игре.
• Отправка атрибутов пользователя для персонализации.

2. В проекте в Личном кабинете перейдите в раздел Каналы продаж > Веб-сайты.
3. Нажмите Открыть Site Builder в панели нужного сайта.
4. В конструкторе вашего сайта перейдите в блок Настройки входа.

5. Выберите вариант ID пользователя.

6. В раскрывающемся списке выберите Новый вариант Авторизации.

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

Настройка вебхуков для начисления покупок пользователю

Вебхуки — это уведомления о событиях, происходящих в системе. Когда происходит определенное событие, Xsolla отправляет HTTP-запрос с данными об этом событии на сервер вашей игры. Вебхуки необходимы для информирования клиента игры и/или сервера о статусе платежей (успешных и неуспешных), а также о попытках аутентификации пользователей.

Включить получение вебхуков

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

Тестирование вебхуков

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

Проверка пользователя (“notification_type”:“user_validation”):

 1curl -v 'https://your.hostname/your/uri' \
 2-X POST \
 3-H 'Accept: application/json' \
 4-H 'Content-Type: application/json' \
 5-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
 6-d '{
 7    "notification_type":"user_validation",
 8    "settings": {
 9      "project_id": 18404,
10      "merchant_id": 2340
11    },
12    "user": {
13        "ip": "127.0.0.1",
14        "phone": "18777976552",
15        "email": "email@example.com",
16        "id": "1234567",
17        "name": "John Smith",
18        "country": "US"
19    }
20}'

Успешная оплата заказа (“notification_type”: “order_paid”):

  1curl -v 'https://your.hostname/your/uri' \
  2-X POST \
  3-H 'Accept: application/json' \
  4-H 'Content-Type: application/json' \
  5-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
  6-d '{
  7    "notification_type": "order_paid",
  8    "items": [
  9      {
 10        "sku": "com.xsolla.item_1",
 11        "type": "virtual_good",
 12        "is_pre_order": false,
 13        "quantity": 3,
 14        "amount": "1000",
 15        "promotions": [
 16          {
 17            "amount_without_discount": "6000",
 18            "amount_with_discount": "5000",
 19            "sequence": 1
 20          },
 21          {
 22            "amount_without_discount": "5000",
 23            "amount_with_discount": "4000",
 24            "sequence": 2
 25          }
 26        ],
 27        "custom_attributes":
 28          {
 29            "purchased": 0,
 30            "attr": "value"
 31          }
 32      },
 33      {
 34        "sku": "com.xsolla.item_new_1",
 35        "type": "bundle",
 36        "is_pre_order": false,
 37        "quantity": 1,
 38        "amount": "1000",
 39        "promotions": []
 40      },
 41      {
 42        "sku": "com.xsolla.gold_1",
 43        "type": "virtual_currency",
 44        "is_pre_order": false,
 45        "quantity": 1500,
 46        "amount": null,
 47        "promotions": []
 48      }
 49    ],
 50    "order": {
 51      "id": 1,
 52      "mode": "default",
 53      "currency_type": "virtual",
 54      "currency": "sku_currency",
 55      "amount": "2000",
 56      "status": "paid",
 57      "platform": "xsolla",
 58      "comment": null,
 59      "invoice_id": "1",
 60      "promotions": [
 61        {
 62          "amount_without_discount": "4000",
 63          "amount_with_discount": "2000",
 64          "sequence": 1
 65        }
 66      ],
 67      "promocodes": [
 68        {
 69          "code": "promocode_some_code",
 70          "external_id": "promocode_sku"
 71        }
 72      ],
 73      "coupons": [
 74        {
 75          "code": "WINTER2021",
 76          "external_id": "coupon_sku"
 77        }
 78      ]
 79    },
 80    "user": {
 81      "external_id": "id_xsolla_login_1",
 82      "email": "gc_user@xsolla.com"
 83    },
 84    "billing": {
 85      "notification_type": "payment",
 86      "settings": {
 87        "project_id": 18404,
 88        "merchant_id": 2340
 89      },
 90      "purchase": {
 91          "subscription": {
 92              "plan_id": "b5dac9c8",
 93              "subscription_id": "10",
 94              "product_id": "Demo Product",
 95              "date_create": "2014-09-22T19:25:25+04:00",
 96              "date_next_charge": "2014-10-22T19:25:25+04:00",
 97              "currency": "USD",
 98              "amount": 9.99
 99          },
100          "total": {
101              "currency": "USD",
102              "amount": 200
103          },
104          "promotions": [{
105              "technical_name": "Demo Promotion",
106              "id": 853
107          }],
108          "coupon": {
109              "coupon_code": "ICvj45S4FUOyy",
110              "campaign_code": "1507"
111          }
112        },
113      "transaction": {
114          "id": 1,
115          "external_id": 1,
116          "payment_date": "2014-09-24T20:38:16+04:00",
117          "payment_method": 1,
118          "payment_method_name": "PayPal",
119          "payment_method_order_id": 1234567890123456789,
120          "dry_run": 1,
121          "agreement": 1
122      },
123      "payment_details": {
124          "payment": {
125              "currency": "USD",
126              "amount": 230
127          },
128          "vat": {
129              "currency": "USD",
130              "amount": 0,
131              "percent": 20
132          },
133          "sales_tax": {
134              "currency": "USD",
135              "amount": 0,
136              "percent": 0
137          },
138          "direct_wht": {
139              "currency": "USD",
140              "amount": 0,
141              "percent": 0
142          },
143          "payout_currency_rate": "1",
144          "payout": {
145              "currency": "USD",
146              "amount": 200
147          },
148          "country_wht": {
149              "currency": "USD",
150              "amount": 2,
151              "percent": 10
152          },
153          "user_acquisition_fee": {
154              "currency": "USD",
155              "amount": 2,
156              "percent": 1
157          },
158          "xsolla_fee": {
159              "currency": "USD",
160              "amount": 10
161          },
162          "payment_method_fee": {
163              "currency": "USD",
164              "amount": 20
165          },
166          "repatriation_commission": {
167              "currency": "USD",
168              "amount": 10
169          }
170      }
171    }
172 ,
173  "custom_parameters": {
174    "parameter1": "value1",
175    "parameter2": "value2"
176  }
177}'

Тестирование сайта в тестовом окружении

Чтобы протестировать работу сайта в тестовом окружении:

1. В проекте в Личном кабинете перейдите в раздел Каналы продаж > Веб-сайты.
2. Нажмите Открыть Site Builder в панели нужного сайта.
3. Нажмите Просмотр.

4. Выберите товар и нажмите кнопку покупки.
5. Выберите группу способов оплаты Карта.
6. Введите реквизиты тестовой банковской карты. Остальные поля могут быть заполнены любыми данными. Вы также можете указать неверные реквизиты (номер карты, срок действия или CVV) для генерации ошибки.

Публикация сайта

1. Чтобы повысить эффективность сайта:

   a. В разделе Настройки SEO задайте параметры, которые будут учитываться поисковыми системами и использоваться для отображения предпросмотра страницы в социальных сетях: загрузите фавикон, укажите заголовок и описание магазина, добавьте изображение для предпросмотра.

   b. Настройте локализацию сайта.

   c. Внесите изменения в домен (опционально). Для этого перейдите в Каналы продаж > Веб-сайты и нажмите Настроить в панели вашего сайта. В разделе Домен внесите изменения в Домен Xsolla или подключите собственный домен.

2. После того как вы внесли все необходимые изменения и ваш веб-магазин готов к запуску, нажмите Опубликовать.

Добавление в игру кнопки для перехода к покупке

Добавьте в игру кнопку, при нажатии на которую пользователь будет перенаправлен в Web Shop к оплате выбранного товара. В кнопку должна быть встроена ссылка следующего формата: https://yourwebshop.xsolla.site/?user-id=<USER_ID>&purchase-sku=<ITEM_SKU>&redirect-url=<RETURN_TO_GAME_URL>&utm_content=buy_button, где:

• yourwebshop.xsolla.site — ссылка на ваш Web Shop.
• <USER_ID> — ID пользователя в вашей системе.
• <ITEM_SKU> — артикул нужного товара из каталога Web Shop.

• Чтобы найти артикул товара (на примере виртуального предмета):
  1. В проекте в Личном кабинете перейдите в раздел Каталог товаров > Виртуальные предметы.
  2. Перейдите в группу, где находится нужный предмет.
  3. Скопируйте артикул из строки соответствующего предмета — он отображается под его названием.

• <RETURN_TO_GAME_URL> — URL-адрес веб страницы (например, https://example.com/success) или диплинк (например, mygame://open), на который будет перенаправлен пользователь после успешной оплаты. При использовании диплинка убедитесь:
  • что вы используете корректный формат, включающий схему и путь (например, mygame://open), а не только схему (mygame://);
  • диплинк обрабатывается внутри вашей мобильной игры.
• utm_content = buy_button — UTM-метка для сбора аналитики по переходам в Web Shop, позволяет точнее отслеживать покупки в зависимости от источника трафика. Используйте buy_button, если открывается форма оплаты конкретного товара в Web Shop при нажатии на Buy Button в игре.

Если вы изменяете параметры в ссылке (например, добавляете utm_content), необходимо повторно опубликовать Web Shop в разделе Каналы продаж > Веб-сайты, чтобы изменения вступили в силу.

Определение iOS storefront

Чтобы определить, следует ли отображать Buy Button, получите информацию о текущем регионе App Store (региональной витрине или iOS storefront). Вы можете сделать это при первом запуске приложения после установки или при последующих запусках, если это необходимо. Storefront может быть доступен как часть вашей текущей реализации StoreKit или предоставляться вашей системой мобильной атрибуции (Mobile Measurement Partner, MMP). Если код региона storefront — “USA”, включите отображение Buy Button.

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

Обратите внимание: значение storefront на устройстве не изменится, если пользователь явно не обновит регион своего Apple ID в системных настройках.

1let countryCode = await Storefront.current?.countryCode
2let showBuyButton = countryCode == "USA"

Дополнительные возможности

Вы можете предоставить пользователям быстрый доступ к функциям Web Shop, используя query-параметры в ссылке на сайт. Подробная информация приведена в инструкции по использованию query-параметров.

Продвинутая аналитика в AppsFlyer

Когда вы используете внешние ссылки, чтобы перенаправлять пользователей из игры на ваш веб-сайт для совершения оплаты, вы по-прежнему можете отслеживать их покупки и измерять пожизненную ценность клиента (LTV) с помощью систем мобильной атрибуции  (Mobile Measurement Partner, MMP), например AppsFlyer. Xsolla поддерживает два типа интеграции, которые обеспечивают непрерывное отслеживание привлечения пользователей, ретаргетинга и покупательской активности как на мобильных, так и на веб-платформах.

Выберите тип, который больше подходит для ваших настроек, чтобы сохранить полный контроль над вашими кампаниями и доходом.