7.0.0 (Beta)

RuStore позволяет интегрировать платежи в мобильное приложение.

подсказка

Если не знаете с чего начать, прочтите инструкцию в сценариях использования.
Если вы переходите на Pay SDK с billingClient SDK, ознакомьтесь с инструкцией по переходу. Подробности о Pay SDK можно узнать тут.

Пример реализации

Ознакомьтесь с приложением-примером, чтобы узнать, как правильно интегрировать SDK платежей.

Условия работы платежей

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

Подключение в проект

Установка через .unitypackage
Установка через Package Manager

Для подключения скачайте файлы:

Импортируйте файлы в проект через Package Manager (Window > Package Manager > + > Add package from tarball...).

Зависимости подключаются автоматически с помощью External Dependency Manager.

Откройте окно менеджера пакетов (Window > Package Manager > + > Add package from git URL...).
Используйте ссылку https://github.com/googlesamples/unity-jar-resolver.git?path=/upm для подключения пакета External Dependency Manager.
Для устранения ошибки Google.IOSResolver.dll will not be loaded установите модуль сборки iOS для вашей версии Unity (UnityHub > Installs > Ваша версия Unity > Add modules > iOS Build Support).

Ошибка Google.IOSResolver.dll
Assembly 'Packages/com.google.external-dependency-manager/ExternalDependencyManager/Editor/1.2.182/Google.IOSResolver.dll' will not be loaded due to errors:
Unable to resolve reference 'UnityEditor.iOS.Extensions.Xcode'. Is the assembly missing or incompatible with the current platform?
Reference validation can be disabled in the Plugin Inspector.

подсказка

Если вы используете операционную систему macOS, измените настройки утилиты архивации. В настройках Archive Utility снимите флажок Keep expanding if possible. В противном случае архив проекта будет скачан некорректно.

Для подключения скачайте файл RuStoreUnityPaySDK-version.unitypackage и импортируйте его в проект (Assets > Import Package > Custom Package). Зависимости подключаются автоматически с помощью **External Dependency Manager **(включен в .unitypackage).

подсказка

Если вы используете операционную систему MacOS, измените настройки утилиты архивации. В настройках Archive Utility снимите флажок Keep expanding if possible. В противном случае архив проекта будет скачан некорректно.

Для корректной обработки зависимостей SDK выполните следующие настройки.

Откройте настройки проекта: Edit > Project Settings > Player > Android Settings.
В pазделе Publishing Settings включите следующие настройки.
- Custom Main Manifest.
- Custom Main Gradle Template.
- Custom Gradle Properties Template.
В разделе Other Settings настройте:
- package name.
- Minimum API Level = 24.
- Target API Level = 34.
Откройте настройки External Dependency Manager: Assets > External Dependency Manager > Android Resolver > Settings, включите следующие настройки.
- Use Jetifier.
- Patch mainTemplate.gradle.
- Patch gradleTemplate.properties.
Обновите зависимости проекта: Assets > External Dependency Manager > Android Resolver > Force Resolve.

Инициализация

Перед вызовом методов библиотеки необходимо выполнить её инициализацию. Сама инициализация происходит автоматически, но для работы SDK в вашем файле Manifest.xml необходимо прописать console_app_id_key и internal_config_key.

<!-- Initializing sdk -->
<meta-data android:name="console_app_id_key" android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
<meta-data android:name="internal_config_key" android:value="@string/rustore_PayClientSettings_internalConfigKey" />

Оба значения должны располагаться внутри тега <application>

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unity3d.player"
    xmlns:tools="http://schemas.android.com/tools">
    <application>
        <activity android:name="com.unity3d.player.UnityPlayerActivity"
                  android:theme="@style/UnityThemeSelector">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
        </activity>
       
        <!-- Initializing sdk -->
        <meta-data android:name="console_app_id_key" android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
        <meta-data android:name="internal_config_key" android:value="@string/rustore_PayClientSettings_internalConfigKey" />
       
    </application>
</manifest>

console_app_id_key — идентификатор приложения из консоли RuStore.

Где в RuStore Консоль отображаются идентификаторы приложений?

Перейдите на вкладку Приложения и выберите нужное приложение.
Скопируйте идентификатор из URL-адреса страницы приложения — это набор цифр между apps/ и /versions. Например, для URL-адреса https://console.rustore.ru/apps/123456/versions ID приложения — 123456.

Важно

Package Name приложения, указанный в Edit > Project Settings... > Player > Android > Other Settings > Package Name, должен совпадать с Package Name APK-файла, который вы публиковали в системе RuStore Консоль.

