Перейти к основному содержимому
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

6.1.0 (Beta)

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

подсказка

Если не знаете с чего начать, прочтите инструкцию в сценариях использования.

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

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

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

  • Для приложения включена возможность покупок в RuStore Консоли.

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

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

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

подсказка

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

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

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

  1. Откройте настройки проекта: Edit → Project Settings → Player → Android Settings.

  2. В pазделе Publishing Settings включите следующие настройки.

    • Custom Main Manifest.
    • Custom Main Gradle Template.
    • Custom Gradle Properties Template.

  3. В разделе Other Settings настройте:

    • package name.
    • Minimum API Level = 24.
    • Target API Level = 34.

  4. Откройте настройки External Dependency Manager: Assets → External Dependency Manager → Android Resolver → Settings, включите следующие настройки.

    • Use Jetifier.
    • Patch mainTemplate.gradle.
    • Patch gradleTemplate.properties.

  5. Обновите зависимости проекта: Assets → External Dependency Manager → Android Resolver → Force Resolve.

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

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

<!-- Initializing sdk -->
<meta-data android:name="console_app_id_value" 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_value" android:value="@string/rustore_PayClientSettings_consoleApplicationId" />
        <meta-data android:name="internal_config_key" android:value="@string/rustore_PayClientSettings_internalConfigKey" />
       
    </application>
</manifest>

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

Где в RuStore Консоль отображаются идентификаторы приложений?
  1. Перейдите на вкладку Приложения и выберите нужное приложение.
  2. Скопируйте идентификатор из 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
Подпись и package name различных типов сборок вашего приложения (debug, release и т.д.) могут отличаться друг от друга. В таком случае вы должны создать в разделе Push-уведомления > Проекты из Консоль RuStore проект под каждый тип сборки.

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

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

Внимание!

Не задавайте значения console_app_id_value и 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 не установлен.

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

Для получения продуктов, добавленных в ваше приложение через RuStore консоль, необходимо использовать метод getProducts.

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

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

Где в RuStore Консоль отображаются идентификаторы продуктов?
  1. Перейдите на вкладку Приложения и выберите нужное приложение.
  2. Выберите Монетизация в меню слева.
  3. Выберите тип товара: Подписки или Разовые покупки.
  4. Скопируйте идентификаторы нужных товаров.

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

Структура продукта
public class Product : BaseFields {
    public ProductId productId { get; }
    public ProductType type { get; }
    public AmountLabel amountLabel { get; }
    public Price? price { get; }
    public Currency currency { get; }
    public Url? imageUrl { get; }
    public Title title { get; }
    public Description? description { get; }
 
    ...
}
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • type — тип продукта (потребляемый / непотребляемый): CONSUMABLE/NON-CONSUMABE.
  • amountLabel — отформатированная цена покупки, включая валютный знак
  • price — цена в минимальных единицах (в копейках).
  • currency — код валюты ISO 4217.
  • title — название продукта на языке language.
  • description — описание на языке language.
  • imageUrl — ссылка на картинку.

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

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

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

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

Структура с информацией о покупке
public class Purchase : BaseFields {
    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public PurchaseType type { get; }
    public Description description { get; }
    public DateTime? purchaseTime { get; }
    public Price price { get; }
    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public SubscriptionToken? subscriptionToken { get; }
    public DeveloperPayload? developerPayload { get; }
 
    ...
}
  • purchaseId — идентификатор покупки.
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • invoiceId — идентификатор счёта.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • type — тип покупки:
    • APPLICATION
    • NON_CONSUMABLE_PRODUCT
    • CONSUMABLE_PRODUCT
    • SUBSCRIPTION
  • description — описание на языке language
  • purchaseTime — время покупки:
  • price — цена в минимальных единицах (в копейках)
  • amountLable — отформатированная цена покупки, включая валютный знак.
  • currency — код валюты ISO 4217.
  • quantity — количество продукта (необязательный параметр — если не указывать, будет использоваться значение 1).
  • status — состояние покупки:
    • INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты
    • CANCELLED — покупка отменена покупателем
    • PROCESSING — запущена оплата
    • REJECTED — покупка отклонена (например, ввиду недостатка средств)
    • PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика
    • CONFIRMED — покупка успешно оплачена
    • REFUNDED — запрос на возврат средств за покупку совершён успешно
    • REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
  • subscriptionToken — токен для валидации покупки на сервере

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

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

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

