7.0.0 (Beta)
RuStore позволяет интегрировать платежи в мобильное приложение.
-
Если не знаете с чего начать, прочтите инструкцию в сценариях использования.
-
Если вы переходите на Pay SDK с billingClient SDK, ознакомьтесь с инструкцией по переходу. Подробности о Pay SDK можно узнать тут.
Пример реализации
Ознакомьтесь с приложением-примеро м чтобы узнать, как правильно интегрировать SDK платежей.
Условия работы платежей
-
Для приложения включена возможность покупок в RuStore Консоли.
- Приложение не должно быть заблокировано в RuStore.
- На устройстве пользователя установлена актуальная версия RuStore.
- Пользователь авторизован в RuStore.
- Пользователь не должен быть заблокирован в RuStore.
Подготовка к работе
- Скопируйте проекты плагина и приложения-примера из официального репозитория RuStore на GitFlic.
- Скопируйте содержимое папки
godot_example/android/plugins
в папкуyour_project/android/plugins
. - В пресете сборки Android в списке Плагины отметьте плагины Ru Store Godot Pay и Ru Store Godot Core.
Инициализация
Перед вызовом методов библиотеки необходимо выполнить её инициализацию. Сама инициализация происходит автоматически, но для работы 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"
xmlns:tools="http://schemas.android.com/tools"
package="com.godot.game"
android:versionCode="1"
android:versionName="1.0"
android:installLocation="auto" >
<supports-screens
android:smallScreens="true"
android:normalScreens="true"
android:largeScreens="true"
android:xlargeScreens="true" />
<uses-feature
android:glEsVersion="0x00030000"
android:required="true" />
<application
android:label="@string/godot_project_name_string"
android:allowBackup="false"
android:icon="@mipmap/icon"
android:appCategory="game"
android:isGame="true"
android:hasFragileUserData="false"
android:requestLegacyExternalStorage="false"
tools:ignore="GoogleAppIndexingWarning" >
<meta-data
android:name="org.godotengine.editor.version"
android:value="${godotEditorVersion}" />
<activity
android:name=".GodotApp"
android:label="@string/godot_project_name_string"
android:theme="@style/GodotAppSplashTheme"
android:launchMode="singleInstancePerTask"
android:excludeFromRecents="false"
android:exported="true"
android:screenOrientation="landscape"
android:configChanges="orientation|keyboardHidden|screenSize|smallestScreenSize|density|keyboard|navigation|screenLayout|uiMode"
android:resizeableActivity="false"
tools:ignore="UnusedAttribute" >
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</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 Консоль отображаются идентификаторы приложений?
- Перейдите на вкладку Приложения и выберите нужное приложение.
- Скопируйте идентификатор из URL-адреса страницы приложения — это набор цифр между
apps/
и/versions
. Например, для URL-адресаhttps://console.rustore.ru/apps/123456/versions
ID приложения —123456
.
Application Id приложения, указанный в Проект → Экспорт... → Android → Параметры → Уникальное Имя, должен совпадать с Application Id APK-файла, к оторый вы публиковали в системе RuStore Консоль.
Не задавайте значения console_app_id_value
и internal_config_value
напрямую в манифесте. Строки должны располагаться в файле ресурсов, например: your_project/android/build/res/values/rustore_values.xml
. При этом значение internal_config_key
всегда должно быть godot
.
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Initializing sdk -->
<string name="rustore_PayClientSettings_consoleApplicationId" translatable="false">198332</string>
<string name="rustore_PayClientSettings_internalConfigKey" translatable="false">godot</string>
</resources>
Работа с SDK
Перед использованием всех методов плагина должен быть создан экземпляр объекта RuStoreGodotPayClient
.
var _pay_client: RuStoreGodotPayClient = RuStoreGodotPayClient.get_instance()
Проверка доступности работы с платежами
Для проверки доступности платежей, вызовите метод get_purchase_availability
. При его вызове проверяются следующие условия.
- На устройстве пользователя установлена актуальная версия RuStore.
- Приложение RuStore поддерживает функциональность платежей.
- Пользователь авторизован в RuStore.
- Пользователь и приложение не должны быть заблокированы в RuStore.
Для приложения включена возможность покупок в RuStore Консоли.
.
Если все указанные выше условия выполняются, возвращается isAvailable == true
. В противном случае возвращается isAvailable == false
, где cause
— это ошибка о невыполненном условии. Для проверки причины возвращения такого результата нужно проверить тип ошибки на RuStoreException
(данные ошибки описаны в разделе Обработка ошибок).
Перед использованием метода необходимо единожды выполнить подписку на события:
on_get_purchases_availability_success
;on_get_purchases_availability_failure
.
func _ready():
# Инициализация _pay_client
_pay_client.on_get_purchase_availability_success.connect(_on_get_purchase_availability_success)
_pay_client.on_get_purchase_availability_failure.connect(_on_get_purchase_availability_failure)
func _on_get_purchase_availability_success(result: RuStorePayGetPurchaseAvailabilityResult):
pass
func _on_get_purchase_availability_failure(error: RuStoreError):
pass
_pay_client.get_purchase_availability()
Проверка установки приложения RuStore
Чтобы проверить установлен ли на устройстве пользователя RuStore необходимо вызвать метод is_rustore_installed
.
var is_rustore_installed: bool = _pay_client.is_rustore_installed()
true
– RuStore установлен.false
– RuStore не установлен.
Получение списка продуктов
Для получения продуктов, добавленных в ваше приложение через RuStore консоль, необходимо использовать метод get_products
.
Перед использованием метода необходимо единожды выполнить подписку на события:
on_get_products_success
;on_get_products_failure
.
func _ready():
# Инициализация _pay_client
_pay_client.on_get_products_success.connect(_on_get_products_success)
_pay_client.on_get_products_failure.connect(_on_get_products_failure)
func _on_get_products_success(products: Array[RuStorePayProduct]):
pass
func _on_get_products_failure(error: RuStoreError):
pass
var PRODUCT_IDS: Array[RuStorePayProductId] = [
RuStorePayProductId.new("con_1"),
RuStorePayProductId.new("non_con_1"),
]
_pay_client.get_products(PRODUCT_IDS)
product_ids
— список идентификаторов продуктов (задаются при создании продукта в консоли разработчика). Список продуктов имеет ограничение в размере 1000 элементов.
Где в RuStore Консоль отображаются идентификаторы продуктов?
- Перейдите на вкладку Приложения и выберите нужное приложение.
- Выберите Монетизация в меню слева.
- Выберите тип товара: Подписки или Разовые покупки.
- Скопируйте идентификаторы нужных товаров.
Метод возвращает список продуктов. Ниже представлена модель продукта.
class_name RuStorePayProduct extends Object
var productId: RuStorePayProductId = null
var type: ERuStorePayProductType.Item = 0
var amountLabel: RuStorePayAmountLabel = null
var price: RuStorePayPrice = null
var currency: RuStorePayCurrency = null
var imageUrl: RuStorePayUrl = null
var title: RuStorePayTitle = null
var description: RuStorePayDescription = null
productId
— и дентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).type
— тип продукта (потребляемый / непотребляемый):CONSUMABLE
/NON-CONSUMABE
.-
amountLabel
— отформатированная цена покупки, включая валютный знак price
— цена в минимальных единицах (в копейках).currency
— код валюты ISO 4217.title
— название продукта на языкеlanguage
.description
— описание на языкеlanguage
.imageUrl
— ссылка на картинку.
Покупка продукта
Одностадийна оплата (без холдирования средств)
Для вызова покупки продукта используйте методpurchase_one_step
.
Перед использованием метода необходимо единожды выполнить подписку на события:
on_purchase_one_step_success
;on_purchase_one_step_failure
.
func _ready():
# Инициализация _pay_client
_pay_client.on_purchase_one_step_success(_on_purchase_one_step_success)
_pay_client.on_purchase_one_step_failure(_on_purchase_one_step_failure)
func _on_purchase_one_step_success(result: RuStorePayProductPurchaseResult):
pass
func _on_purchase_one_step_failure(product_id: RuStorePayProductId, error: RuStoreError):
pass
var parameters = RuStorePayProductPurchaseParams.new(
RuStoreProductId.new("product_id"),
null,
null,
RuStoreQuantity.new(1));
_pay_client.purchase_one_step(parameters)
Двустадийна оплата (с холдированием средств)
Для вызова покупки продукта используйте методpurchase_two_step
.
Перед использованием метода необходимо единожды выполнить подписку на события:
on_purchase_two_step_success
;on_purchase_two_step_failure
.
func _ready():
# Инициализация _pay_client
_pay_client.on_purchase_two_step_success(_on_purchase_two_step_success)
_pay_client.on_purchase_two_step_failure(_on_purchase_two_step_failure)
func _on_purchase_two_step_success(result: RuStorePayProductPurchaseResult):
pass
func _on_purchase_two_step_failure(product_id: RuStorePayProductId, error: RuStoreError):
pass
var parameters = RuStorePayProductPurchaseParams.new(
RuStoreProductId.new("product_id"),
null,
null,
RuStoreQuantity.new(1));
_pay_client.purchase_two_step(parameters)
Структура параметров покупки.
class_name RuStorePayProductPurchaseParams extends Object
var productId: RuStorePayProductId = null
var developerPayload: RuStorePayDeveloperPayload = null
var orderId: RuStorePayOrderId = null
var quantity: RuStorePayQuantity = null
func _init(
productId: RuStorePayProductId,
developerPayload: RuStorePayDeveloperPayload = null,
orderId: RuStorePayOrderId = null,
quantity: RuStorePayQuantity = null
):
self.productId = productId
self.developerPayload = developerPayload
self.orderId = orderId
self.quantity = quantity
productId
— идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).quantity
— количество продукта (необязательный параметр — если не указывать, будет использоваться значение1
).orderId
— уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.developerPayload
— строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки. Максимальная длина 250 символов.
Структура результата покупки.
class_name RuStorePayProductPurchaseResult extends Object
class SuccessProductPurchaseResult extends RuStorePayProductPurchaseResult:
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var productId: RuStorePayProductId = null
var purchaseId: RuStorePayPurchaseId = null
var subscriptionToken: RuStorePaySubscriptionToken = null
class CancelProductPurchaseResult extends RuStorePayProductPurchaseResult:
var purchaseId: RuStorePayPurchaseId = null
class FailureProductPurchaseResult extends RuStorePayProductPurchaseResult:
var cause: RuStoreError = null
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var productId: RuStorePayProductId = null
var purchaseId: RuStorePayPurchaseId = null
var quantity: RuStorePayQuantity = null
var subscriptionToken: RuStorePaySubscriptionToken = null
SuccessProductPurchaseResult
— результат успешного завершения покупки цифрового товара.FailureProductPurchaseResult
— при отправке запроса на оплату или получения статуса оплаты возникла проблема, невозможно установить статус покупки.CancelProductPurchaseResult
— запрос на покупку отправлен, при этом пользователь закрыл «платёжную шторку» на своём устройстве, и результат оплаты неизвестен.
Получение сведений о покупке
Для получения информации о покупке, используйте методget_purchase
.
func _ready:
# Инициализация _pay_client
_pay_client.on_get_purchase_success(_on_get_purchase_success)
_pay_client.on_get_purchase_failure(_on_get_purchase_failure)
func _on_get_purchase_success(purchase: RuStorePayPurchase):
pass
func _on_get_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
pass
var purchase_id: RuStorePayPurchaseId = ...
_pay_client.get_purchase(purchase_id)
Метод возвращает информацию о конкретной покупке в любом статусе. Ниже представлена модель покупки.
class_name RuStorePayPurchase extends Object
var amountLabel: RuStorePayAmountLabel = null
var currency: RuStorePayCurrency = null
var description: RuStorePayDescription = null
var developerPayload: RuStorePayDeveloperPayload = null
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var price: RuStorePayPrice = null
var productId: RuStorePayProductId = null
var productType: ERuStorePayProductType.Item = 0
var purchaseId: RuStorePayPurchaseId = null
var purchaseTime: RuStorePayTime = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
var quantity: RuStorePayQuantity = null
var status: ERuStorePayPurchaseStatus.Item = 0
var subscriptionToken: RuStorePaySubscriptionToken = null
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 часов, холдирование средств отменено.
Статусная модель покупки
Статусная модель одностадийного платежа.
Статусная модель двухстадийного платежа.
Получение списка покупок
Для получения списка покупок пользователя используйте методget_purchases
.
func _ready:
# Инициализация _pay_client
_pay_client.on_get_purchases_success.connect(_on_get_purchases_success)
_pay_client.on_get_purchases_failure.connect(_on_get_purchases_failure)
func _on_get_purchases_success(purchases: Array[RuStorePayPurchase]):
pass
func _on_get_purchases_failure(error: RuStoreError):
pass
# Инициализация _pay_client
_pay_client.get_purchases()
Метод возвращает список покупок в статусах CONFIRMED
(для непотребляемых товаров) и PAID
(для потребляемых товаров). Ниже представлена модель покупки.
class_name RuStorePayPurchase extends Object
var amountLabel: RuStorePayAmountLabel = null
var currency: RuStorePayCurrency = null
var description: RuStorePayDescription = null
var developerPayload: RuStorePayDeveloperPayload = null
var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var price: RuStorePayPrice = null
var productId: RuStorePayProductId = null
var productType: ERuStorePayProductType.Item = 0
var purchaseId: RuStorePayPurchaseId = null
var purchaseTime: RuStorePayTime = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
var quantity: RuStorePayQuantity = null
var status: ERuStorePayPurchaseStatus.Item = 0
var subscriptionToken: RuStorePaySubscriptionToken = null
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 часов, холдирование средств отменено.
Валидация покупок на сервере
Если вам необходимо произвести валидацию успешной покупки на сервере RuStore, вы можете использовать subscriptionToken
в SuccessProductPurchaseResult
, возвращаемой при успешной покупке продукта.
func _on_purchase_two_step_success(result: RuStorePayProductPurchaseResult):
if result is RuStorePayProductPurchaseResult.SuccessProductPurchaseResult:
yourApi.validate(result.subscriptionToken);
Также можно получить subscriptionToken
в сущности Purchase
. Сущность Purchase
можно получить используя метод get_purchases
.
func _on_get_purchases_success(purchases: Array[RuStorePayPurchase]):
for item in purchases:
yourApi.validate(item.subscriptionToken);
Подтверждение (потребление) покупки
Вызов метода подтверждения (потребления)
Для подтверждения (потребления) покупки используйте методconsume_purchase
. Запрос на подтверждение (потребление) покупки должен сопровождаться выдачей товара. После вызова подтверждения покупка перейдёт в статус CONSUMED
.
Перед использованием метода необходимо единожды выполнить подписку на события:
on_confirm_two_step_purchase_success
;on_confirm_two_step_purchase_failure
.
func _ready:
# Инициализация _pay_client
_pay_client.on_confirm_two_step_purchase_success(_on_confirm_two_step_purchase_success)
_pay_client.on_confirm_two_step_purchase_failure(_on_confirm_two_step_purchase_failure)
func _on_confirm_two_step_purchase_success(purchase_id: RuStorePayPurchaseId):
pass
func _on_confirm_two_step_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
pass
var id: RuStorePayPurchaseId = ...
var payload: RuStorePayDeveloperPayload = ...
_pay_client.confirm_two_step_purchase(id, payload)
id
— идентификатор покупки.-
payload
— строка с дополнительной информацией о заказе, которую вы можете установить при инициализации процесса покупки
Отмена покупки
Для отмены покупки используйте методcancel_two_step_purchase
.
Перед использованием метода необходимо единожды выполнить подписку на события:
on_cancel_two_step_purchase_success
;on_cancel_two_step_purchase_failure
.
func _ready:
# Инициализация _pay_client
_pay_client.on_cancel_two_step_purchase_success(_on_cancel_two_step_purchase_success)
_pay_client.on_cancel_two_step_purchase_failure(_on_cancel_two_step_purchase_failure)
func _on_cancel_two_step_purchase_success(purchase_id: String):
pass
func _on_cancel_two_step_purchase_failure(purchase_id: String, error: RuStoreError):
pass
# Ваша реализация UI отмены покупки
func _on_cancel_two_step_purchase_pressed(purchaseId: RuStorePayPurchaseId):
_pay_client.cancel_two_step_purchase(purchaseId)
purchaseId
— идентификатор покупки
- Обратный вызов (callback)
on_cancel_two_step_purchase_success
возвращает идентификатор покупки. - Обратный вызов (callback)
on_cancel_two_step_purchase_failure
возвращает идентификатор покупки типаString
и объектRuStoreError
с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.
Обработка ошибок
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, от которой наследуются остальные ошибки.