5.1.1
RuStore позволяет интегрировать платежи в мобильное приложение.
Если не знаете с чего начать, прочтите инструкцию в сценариях использования.
Пример реализации
Ознакомьтесь с приложением-примером чтобы узнать, как правильно интегрировать SDK платежей.
Условия работы платежей
- Kotlin
- Java
- На устройстве пользователя установлена актуальная версия RuStore.
- Пользователь авторизован в RuStore.
- Пользователь и приложение не должны быть заблокированы в RuStore.
- Для приложения включена возможность покупок в RuStore Консоли.
Сервис имеет некоторые ограничения на работу за пределами России.
- На устройстве пользователя установлена актуальная версия RuStore.
- Пользователь авторизован в RuStore.
- Пользователь и приложение не должны быть заблокированы в RuStore.
- Для приложения включена возможность покупок в RuStore Консоли.
Сервис имеет некоторые ограничения на работу за пределами России.
Подготовка к работе
- Kotlin
- Java
Добавление репозитория
Подключите репозиторий, как показано в примере ниже.
repositories {
maven {
url = uri("https://artifactory-external.vkpartner.ru/artifactory/maven")
}
}
Подключение зависимости
Добавьте следующий код в свой конфигурационный файл для подключения зависимости.
dependencies {
implementation("ru.rustore.sdk:billingclient:5.1.1")
}
Добавление репозитория
Подключите репозиторий, как показано в примере ниже.
repositories {
maven {
url "https://artifactory-external.vkpartner.ru/artifactory/maven"
}
}
Подключение зависимости
Добавьте следующий код в свой конфигурационный файл для подключения зависимости.
dependencies {
implementation 'ru.rustore.sdk:billingclient:5.1.1'
}
Обработка deeplink
- Kotlin
- Java
Deeplink в RuStore SDK платежей нужна для корректной работы со сторонними приложениями оплаты. Она помогает пользователям быстрее совершать покупки в стороннем приложении и возвращаться в ваше приложение.
Для настройки работы с deeplink в вашем приложении и RuStore SDK, укажите deeplinkScheme внутри вашего AndroidManifest
файла и переопределите метод OnNewIntent
вашего активити.
<activity
android:name=".YourBillingActivity">
<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
.
Схема, указанная в Androidmanifest
файле должна совпадать со схемой, которую вы указыв аете в методе create
RuStore SDK платежей.
Далее в Activity
, в которую необходимо вернуться после совершения оплаты (ваша страница магазина), нужно добавить следующий код.
class YourBillingActivity: AppCompatActivity() {
// Previously created with RuStoreBillingClientFactory.create()
private val billingClient: RuStoreBillingClient = YourDependencyInjection.getBillingClient()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
if (savedInstanceState == null) {
billingClient.onNewIntent(intent)
}
}
override fun onNewIntent(intent: Intent?) {
super.onNewIntent(intent)
billingClient.onNewIntent(intent)
}
}
Для восстановления состояния вашего приложения при возврате с deeplink добавьте в AndroidManifest.xml
android:launchMode="singleTask"
.
<activity
android:name=".YourBillingActivity"
android:launchMode="singleTask"
android:exported="true"
android:screenOrientation="portrait"
android:windowSoftInputMode="adjustResize">
Deeplink в RuStore SDK платежей нужна для корректной работы со сторонними приложениями оплаты. Она помогает пользователям быстрее совершать покупки в стороннем пр иложении и возвращаться в ваше приложение.
Для настройки работы с deeplink в вашем приложении и RuStore SDK, укажите deeplinkScheme внутри вашего AndroidManifest
файла и переопределите метод OnNewIntent
вашего активити.
<activity
android:name=".YourBillingActivity">
<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
.
Схема, указанная в Androidmanifest
файле должна совпадать со схемой, которую вы указываете в методе create
RuStore SDK платежей.
Далее в Activity
, в которую необходимо вернуться после совершения оплаты (ваша страница магазина), нужно добавить следующий код.
public class YourBillingActivityextends AppCompatActivity {
// Previously created with RuStoreBillingClientFactory.create();
RuStoreBillingClient billingClient = YourDependencyInjection.getBillingClient();
@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
if (savedInstanceState == null) {
billingClient.onNewIntent(getIntent());
}
}
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
billingClient.onNewIntent(intent);
}
}
Для восстановления состояния вашего приложения при возврате с deeplink добавьте в AndroidManifest.xml
android:launchMode="singleTask"
.
<activity
android:name=".YourBillingActivity"
android:launchMode="singleTask"
android:exported="true"
android:screenOrientation="portrait"
android:windowSoftInputMode="adjustResize">
Инициализация
Перед вызовом методов библиотеки необходимо выполнит ь её инициализацию.
- Kotlin
- Java
Создайте RuStoreBillingClient
, используя RuStoreBillingClientFactory.create()
.
val billingClient: RuStoreBillingClient = RuStoreBillingClientFactory.create(
context = app,
consoleApplicationId = "111111",
deeplinkScheme = "yourappscheme",
// Опциональные параметры
themeProvider = null,
debugLogs = false,
externalPaymentLoggerFactory = null,
)
-
context
— это ключевой элемент, который предоставляет информацию о текущем состоянии приложения или объекта.信息В Android существует несколько типов контекста:
- Контекст приложения — это singleton-экземпляр, доступный через
getApplicationContext()
. - Контекст Activity — доступен внутри Activity и привязан к её жизненному циклу.
- Контекст в ContentProvider — доступен через метод
getContext()
и аналогичен контексту приложения.
Для создания
RuStoreBillingClient
предпочтительнее использоватьapplicationContext
. - Контекст приложения — это singleton-экземпляр, доступный через
-
consoleApplicationId
— код приложения из консоли разработчика RuStore (пример:https://console.rustore.ru/apps/123456
).Чтобы получить ID приложения, скопируйте цифры из URL-адреса страницы приложения в RuStore Консоли после
apps/
.
ApplicationId
, указанный в build.gradle
, должен совпадать с applicationId
APK-файла, который вы публиковали в Консоли RuStore.
-
deeplinkScheme
— схема deeplink, необходимая для возврата в ваше приложение после оплаты через стороннее приложение (например, SberPay или СБП). SDK генерирует свой хост к данной схеме.
yourappscheme
, должна совпадать со схемой, указанной в AndroidManifest.xml
(подробнее см. Обработка deeplink).-
themeProvider
— интерфейс, который предоставляет темуBillingClientTheme
. Возможны 2 реализации темыBillingClientTheme
: светлая (Light
) и тёмная (Dark
). Необязательный интерфейс, по умолчанию применяется светлая тема.备注По умолчанию тема будет светлой (Light), но вы можете настроить и тёмную (Dark).
-
externalPaymentLoggerFactory
— интерфейс, позволяющий вести журнал событий.提示Журнал событий полезен для версий, которые ещё не опубликованы на пользователей. С его помощью можно отследить возникающие ошибки.
-
debugLogs
— флаг, регулирующий ведение журнала событий. Укажите значениеtrue
, если хотите, чтобы события попадали в журнал. В ином случае укажитеfalse
.
Подпись keystore
должна совпадать с подписью, которой было подписано приложение, опубликованное в Консоли RuStore. Убедитесь, что используемый buildType
(пр. debug
) использует такую же подпись, что и опубликованное приложение (пр. release
).
Создайте RuStoreBillingClient
, используя RuStoreBillingClientFactory.create()
.
final Context context = getContext();
final String consoleApplicationId = "111111";
final String deeplinkScheme = "yourappscheme";
// Опциональные параметры
final BillingClientThemeProvider themeProvider = null;
final boolean debugLogs = false;
final ExternalPaymentLoggerFactory externalPaymentLoggerFactory = null;
final SuperAppTokenProvider superAppTokenProvider = null;
RuStoreBillingClient billingClient = RuStoreBillingClientFactory.INSTANCE.create(
context,
consoleApplicationId,
deeplinkScheme,
// Опциональные параметры
themeProvider,
superAppTokenProvider,
externalPaymentLoggerFactory
debugLogs,
);
-
context
— это ключевой элемент, который предоставляет информацию о текущем состоянии приложения или объекта.信息В Android существует несколько типов контекста:
- Контекст приложения — это singleton-экземпляр, доступный через
getApplicationContext()
. - Контекст Activity — доступен внутри Activity и привязан к её жизненному циклу.
- Контекст в ContentProvider — доступен через метод
getContext()
и аналогичен контексту приложения.
Для создания
RuStoreBillingClient
предпочтительнее использоватьapplicationContext
. - Контекст приложения — это singleton-экземпляр, доступный через
-
consoleApplicationId
— код приложения из консоли разработчика RuStore (пример:https://console.rustore.ru/apps/123456
).Чтобы получить ID приложения, скопируйте цифры из URL-адреса страницы приложения в RuStore Консоли после
apps/
.
ApplicationId
, указанный в build.gradle
, должен совпадать с applicationId
APK-файла, который вы публиковали в Консоли RuStore.
-
deeplinkScheme
— схема deeplink, необходимая для возврата в ваше приложение после оплаты через стороннее приложение (например, SberPay или СБП). SDK генерирует свой хост к данной схеме.
yourappscheme
, должна совпадать со схемой, указанной в AndroidManifest.xml
(подробнее см. Обработка deeplink).-
themeProvider
— интерфейс, который предоставляет темуBillingClientTheme
. Возможны 2 реализации темыBillingClientTheme
: светлая (Light
) и тёмная (Dark
). Необязательный интерфейс, по умолчанию применяется светлая тема.备注По умолчанию тема будет светлой (Light), но вы можете настроить и тёмную (Dark).
-
externalPaymentLoggerFactory
— интерфейс, позволяющий вести журнал событий.提示Журнал событий полезен для версий, которые ещё не опубликованы на пользователей. С его помощью можно отследить возникающие ошибки.
-
debugLogs
— флаг, регулирующий ведение журнала событий. Укажите значениеtrue
, если хотите, чтобы события попадали в журнал. В ином случае укажитеfalse
.
Подпись keystore
должна совпадать с подписью, которой было подписано приложение, опубликованное в Консоли RuStore. Убедитесь, что используемый buildType
(пр. debug
) использует такую же подпись, что и опубликованное приложение (пр. release
).
Как работают платежи
На схеме ниже показан примерный алгоритм настройки и подключения платежей, на который вы можете ориентироваться. Учитывайте особенности вашего проекта в работе.
Проверка доступности работы с платежами
- Kotlin
- Java
Во время проверки доступности платежей проверяются следующие условия.
- На устройстве пользователя установлена актуальная версия RuStore.
- Приложение RuStore поддерживает функциональность платежей.
- Пользователь авторизован в RuStore.
- Пользователь и приложение не должны быть заблокированы в RuStore.
- Для приложения включена возможность покупок в RuStore Консоли.
Проверка доступности платежей зависит от наличия RuStore на устройстве пользователя. Если у пользователя не установлено приложение RuStore, метод вернёт FeatureAvailabilityResult.Unavailable
.
checkPurchasesAvailability
.
Если все указанные выше условия выполняются, возвращается FeatureAvailabilityResult.Available
.
В противном случае возвращается FeatureAvailabilityResult.Unavailable(val cause: RuStoreException)
, где cause
— это ошибка о невыполненном условии.
Все возможные ошибки RuStoreException
описаны в разделе Обработка ошибок. Прочие ошибки возвращаются в onFailure
. (См. Task API).
RuStoreBillingClient.checkPurchasesAvailability(context)
.addOnSuccessListener { result ->
when (result) {
FeatureAvailabilityResult.Available -> {
// Process purchases available
}
is FeatureAvailabilityResult.Unavailable -> {
// Process purchases unavailable
}
}
}.addOnFailureListener { throwable ->
// Process unknown error
}
context
— контекст Android.
Во время проверки доступности платежей проверяются следующие условия.
- На устройстве пользователя установлена актуальная версия RuStore.
- Приложение RuStore поддерживае т функциональность платежей.
- Пользователь авторизован в RuStore.
- Пользователь и приложение не должны быть заблокированы в RuStore.
- Для приложения включена возможность покупок в RuStore Консоли.
Проверка доступности платежей зависит от наличия RuStore на устройстве пользователя. Если у пользователя не установлено приложение RuStore, метод вернёт FeatureAvailabilityResult.Unavailable
.
checkPurchasesAvailability
.
Если все указанные выше условия выполняются, возвращается FeatureAvailabilityResult.Available
.
В противном случае возвращается FeatureAvailabilityResult.Unavailable(val cause: RuStoreException)
, где cause
— это ошибка о невыполненном условии.
Все возможные ошибки RuStoreException
описаны в разделе О бработка ошибок. Прочие ошибки возвращаются в onFailure
. (См. Task API).
RuStoreBillingClientExtKt.checkPurchasesAvailability(RuStoreBillingClient.Companion, getContext())
.addOnSuccessListener(result -> {
if (result instanceof FeatureAvailabilityResult.Available) {
// Hanlde purchases available
} else {
RuStoreException exception = ((FeatureAvailabilityResult.Unavailable) result).getCause();
// Hanlde purchases unavailable
}
})
.addOnFailureListener(error -> {
// Handle error
});
Работа с SDK
Получение списка продуктов
- Kotlin
- Java
getProducts
, чтобы получить информацию о продуктах, добавленных в ваше приложение через RuStore Консоль.
val productsUseCase: ProductsUseCase = billingClient.products
productsUseCase.getProducts(productIds = listOf("id1", "id2"))
.addOnSuccessListener { products: List<Product> ->
// Process success
}
.addOnFailureListener { throwable: Throwable ->
// Process error
}
productIds
— список идентификаторов продуктов. В нём не должно быть более 100 позиций.
Чтобы указать id продуктов, которые нужны для работы метода:
- Откройте RuStore Консоль.
- Перейдите на вкладку «Приложения».
- Выберите нужное приложение.
- В левом боковом меню выберите раздел «Монетизация».
- Выберите тип товара: «Подписки» или «Разовые покупки».
- Скопируйте идентификаторы нужных товаров. Это и есть
id
продуктов.
Метод возвращает
data class Product(
val productId: String,
val productType: ProductType?,
val productStatus: ProductStatus,
val priceLabel: String?,
val price: Int?,
val currency: String?,
val language: String?,
val title: String?,
val description: String?,
val imageUrl: Uri?,
val promoImageUrl: Uri?,
val subscription: ProductSubscription?,
)