6.1.0
RuStore позволяет интегрировать платежи в мобильное приложение.
Если не знаете с чего начать, прочтите инструкцию в сценариях использования.
Пример реализации
Ознакомьтесь с приложением-примером чтобы узнать, как правильно интегрировать SDK платежей.
Условия работы платежей
- Приложение загружено в Консоль RuStore.
- Приложение прошло модерацию (публиковать приложение необязательно).
- Подпись тестируемой сборки (например,
debug
) приложения должна совпадать с подписью сборки приложения, которая была загружена в консоль и прошла модерацию ранее (например,release
).
- Пользователь и приложение не должны быть заблокированы в RuStore.
- Для приложения включена возможность покупок в RuStore Консоли.
- Версия Defold 1.6.2 или выше.
Сервис имеет некоторые ограничения на работу з а пределами России.
Подключение в проект
Подключение в проект
- Скопируйте проекты плагина и приложения-примера из официального репозитория RuStore на GitFlic.
- Скопируйте папки
billing_example/extension_rustore_billing
иbilling_example/extension_rustore_core
в корень вашего проекта.
Обработка deeplink
Deeplink в RuStore SDK платежей нужна для корректной работы со сторонними приложениями оплаты. Она помогает пользователям быстрее совершать покупки в стороннем приложении и возвращаться в ваше приложение.
Для настройки работы с deeplink в вашем приложении и RuStore SDK, укажите deeplinkScheme
внутри вашего AndroidManifest
файла и переопределите метод onNewIntent
вашего Activity
.
<activity>
<!-- RUSTORE BILLING INTENT FILTER -->
<activity android:name="ru.rustore.defold.billing.RuStoreIntentFilterActivity" android:exported="true" android:launchMode="singleTask">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<!-- Set your appscheme -->
<data android:scheme="yourappscheme" />
</intent-filter>
</activity>
Вместо yourappscheme
из примера выше укажите название своей схемы. Например, ru.package.name.rustore.scheme
.
Схема, указанная в AndroidManifest
файле должна совпадать со схемой, которую вы указываете в методе create
RuStore SDK платежей.
Пример приложения содержит модифицированный манифест в файле billing_example/extension_rustore_billing/manifests/android/AndroidManifest.xml
Инициализация
Перед вызовом методов библиотеки необходимо выполнить её инициализацию.
Для инициализации вызовите методinit()
.
local APPLICATION_ID = "123456"
local DEEPLINK_SCHEME = "yourappscheme"
local DEBUG_LOGS = true
rustorebilling.init(APPLICATION_ID, DEEPLINK_SCHEME, DEBUG_LOGS)
-
APPLICATION_ID
— идентификатор приложения из консоли RuStore.
Где в RuStore Консоль отображаются идентификаторы приложений?
- Перейдите на вкладку Приложения и выберите нужное приложение.
- Скопируйте идентификатор из URL-адреса страницы приложения — это набор цифр между
apps/
и/versions
. Например, для URL-адресаhttps://console.rustore.ru/apps/123456/versions
ID приложения —123456
.
-
DEEPLINK_SCHEME
— схема deeplink, необходимая для возврата в ваше приложение после оплаты через стороннее приложение (например, SberPay или СБП). SDK генерирует свой хост к данной схеме. -
DEBUG_LOGS
— флаг, регулирующий ведение журнала событий. Укажите значениеtrue
, если хотите, чтобы события попадали в журнал. В ином случае укажитеfalse
.
DEEPLINK_SCHEME
, должна совпадать со схемой, указанной в AndroidManifest.xml
(подробнее см. Обработка deeplink).Как работают платежи
Проверка доступности работы с платежами
- На устройстве пользователя установлена актуальная версия RuStore.
- Приложение RuStore поддерживает функциональность платежей.
- Пользователь авторизован в RuStore.
- Пользователь и приложение не должны быть заблокированы в RuStore.
- Для приложения включена возможность покупок в RuStore Консоли.
Перед использованием метода необходимо единожды выполнить подписку на события:
rustore_check_purchases_available_success
;rustore_check_purchases_available_failure
.
function init(self)
# Инициализация rustorebilling
rustorecore.connect("rustore_check_purchases_available_success", _check_purchases_available_success)
rustorecore.connect("rustore_check_purchases_available_failure", _check_purchases_available_failure)
end
function _check_purchases_availability_success(self, channel, value)
local data = json.decode(value)
end
function _check_purchases_availability_failure(self, channel, value)
local data = json.decode(value)
end
rustorebilling.check_purchases_availability()
Обратный вызов (callback) rustore_check_purchases_availability_success
возвращает строку JSON с информацией о доступности сервиса (см. ниже).
-
isAvailable
— выполнение условий выполнения платежей (true
/false
). -
cause
— информация об ошибке.
Структура ошибки описана в разделе Обработка ошибок.
Обратный вызов (callback) rustore_check_purchases_availability_failure
возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.
Работа с SDK
Получение списка продуктов
Вы проверили, что платежи доступны и пользователи могут совершать покупки. Теперь можно получить список продуктов. Используйте метод get_products()
, чтобы получить информацию о продуктах, добавленных в ваше приложение через RuStore Консоль.
Перед использованием метода необходимо единожды выполнить подписку на события:
rustore_on_get_products_success
;rustore_on_get_products_failure
.
function init(self)
# Инициализация rustorebilling
rustorecore.connect("rustore_on_get_products_success", _on_get_products_success)
rustorecore.connect("rustore_on_get_products_failure", _on_get_products_failure)
end
function _on_get_products_success(self, channel, value)
local data = json.decode(value)
end
func _on_get_products_failure(self, channel, value)
local data = json.decode(value)
end
local PRODUCT_IDS = {
"non_con2",
"non_con1",
"con2",
"con1",
"sub2",
"sub1"}
rustorebilling.get_products(PRODUCT_IDS)
PRODUCT_IDS
— список идентификаторов продуктов. В нём не должно быть более 100 позиций.
Чтобы указать id
продуктов, которые нужны для работы метода, выполните следующие действия.
- Откройте RuStore Консоль.
- Перейдите на вкладку Приложения.
- Выберите нужное приложение.
- В левом боковом меню выберите раздел Монетизация.
- Выберите тип товара: Подписки или Разовые покупки.
- Скопируйте идентификаторы нужных товаров. Это и есть
id
продуктов.
Обратный вызов (callback) rustore_on_get_products_success
возвращает строку JSON с информацией о продуктах (см. ниже).
currency
— код валюты ISO 4217.description
— описание на языкеlanguage
.imageUrl
— ссылка на картинку.language
— язык, указанный с помощью BCP 47 кодирования.price
— цена в минимальных единицах (в копейках).priceLable
— отформатированная цена товара, включая валютный знак на языкеlanguage
.productId
— идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).productStatus
— тип продукта (потребляемый / непотребляемый / подписка):CONSUMABLE
/NON-CONSUMABE
/SUBSCRIPTION
.productType
— статус продукта.promoImageUrl
— ссылка на промокартинку.title
— название продукта на языкеlanguage
.subscription
— описание подписки, возвращается только для продуктов с типомsubscription
.
Доступные поля объекта subscription
(см. ниже).
subscriptionPeriod
— период подписки.freeTrialPeriod
— пробный период подписки.gracePeriod
— льготный период подписки.introductoryPrice
— отформатированная вступительная цена подписки, включая знак валюты, на языкеproduct:language
.introductoryPriceAmount
— вступительная цена в минимальных единицах валюты (в копейках).introductoryPricePeriod
— расчётный период вступительной цены.
Доступные поля объекта «период» (см. ниже).
years
— количество лет.months
— количество месяцев.days
— количество дней.
Обратный вызов (callback) rustore_on_get_products_failure
возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.
Покупка продукта
Для вызова покупки продукта используйте метод purchase_product()
.
Перед использованием метода необходимо единожды выполнить подписку на события:
rustore_on_purchase_product_success
;rustore_on_purchase_product_failure
.
function init(self)
# Инициализация rustorebilling
rustorecore.connect("rustore_on_purchase_product_success", _on_purchase_product_success)
rustorecore.connect("rustore_on_purchase_product_failure", _on_purchase_product_failure)
end
function _on_purchase_product_success(self, channel, value)
local data = json.decode(value)
end
function _on_purchase_product_failure(self, channel, value)
local data = json.decode(value)
end
local PRODUCT_ID = "example_id"
local PARAMS = "{" ..
"\"orderId\":\"example\"," ..
"\"quantity\":1," ..
"\"payload\":\"example\"" ..
"}"
rustorebilling.purchase_product(PRODUCT_ID, PARAMS)
PRODUCT_ID
— идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр);PARAMS
— опциональные параметры:orderId
— уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирова н автоматически (uuid). Максимальная длина 150 символов;quantity
— количество продукта (необязательный параметр — если не указывать, будет подставлено значение1
);payload
— строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки.
Обратный вызов rustore_on_purchase_product_success
возвращает строку JSON с информацией о покупке. Доступны следующие поля.
-
type
— тип результата запросаSuccess
— результат успешного завершения покупки цифрового товара;Failure
— при отправке запроса на оплату или получения статуса оплаты возникла проблема, невозможно установить статус покупки;Cancelled
— запрос на покупку отправлен, при этом пользователь закрыл «платёжную шторку» на своём устройстве, и результат оплаты неизвестен;InvalidPaymentState
— ошибка работы SDK платежей. Может возникнуть, в случае некорректного обратного deeplink.
-
data
— строка JSON с опциональными полями.
Объект типа Success
возвращается в сл учае удачного выполнения запроса. Доступны следующие поля.
orderId
— уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.purchaseId
— идентификатор покупки.productId
— идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).invoiceId
— идентификатор счёта.sandbox
— флаг тестового платежа. Значениеtrue
— тестовый платёж,false
— реальный платёж.subscriptionToken
— токен для валидации покупки на сервере.
Объект типа Failure
возвращается в случае ошибки при выполнения запроса. Доступны следующие поля.
purchaseId
— идентификатор покупки.invoiceId
— идентификатор счёта.orderId
— уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей си стеме, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.quantity
— количество продукта (необязательный параметр — если не указывать, будет подставлено значение1
).productId
— идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).sandbox
— флаг тестового платежа. Значениеtrue
— тестовый платёж,false
— реальный платёж.errorCode
— код ошибки.
Коды ошибок описаны в разделе Коды ошибок.
Объект типа Cancelled
возвращается в случае отмены покупки пользователем. Доступны следующие поля.
purchaseId
— идентификатор покупки.sandbox
— флаг тестового платежа. Значениеtrue
— тестовый платёж,false
— реальный платёж.
Объект типа InvalidPaymentState
возвращается в случае ошибки работы SDK платежей. Например в случае некорректного обратного deeplink.
Обратный вызов (callback) rustore_on_purchase_product_failure
возвращает строку JSON с информацией об ошиб ке. Структура ошибки описана в разделе Обработка ошибок.
Получение списка покупок
Метод возвращает только покупки со статусами из таблицы ниже. Подробнее о других возможных состояниях покупки смотрите в разделе Получение сведений о покупке.
Тип/Статус | INVOICE_CREATED | CONFIRMED | PAID |
---|---|---|---|
CONSUMABLE | + | + | |
NON-CONSUMABLE | + | + | |
SUBSCRIPTION | + | + |
Метод возвращает незавершённые состояния покупки и покупки потребляемых товаров, требующих обработки. Помимо этого, он показывает подтверждённые покупки для подписок и непотребляемых товаров — тех, которые нельзя купить повторно.
Для получения списка покупок пользователя используйте метод get_purchases()
.
Перед использованием метода необходимо единожды выполнить подписку на события:
rustore_on_get_purchases_success
;rustore_on_get_purchases_failure
.
function init(self)
# Инициализация rustorebilling
rustorecore.connect("rustore_on_get_purchases_success", _on_get_purchases_success)
rustorecore.connect("rustore_on_get_purchases_failure", _on_get_purchases_failure)
end
function _on_get_purchases_success(self, channel, value)
local data = json.decode(value)
for key, value in pairs(data) do
-- value.amount
end
end
function _on_get_purchases_failure(self, channel, value)
local data = json.decode(value)
end
rustorebilling.get_purchases()
Обратный вызов (callback) rustore_on_get_purchases_success
возвращает массив объектов с информацией о покупках. Доступны следующие поля.
amount
— цена в минимальных единицах валюты.amountLable
— отформатированная цена покупки, включая валютный знак.currency
— код валюты ISO 4217.developerPayload
— строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки.invoiceId
— идентификатор счёта.language
— язык, указанный с помощью BCP 47 кодирования.orderId
— уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.productId
— идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).productType
— тип продукта (потребляемый / непотребляемый / подписка):CONSUMABLE
/NON-CONSUMABE
/SUBSCRIPTION
.purchaseId
— идентификатор покупки.purchaseState
— состояние покупки:purchaseTime
— время покупки.quantity
— количество продукта (необязательный параметр — если не указывать, будет подставлено значение1
).subscriptionToken
— токен для валидации покупки на сервере.
Обратный вызов (callback) rustore_on_get_purchases_failure
возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.
Получение сведений о покупке
Для получения информации о покупке, используйте методget_purchase_info()
.
Перед использованием метода необходимо единожды выполнить подписку на события:
rustore_on_get_purchase_info_success
;rustore_on_get_purchase_info_failure
.
function init(self)
# Инициализация rustorebilling
rustorecore.connect("rustore_on_get_purchase_info_success", _on_get_purchase_info_success)
rustorecore.connect("rustore_on_get_purchase_info_failure", _on_get_purchase_info_failure)
end
function _on_get_purchase_info_success(self, channel, value)
local data = json.decode(value)
end
function _on_get_purchase_info_failure(self, channel, value)
local data = json.decode(value)
end
# Ваша реализация UI запроса информации о покупке
function _on_get_purchase_info_pressed(purchaseId):
rustorebilling.get_purchase_info(purchaseId)
end
purchaseId
— идентификатор покупки
Обратный вызов (callback) rustore_on_get_purchase_info_success
возвращает строку JSON с информацией о покуп
amount
— цена в минимальных единицах валюты.amountLable
— отформатированная цена покупки, включая валютный знак.currency
— код валюты ISO 4217.developerPayload
— строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки.invoiceId
— идентификатор счёта.language
— язык, указанный с помощью BCP 47 кодирования.orderId
— уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.productId
— идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).productType
— тип продукта (потребляемый / непотребляемый / подписка):CONSUMABLE
/NON-CONSUMABE
/SUBSCRIPTION
.purchaseId
— идентификатор покупки.purchaseState
— состояние покупки:purchaseTime
— время покупки.quantity
— количество продукта (необязательный параметр — если не указывать, будет подставлено значение1
).subscriptionToken
— токен для валидации покупки на сервере.
Обратный вызов (callback) rustore_on_get_purchase_info_failure
возвращает строку JSON с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.
Статусная модель (purchaseState
)
Статусная модель покупки потребляемых продуктов (CONSUMABLES
)
Статусная модель покупки непотребляемых продуктов (NON-CONSUMABLES
)
Статусная модель покупки подписок (SUBSCRIPTIONS
)
Потребление (подтверждение) покупки
Продукты, требующие потребления (подтверждения)
Учитывайте тип покупки. Метод потребления (подтверждения) необходим, только если у вас потребляемый товар (CONSUMABLE
), который можно купить много раз.
Чтобы такие товары начислились пользователям без ошибок, подтвердите потребление (подтверждение) продукта с помощью метода confirmPurchase
.
При начислении товара в вашем приложении используйте серверную валидацию платежей. Начисляйте товар только когда платёж (счёт) перейдет в финальный статус CONFIRMED
.
Начисление продуктов пользователям надо делать в callback addOnSuccessListener
метода confirmPurchase
.
Статус PAID
является промежуточным и означает, что средства пользователя захолдированы на карте и вам нужно подтвердить покупку.
Исключение составляют платежи через СБП или мобильное списание — см. пояснения ниже.
При оплате потребляемых (CONSUMABLE
) товаров через СБП или мобильное списание используется одностадийный платёж, при этом модель счёта остаётся двухстадийной. Это значит, что при переходе счёта в статус PAID
при оплате через СБП или мобильное списание деньги уже списаны со счёта покупателя, а с разработчика удержана комиссия. В этом случае при отмене покупки в состоянии PAID
происходит возврат средств (refund), а не отмена холдирования — reverse. Удержанная комиссия разработчику не возвращается. При этом для завершения покупки всё равно нужно выполнить метод подтверждения (потребления) — см. также таблицу ниже.
Платёжный метод | Тип платежа | Платёж в статусе PAID |
---|---|---|
| Двухстадийный |
|
| Одностадийный |
|