warning

Подпись тестируемой сборки (например, debug) приложения должна совпадать с подписью сборки приложения, которая была загружена в консоль и прошла модерацию ранее (например, release)

Значение console_app_id_key задается в файле PayClientSettings.assets. Чтобы создать файл PayClientSettings.assets, в меню редактора Unity выберите пункт: Window > RuStore SDK > Settings > PayClient.

Значение internal_config_key задается в файле PayClientSettings.assets автоматически.

Внимание!

Не задавайте значения console_app_id_key и internal_config_key напрямую в манифесте. Строки должны располагаться в файле ресурсов, который генерируется автоматически на основе данных PayClientSettings.assets.

Работа с SDK

Проверка доступности работы с платежами

Для проверки доступности платежей, вызовите метод GetPurchaseAvailability. При его вызове проверяются следующие условия.

На устройстве пользователя установлена актуальная версия RuStore.
Приложение RuStore поддерживает функциональность платежей.
Пользователь авторизован в RuStore.
Пользователь и приложение не должны быть заблокированы в RuStore.
Для приложения включена возможность покупок в RuStore Консоли.

Если все указанные выше условия выполняются, возвращается PurchaseAvailabilityResult.Available.

В противном случае возвращается PurchaseAvailabilityResult.Unavailable(val cause: Throwable), где cause — это ошибка о невыполненном условии. Для проверки причины возвращения такого результата нужно проверить тип ошибки на RuStoreException (данные ошибки описаны в разделе Обработка ошибок).

Вызов метода GetPurchaseAvailability
RuStorePayClient.Instance.GetPurchaseAvailability(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        if (result.isAvailable) {
            // Process success
        }
        else {
            // Process result.cause
        }
    });

Проверка установки приложения RuStore

Чтобы проверить установлен ли на устройстве пользователя RuStore необходимо вызвать метод IsRuStoreInstalled.

bool isRuStoreInstalled = RuStorePayClient.Instance.IsRuStoreInstalled();

true – RuStore установлен.
false – RuStore не установлен.

Получение списка продуктов

Вы проверили, что платежи доступны и пользователи могут совершать покупки. Теперь можно получить список продуктов. Используйте метод getProducts, чтобы получить информацию о продуктах, добавленных в ваше приложение через RuStore Консоль.

Вызов метода getProducts
ProductId[] ids = ...
 
