2.1.1

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

подсказка

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

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

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

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

• Приложение загружено в Консоль RuStore.
• Приложение прошло модерацию (публиковать приложение необязательно).

Важно

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

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

предупреждение

Сервис имеет некоторые ограничения на работу за пределами России.

Подготовка к работе

Для подключения скачайте RuStore Billing SDK и импортируйте его в проект (Assets > Import Package > Custom Package). Зависимости подключаются автоматически с помощью External Dependency Manager (включен в SDK).

подсказка

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

Также вы можете склонировать код с помощью Git.

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

• Edit > Project Settings > Player Settings > Publishing Settings, включите Custom Main Gradle Template и Custom Gradle Properties Template.
• Assets > External Dependencies Manager > Android Resolver > Settings, включите Use Jetifier, Patch mainTemplate.gradle, Patch gradleTemplate.properties.

После настройки обязательно сделать Assets > External Dependencies Manager > Android Resolver > Force Resolve.

Minimum API level должен быть установлен не ниже 24. Минификация приложения (ProGuard/R8) в данный момент не поддерживается, необходимо её отключить в настройках проекта (File > Build Settings > Player Settings > Publishing Settings > Minify).

Обработка deeplink

Deeplink в RuStore SDK платежей нужна для корректной работы со сторонними приложениями оплаты. Она помогает пользователям быстрее совершать покупки в стороннем приложении и возвращаться в ваше приложение.

Для настройки работы с deeplink в вашем приложении и RuStore SDK, укажите deeplinkScheme внутри вашего AndroidManifest файла и переопределите метод onNewIntent вашего Activity.

AndroidManifest.xml

<activity
    android:name="ru.rustore.unitysdk.RuStoreUnityActivity" android:theme ="@style/UnityThemeSelector" android:exported ="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>

    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>
        <data android:scheme="yourappscheme"/>
    </intent-filter>
</activity>

Вместо yourappscheme из примера выше укажите название своей схемы. Например, ru.package.name.rustore.scheme.

Далее расширьте класс UnityPlayerActivity и добавьте обработку входящего intent в onNewIntent.

Пример класса RuStoreUnityActivity

package ru.rustore.unitysdk;

import android.os.Bundle;
import android.content.Intent;
import ru.rustore.unitysdk.billingclient.RuStoreUnityBillingClient;
import com.unity3d.player.UnityPlayerActivity;

public class RuStoreUnityActivity extends UnityPlayerActivity {
    @Override protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
            if (savedInstanceState ==  null) {
            RuStoreUnityBillingClient.onNewIntent(getIntent());
        }
    }
    @Override protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        RuStoreUnityBillingClient.onNewIntent(intent);
    }
}

Разместите Java-файл с кодом расширения UnityPlayerActivity в папке проекта Assets. Если у вас уже есть своё расширение UnityPlayerActivity, перенесите в него код функций onCreate и onNewIntent.

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

Перед вызовом методов библиотеки необходимо выполнить её инициализацию.

Выберите в меню редактора пункт Window > RuStoreSDK > Settings > Billing Client.

RuStoreBillingClient.Instance.Init();

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

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

var config =  new RuStoreBillingClientConfig() {
    consoleApplicationId =  "123456" ,
    deeplinkPrefix =  "yourappscheme" ,
    allowNativeErrorHandling =  true,
    enableLogs =  true
};

RuStoreBillingClient.Instance.Init(config);

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

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

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

• deeplinkPrefix — URL-адрес для использования deeplink. В качестве названия может быть использовано любое уникальное имя (пример: yourappscheme).
• allowNativeErrorHandling — разрешить обработку ошибок в нативном SDK (см. подробнее в разделе Обработка ошибок).
• enableLogs — включить ведение журнала событий.

примечание

Схема deeplink, передаваемая в deeplinkPrefix, должна совпадать со схемой, указанной в AndroidManifest.xml (подробнее см. Обработка deeplink).

Если вам нужно проверить факт инициализации библиотеки, используйте свойство RuStoreBillingClient.Instance.isInitialized — его значение true, если библиотека инициализирована, и false, если Init еще не был вызван.

var isInitialized = RuStoreBillingClient.Instance.IsInitialized;

Как работают платежи

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

Для проверки доступности платежей используйте метод CheckPurchasesAvailability. Если все указанные выше условия выполняются, возвращается FeatureAvailabilityResult.isAvailable == true. В противном случае возвращается FeatureAvailabilityResult.isAvailable == false, где FeatureAvailabilityResult.cause — это ошибка о невыполненном условии.