Структура с информацией о покупке
public class Purchase : BaseFields {
    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public OrderId? orderId { get; }
    public PurchaseType type { get; }
    public Description description { get; }
    public DateTime? purchaseTime { get; }
    public Price price { get; }
    public AmountLabel amountLabel { get; }
    public Currency currency { get; }
    public Quantity quantity { get; }
    public PurchaseStatus status { get; }
    public SubscriptionToken? subscriptionToken { get; }
    public DeveloperPayload? developerPayload { get; }
 
    ...
}
  • purchaseId — идентификатор покупки.
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • invoiceId — идентификатор счёта.
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • type — тип покупки:
    • APPLICATION
    • NON_CONSUMABLE_PRODUCT
    • CONSUMABLE_PRODUCT
    • SUBSCRIPTION
  • description — описание на языке language
  • purchaseTime — время покупки:
  • price — цена в минимальных единицах (в копейках)
  • amountLable — отформатированная цена покупки, включая валютный знак.
  • currency — код валюты ISO 4217.
  • quantity — количество продукта (необязательный параметр — если не указывать, будет использоваться значение 1).
  • status — состояние покупки:
    • INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты
    • CANCELLED — покупка отменена покупателем
    • PROCESSING — запущена оплата
    • REJECTED — покупка отклонена (например, ввиду недостатка средств)
    • PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика
    • CONFIRMED — покупка успешно оплачена
    • REFUNDED — запрос на возврат средств за покупку совершён успешно
    • REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 72 часов, холдирование средств отменено
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
  • subscriptionToken — токен для валидации покупки на сервере

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

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

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

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

Структура параметров покупки
public class ProductPurchaseParams : BaseFields {
    public ProductId productId { get; }
    public Quantity? quantity { get; }
    public OrderId? orderId { get; }
    public DeveloperPayload? developerPayload { get; }
 
    ...
}
  • productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
  • quantity — количество продукта (необязательный параметр — если не указывать, будет использоваться значение 1).
  • orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки. Максимальная длина 250 символов.

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

public interface IProductPurchaseResult {
}
 
public sealed class SuccessProductPurchaseResult : BaseFields, IProductPurchaseResult {
    public OrderId? orderId { get; }
    public PurchaseId purchaseId { get; }
    public ProductId productId { get; }
    public InvoiceId invoiceId { get; }
    public SubscriptionToken? subscriptionToken { get; }
 
    ...
}
 
public sealed class CancelProductPurchaseResult : BaseFields, IProductPurchaseResult {
    public PurchaseId? purchaseId { get; }
 
    ...
}
 
public sealed class FailureProductPurchaseResult : BaseFields, IProductPurchaseResult {
    public OrderId? orderId { get; }
    public PurchaseId? purchaseId { get; }
    public ProductId? productId { get; }
    public InvoiceId? invoiceId { get; }
    public Quantity? quantity { get; }
    public SubscriptionToken? subscriptionToken { get; }
    public RuStoreError cause { get; }
 
    ...
}
  • SuccessProductPurchaseResult — результат успешного завершения покупки цифрового товара.
  • FailureProductPurchaseResult — при отправке запроса на оплату или получения статуса оплаты возникла проблема, невозможно установить статус покупки.
  • CancelProductPurchaseResult — запрос на покупку отправлен, при этом пользователь закрыл «платёжную шторку» на своём устройстве, и результат оплаты неизвестен.

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

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

Получение subscriptionToken из результата покупки
var parameters = new ProductPurchaseParams(
      productId: new ProductId("product_id"),
      quantity: new Quantity(1),
      orderId: null,
      developerPayload: null);
 
RuStorePayClient.Instance.Purchase(
    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);
        });
    });

Подтверждение (потребление) покупки​

RuStore содержит продукты следующих типов:

  • CONSUMABLE (потребляемый) — можно купить много раз, например кристаллы в приложении.
  • NON_CONSUMABLE (непотребляемый) — можно купить один раз, например отключение рекламы в приложении.

Подтверждения требуют только продукты типа CONSUMABLE, если они находятся в состоянии PurchaseState.PAID.

Для подтверждения (потребления) покупки используйте метод ConsumePurchase. Запрос на подтверждение (потребление) покупки должен сопровождаться выдачей товара. После вызова подтверждения покупка перейдёт в статус CONSUMED.

Вызов метода подтверждения
PurchaseId id = ...
DeveloperPayload payload = ...
 
RuStorePayClient.Instance.ConsumePurchase(
    purchaseId: id,
    developerPayload: payload,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    });
  • purchaseId — идентификатор покупки.
  • developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки

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

  • 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, от которой наследуются остальные ошибки.