RuStorePayClient.Instance.GetProducts(
    productIds: ids,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

ProductId[] productIds — список идентификаторов продуктов (задаются при создании продукта в консоли разработчика). Список продуктов имеет ограничение в размере 1000 элементов.

Где в RuStore Консоль отображаются идентификаторы продуктов?

Перейдите на вкладку Приложения и выберите нужное приложение.
Выберите Монетизация в меню слева.
Выберите тип товара: Подписки или Разовые покупки.
Скопируйте идентификаторы нужных товаров.

Метод возвращает список продуктов. Ниже представлена модель продукта.

Структура продукта
public class Product : BaseFields {

    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Description? description { get; }
    public Url imageUrl { get; }
    public Price? price { get; }
    public ProductId productId { get; }
    public Title title { get; }
    public ProductType type { get; }

    ...
}

amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
description — описание на языке language.
imageUrl — ссылка на картинку.
price — цена в минимальных единицах (в копейках).
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
title — название продукта на языке language.
type — тип продукта.

Получение списка покупок

Для получения списка покупок пользователя используйте метод getPurchases.

Вызов метода получения списка покупок пользователя
RuStorePayClient.Instance.GetPurchases(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

Метод возвращает список покупок в статусах CONFIRMED и PAID . Ниже представлена модель покупки.

Структура с информацией о покупке
public class Purchase : BaseFields {

    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Description description { get; }
    public DeveloperPayload? developerPayload { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public Price price { get; }
    public ProductId productId { get; }
    public ProductType productType { get; }
    public PurchaseId purchaseId { get; }
    public DateTime? purchaseTime { get; }
    public PurchaseType purchaseType { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public SubscriptionToken? subscriptionToken { get; }
 
    ...
}

amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
description — описание на языке language.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
invoiceId — идентификатор счёта.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
price — цена в минимальных единицах (в копейках).
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
productType — тип продукта.

purchaseId — идентификатор покупки.
purchaseTime — время покупки.
PurchaseType — тип покупки:
- ONE_PHASE - одностадийная покупка;
- TWO_PHASE - двухстадийная покупка.
quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
status — состояние покупки:
- INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
- CANCELLED — покупка отменена покупателем;
- PROCESSING — запущена оплата;
- REJECTED — покупка отклонена (например, ввиду недостатка средств);
- PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
- CONFIRMED — покупка успешно оплачена;
- REFUNDED — запрос на возврат средств за покупку совершён успешно;
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено.

Получение сведений о покупке

Для получения информации о покупке, используйте метод getPurchase.

Вызов метода получения списка покупок пользователя
RuStorePayClient.Instance.GetPurchase(
    purchaseId: purchase.purchaseId,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (response) => {
        // Process success
    });

Метод возвращает информацию о конкретной покупке в любом статусе. Ниже представлена модель покупки.

Структура с информацией о покупке
public class Purchase : BaseFields {

    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Description description { get; }
    public DeveloperPayload? developerPayload { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public Price price { get; }
    public ProductId productId { get; }
    public ProductType productType { get; }
    public PurchaseId purchaseId { get; }
    public DateTime? purchaseTime { get; }
    public PurchaseType purchaseType { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public SubscriptionToken? subscriptionToken { get; }
 
    ...
}

amountLabel — отформатированная цена покупки, включая валютный знак.
currency — код валюты ISO 4217.
description — описание на языке language.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
invoiceId — идентификатор счёта.
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
price — цена в минимальных единицах (в копейках).
productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
productType — тип продукта.

purchaseId — идентификатор покупки.
purchaseTime — время покупки.
PurchaseType — тип покупки:
- ONE_PHASE - одностадийная покупка;
- TWO_PHASE - двухстадийная покупка.
quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
status — состояние покупки:
- INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
- CANCELLED — покупка отменена покупателем;
- PROCESSING — запущена оплата;
- REJECTED — покупка отклонена (например, ввиду недостатка средств);
- PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
- CONFIRMED — покупка успешно оплачена;
- REFUNDED — запрос на возврат средств за покупку совершён успешно;
- REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено.

Статусная модель покупки

Статусная модель одностадийного платежа.

Статусная модель двухстадийного платежа.

Покупка продукта

Одностадийная оплата (без холдирования средств)

Для вызова покупки продукта используйте метод PurchaseOneStep.

Вызов метода покупки продукта
var parameters = new ProductPurchaseParams(
      productId: new ProductId("product_id"),
      developerPayload: null,
      orderId: null,
      quantity: new Quantity(1));
 
RuStorePayClient.Instance.PurchaseOneStep(
    parameters: parameters,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

Двухстадийная оплата (с холдированием средств)

Для вызова покупки продукта используйте метод PurchaseTwoStep.

Вызов метода покупки продукта
var parameters = new ProductPurchaseParams(
      productId: new ProductId("product_id"),
      developerPayload: null,
      orderId: null,
      quantity: new Quantity(1));
 
RuStorePayClient.Instance.PurchaseTwoStep(
    parameters: parameters,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process success
    });

Структура параметров покупки.

Структура параметров покупки
public class ProductPurchaseParams : BaseFields {

    public ProductId productId { get; }
    public DeveloperPayload? developerPayload { get; }
    public OrderId? orderId { get; }
    public Quantity? quantity { get; }
	
    ...
}

productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки (опционально).
orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов (опционально).
quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1) (опционально).

Структура результата покупки.

public interface IProductPurchaseResult {
}
 
public sealed class SuccessProductPurchaseResult : BaseFields, IProductPurchaseResult {

   public InvoiceId invoiceId { get; }
   public OrderId? orderId { get; }
   public ProductId productId { get; }
   public PurchaseId purchaseId { get; }
   public SubscriptionToken? subscriptionToken { get; }
 
   ...
}
 
public sealed class CancelProductPurchaseResult : BaseFields, IProductPurchaseResult {

   public PurchaseId? purchaseId { get; }

   ...
}
 
public sealed class FailureProductPurchaseResult : BaseFields, IProductPurchaseResult {

   public RuStoreError cause { get; }
   public InvoiceId? invoiceId { get; }
   public OrderId? orderId { get; }
   public ProductId? productId { get; }
   public PurchaseId? purchaseId { get; }
   public Quantity? quantity { get; }
   public SubscriptionToken? subscriptionToken { get; }
 
   ...
}

SuccessProductPurchaseResult — результат успешного завершения покупки цифрового товара.
FailureProductPurchaseResult — при отправке запроса на оплату или получения статуса оплаты возникла проблема, невозможно установить статус покупки.
CancelProductPurchaseResult — запрос на покупку отправлен, при этом пользователь закрыл «платёжную шторку» на своём устройстве, и результат оплаты неизвестен.

Валидация покупок на сервере

Если вам необходимо произвести валидацию успешной покупки на сервере RuStore, вы можете использовать subscriptionToken в SuccessProductPurchaseResult, возвращаемой при успешной покупке продукта.

Получение subscriptionToken из результата покупки
var parameters = new ProductPurchaseParams(
      productId: new ProductId("product_id"));
 
RuStorePayClient.Instance.PurchaseTwoStep(
    parameters: parameters,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        if (result is SuccessProductPurchaseResult success) {
            var subscriptionToken = success.subscriptionToken;
            yourApi.validate(subscriptionToken);
        }
    });

Также можно получить subscriptionToken в сущности Purchase. Сущность Purchase можно получить используя метод GetPurchases.

RuStorePayClient.Instance.GetPurchases(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        result.ForEach(item => {
            yourApi.validate(item.subscriptionToken);
        });
    });

Подтверждение покупки

Покупки, требующие подтверждения

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

Если покупка проводится по одностадийному сценарию, её подтверждение не нужно.
Если покупка проводится по двухстадийному сценарию, то необходимо подтверждение со стороны разработчика.

Вызов метода подтверждения

Для подтверждения покупки используйте метод ConfirmTwoStepPurchase. Запрос на подтверждение покупки должен сопровождаться выдачей товара. После вызова подтверждения покупка перейдёт в статус CONFIRMED.

Вызов метода подтверждения
PurchaseId id = ...
DeveloperPayload payload = ...
 
RuStorePayClient.Instance.ConfirmTwoStepPurchase(
    purchaseId: purchaseId,
    developerPayload: payload,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    });

purchaseId — идентификатор покупки.
developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки (опционально). Максимально 250 символов. Если передан, заменяет значение, записанное при старте покупки методом purchase.

Отмена покупки

Для отмены покупки используйте метод CancelTwoStepPurchase.

Вызов метода CancelTwoStepPurchase
PurchaseId id = ...

RuStoreBillingClient.Instance.CancelTwoStepPurchase(
    purchaseId: id" ,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    }
);

purchaseId — идентификатор покупки.

Обработка ошибок

RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK;
RuStorePaymentCommonException — общая ошибка SDK;
RuStorePayClientAlreadyExist — ошибка повторной инициализации SDK;
RuStorePayClientNotCreated — попытка обратиться к публичным интерфейсам SDK до момента её инициализации;
RuStorePayInvalidActivePurchase — запущен процесс оплаты неизвестного типа продукта;
RuStorePayInvalidConsoleAppId — не задан обязательный параметр сonsole_application_id для инициализации SDK;
RuStorePaySignatureException — неверная сигнатура ответа (возникает при попытке совершить мошеннические действия);
EmptyPaymentTokenException — ошибка получения платежного токена;
RuStoreNotInstalledException — на устройстве пользователя не установлен RuStore;
RuStoreOutdatedException — версия RuStore, установленная на устройстве пользователя, не поддерживает данный SDK;
RuStoreUserUnauthorizedException — пользователь не авторизован в RuStore;
RuStoreApplicationBannedException — приложение заблокировано в RuStore;
RuStoreUserBannedException — пользователь заблокирован в RuStore;
RuStoreException — базовая ошибка RuStore, от которой наследуются остальные ошибки.

7.0.0 (Beta)

Пример реализации​

Условия работы платежей​

Подключение в проект​

Инициализация​

Работа с SDK​

Проверка доступности работы с платежами​

Проверка установки приложения RuStore​

Получение списка продуктов​

Получение списка покупок​

Получение сведений о покупке​

Статусная модель покупки​

Покупка продукта​

Валидация покупок на сервере​

Подтверждение покупки​

Покупки, требующие подтверждения​

Вызов метода подтверждения​

Отмена покупки​

Обработка ошибок​

Пример реализации

Условия работы платежей

Подключение в проект

Инициализация

Работа с SDK

Проверка доступности работы с платежами

Проверка установки приложения RuStore

Получение списка продуктов

Получение списка покупок

Получение сведений о покупке

Статусная модель покупки

Покупка продукта

Валидация покупок на сервере

Подтверждение покупки

Покупки, требующие подтверждения

Вызов метода подтверждения

Отмена покупки

Обработка ошибок