Все возможные ошибки RuStoreException описаны в разделе Обработка ошибок. Прочие ошибки возвращаются в onFailure. (См. Task API).

Вызов метода CheckPurchasesAvailability

RuStoreBillingClient.Instance.CheckPurchasesAvailability( 
    onFailure: (error) => { 
        // Process error 
    }, 
    onSuccess: (response) => { 
        if (response.isAvailable) { 
            // Process purchases available 
        } else {
            // Process purchases unavailable 
        } 
    }
);

Работа с SDK

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

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

Вызов метода GetProducts

RuStoreBillingClient.Instance.GetProducts(productsId,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (response) => {
        // Process response
    }
);

string[] productIds — список идентификаторов продуктов. В нём не должно быть более 100 позиций.

Чтобы указать id продуктов, которые нужны для работы метода, выполните следующие действия.

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

Метод возвращает список продуктов List<Product>.

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

Класс Product

public class Product {
    public enum ProductStatus {
        ACTIVE,
        INACTIVE
    }
    public enum ProductType {
        NON_CONSUMABLE,
        CONSUMABLE,
        SUBSCRIPTION
    }
    public string productId;
    public ProductType productType;
    public ProductStatus productStatus;
    public string priceLabel;
    public int price;
    public string currency;
    public string language;
    public string title;
    public string description;
    public string imageUrl;
    public string promoImageUrl;
    public ProductSubscription subscription;
}

• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• productType — тип продукта (потребляемый / непотребляемый / подписка): CONSUMABLE/NON-CONSUMABE/SUBSCRIPTION.
• productStatus — статус продукта.
• priceLable — отформатированная цена товара, включая валютный знак на языке language.
• price — цена в минимальных единицах (в копейках).
• currency — код валюты ISO 4217.
• language — язык, указанный с помощью BCP 47 кодирования.
• title — название продукта на языке language.
• description — описание на языке language.
• imageUrl — ссылка на картинку.
• promoImageUrl — ссылка на промокартинку.
• subscription — описание подписки, возвращается только для продуктов с типом subscription.

Структура подписки

Класс ProductSubscription

public class ProductSubscription {
    public SubscriptionPeriod subscriptionPeriod;
    public SubscriptionPeriod freeTrialPeriod;
    public SubscriptionPeriod gracePeriod;
    public string introductoryPrice;
    public string introductoryPriceAmount;
    public SubscriptionPeriod introductoryPricePeriod;
}

• subscriptionPeriod — период подписки.
• freeTrialPeriod — пробный период подписки.
• gracePeriod — льготный период подписки.
• introductoryPrice — отформатированная вступительная цена подписки, включая знак валюты, на языке product:language.
• introductoryPriceAmount — вступительная цена в минимальных единицах валюты (в копейках).
• introductoryPricePeriod — расчётный период вступительной цены.

Структура периода подписки

Класс SubscriptionPeriod

public class SubscriptionPeriod {
    public int years;
    public int months;
    public int days;
}

• years — количество лет.
• months — количество месяцев.
• days — количество дней.

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

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

Тип/Статус	INVOICE_CREATED	CONFIRMED	PAID
CONSUMABLE	+		+
NON-CONSUMABLE	+	+
SUBSCRIPTION	+	+

примечание

Метод возвращает незавершённые состояния покупки и покупки потребляемых товаров, требующих обработки. Помимо этого, он показывает подтверждённые покупки для подписок и непотребляемых товаров — тех, которые нельзя купить повторно.

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

RuStoreBillingClient.Instance.GetPurchases(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (response) => {
        // Process response
    }
);

Метод возвращает List<Purchase> response — список покупок.

Структура покупки

public class Purchase {
    public enum PurchaseState
    {
        CREATED,
        INVOICE_CREATED,
        CONFIRMED,
        PAID,
        CANCELLED,
        CONSUMED,
        CLOSED
    }
    public string purchaseId;
    public string productId;
    public string description;
    public string invoiceId;
    public string language;
    public DateTime purchaseTime;
    public string orderId;
    public string amountLabel;
    public int amount;
    public string currency;
    public int quantity;
    public PurchaseState purchaseState;
    public string developerPayload;
    public string subscriptionToken;
}

• purchaseId — идентификатор покупки.
• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• description — описание на языке language.
• invoiceId — идентификатор счёта.
• language — язык, указанный с помощью BCP 47 кодирования.
• purchaseTime — время покупки.
• orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
• amountLable — отформатированная цена покупки, включая валютный знак.
• amount — цена в минимальных единицах валюты.
• currency — код валюты ISO 4217.
• quantity — количество продукта (необязательный параметр — если не указывать, будет подставлено значение 1).
• purchaseState — состояние покупки:
• developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки.
• subscriptionToken — токен для валидации покупки на сервере.

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

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

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

Чтобы такие товары начислились пользователям без ошибок, подтвердите потребление (подтверждение) продукта с помощью метода confirmPurchase. При начислении товара в вашем приложении используйте серверную валидацию платежей. Начисляйте товар только когда платёж (счёт) перейдет в финальный статус CONFIRMED. Начисление продуктов пользователям надо делать в callback addOnSuccessListener метода confirmPurchase.

Обратите внимание!

Статус PAID является промежуточным и означает, что средства пользователя захолдированы на карте и вам нужно подтвердить покупку.

Исключение составляют платежи через СБП или мобильное списание — см. пояснения ниже.

При оплате потребляемых (CONSUMABLE) товаров через СБП или мобильное списание используется одностадийный платёж, при этом модель счёта остаётся двухстадийной. Это значит, что при переходе счёта в статус PAID при оплате через СБП или мобильное списание деньги уже списаны со счёта покупателя, а с разработчика удержана комиссия. В этом случае при отмене покупки в состоянии PAID происходит возврат средств (refund), а не отмена холдирования — reverse. Удержанная комиссия разработчику не возвращается. При этом для завершения покупки всё равно нужно выполнить метод подтверждения (потребления) — см. также таблицу ниже.

Платёжный метод	Тип платежа	Платёж в статусе PAID
банковские карты; Сбер ID; SberPay; T-Pay; VK Pay.	Двухстадийный	Средства захолдированы на счёте покупателя. Комиссия с разработчика не удержана. Возможна отмена платежа.
СБП; мобильное списание.	Одностадийный	Средства списаны со счёта покупателя. Удержана комиссия с разработчика. При отмене покупки в состоянии PAID происходит возврат средств (refund), а не отмена холдирования — reverse. Удержанная комиссия разработчику не возвращается.

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

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

Вызов метода ConfirmPurchase

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

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

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

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

Вызов метода DeletePurchase

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

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

к сведению

Используйте этот метод, если у вас есть логика, завязанная на удалении покупки. Покупка отменяется автоматически через таймаут в 20 минут, либо при повторной покупке от того же клиента.

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

Возможные ошибки

• RuStoreNotInstalledException — на устройстве пользователя не установлен RuStore;
• RuStoreOutdatedException — версия RuStore, установленная на устройстве пользователя, не поддерживает данный SDK;
• RuStoreUserUnauthorizedException — пользователь не авторизован в RuStore;
• RuStoreRequestLimitReached — с момента последнего отображения процесса прошло слишком мало времени;
• RuStoreReviewExists — этот пользователь уже оценил ваше приложение;
• RuStoreInvalidReviewInfo — проблемы с ReviewInfo;
• RuStoreException — базовая ошибка RuStore, от которой наследуются остальные ошибки.

Возникающие ошибки передаются в обработчик методов SDK onFailure.

Структура ошибки

Класс RuStoreError

public class RuStoreError {
    public string name;
    public string description;
}

• name – имя ошибки.
• description – описание ошибки.

Автоматическая обработка ошибок

При вызове метода PurchaseProduct ошибки обрабатываются автоматически.

Если при инициализации SDK был передан параметр allowNativeErrorHandling == true, при возникновении ошибки, кроме вызова соответствующего обработчика Failure, пользователю будет показан диалог с ошибкой.

Kotlin

public fun RuStoreException.resolveForBilling(context: Context)

Изменить это поведение после инициализации можно установкой свойства AllowNativeErrorHandling.

C#

RuStoreBillingClient.Instance.AllowNativeErrorHandling = false;

Сценарий подтверждения и отмены покупки

В связи с тем, что изменилась модель результата покупки продукта, изменилась и логика потребления (подтверждения) и отмены покупки.

Метод отмены покупки (deletePurchase) необходимо использовать, если:

• метод получения списка покупок (getPurchases) вернул покупку со статусом:

  • PurchaseState.CREATED;
  • PurchaseState.INVOICE_CREATED;

• метод покупки (purchaseProduct) вернул:

  • PaymentResult.Cancelled;
  • PaymentResult.Failure.

Метод потребления (подтверждения) продукта (confirmPurchase) необходимо использовать, если метод получения списка покупок (getPurchases) вернул покупку типа CONSUMABLE и со статусом PurchaseState.PAID.