SDK Платежи in-app для Godot (версия 9.1.0)

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

提示

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

• Если вы переходите на Pay SDK с billingClient SDK, ознакомьтесь с инструкцией по переходу. Подробности о Pay SDK можно узнать тут.

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

警告

Библиотеки плагинов в репозитории собраны для Godot Engine 4.2.1. Если вы используете другую версию Godot Engine, выполните шаги раздела Пересборка плагина.

1. Скопируйте проекты плагина и приложения-примера из официального репозитория RuStore на GitFlic.
2. Скопируйте содержимое папки godot_example/android/plugins в папку your_project/android/plugins.
3. В пресете сборки Android в списке Плагины отметьте плагины Ru Store Godot Pay и Ru Store Godot Core.
4. Для Godot 4.2.2 и младше, в файле your_project/android/build/build.gradle добавьте секцию resolutionStrategy:

android {
    ...
}

configurations.all {
    resolutionStrategy {
        force 'androidx.core:core:1.9.0'
        force 'androidx.core:core-ktx:1.9.0'
        force 'androidx.lifecycle:lifecycle-runtime:2.6.2'
        force 'androidx.lifecycle:lifecycle-runtime-ktx:2.6.2'
        force 'androidx.lifecycle:lifecycle-livedata:2.6.2'
        force 'androidx.lifecycle:lifecycle-livedata-core:2.6.2'
        force 'androidx.lifecycle:lifecycle-viewmodel:2.6.2'
        force 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.6.2'
        force 'androidx.lifecycle:lifecycle-process:2.6.2'
        force 'androidx.lifecycle:lifecycle-livedata-core-ktx:2.6.2'
        force 'androidx.lifecycle:lifecycle-viewmodel-savedstate:2.6.2'
    }
}

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

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

Указание console_app_id и 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>. Также к тегу <application> добавьте аттрибут tools:replace="android:label".

AndroidManifest.xml

<?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" />
 
    <!-- Additional attribute tools:replace -->
    <application
        android:label="@string/godot_project_name_string"
		
        tools:replace="android:label"
        
        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 Консоль отображаются идентификаторы приложений?

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

Важно

• ApplicationId, указанный в build.gradle, должен совпадать с applicationId APK-файла, который вы публиковали в RuStore Консоль.

• Подпись keystore должна совпадать с подписью, которой было подписано приложение, опубликованное в RuStore Консоль. Убедитесь, что используемый buildType (пр. debug) использует такую же подпись, что и опубликованное приложение (пр. release).

информация

В целях безопасности, SDK устанавливает android:usesCleartextTraffic="false" по умолчанию, чтобы предотвратить передачу данных по незащищённому HTTP и защитить от атак типа "Man-in-the-Middle". Если ваше приложение требует использования HTTP, вы можете изменить этот атрибут на true, но делайте это на свой страх и риск, так как это увеличивает шанс перехвата и подмены данных. Мы рекомендуем разрешать незащищённый трафик только в исключительных случаях и для доверенных доменов, предпочитая HTTPS для всех сетевых взаимодействий.

Пример rustore_values.xml

<?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>

Обработка deeplink

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

Внимание

Допускаются только символы в кодировке ASCII. Формат должен соответствовать спецификации RFC-3986.

Для настройки deeplink в вашем приложении выполните два основных шага:

1. Измените код игровой активити.

1. Откройте файл GodotApp.java расположенный по пути *your_project*/android/build/src/com/godot/game.
2. Переопределите методы onCreate и onNewIntent для обработки входящих intent'ов, используя приведённый ниже код.

Пример GodotApp.java

package com.godot.game;

import android.content.Intent;
import android.os.Bundle;
import org.godotengine.godot.GodotActivity;
import ru.rustore.godot.pay.RuStoreGodotPay;

public class GodotApp extends GodotActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        setTheme(R.style.GodotAppMainTheme);
        super.onCreate(savedInstanceState);
        if (savedInstanceState == null) {
            RuStoreGodotPay.proceedIntent(getIntent());
        }
    }

    @Override
    public void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        RuStoreGodotPay.proceedIntent(intent);
    }
}

Метод proceedIntent имеет перегрузку с дополнительным параметром maxRetryTimeMs: Long.

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

long maxRetryTimeMs = 5000L;
RuStoreGodotPay.proceedIntent(intent, maxRetryTimeMs);

• maxRetryTimeMs — максимальное время (в миллисекундах) для повторных попыток инициализации платёжного клиента (по умолчанию 5000 мс).

2. Обновите AndroidManifest.xml.

1. В секцию <application>...</application> поместите тег meta-data с указанием ссылки на вашу Deeplink Scheme.
2. Установите атрибут launchMode игровой активити в значение singleTop.
3. Создайте activity-alias указав в атрибуте targetActivity класс игровой активити.
4. Внутри activity-alias объявите intent-filter с указанием ссылки на вашу Deeplink Scheme.

AndroidManifest.xml

<?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"
        tools:replace="android:label"
        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}" />
		
        <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" />
		
        <!-- 1. Deeplink scheme -->
        <meta-data
            android:name="sdk_pay_scheme_value"
            android:value="@string/rustore_PayClientSettings_deeplinkScheme" />

        <!-- 2. Game Activity launchMode="singleTop" -->
        <activity
            android:name=".GodotApp"
            android:label="@string/godot_project_name_string"
            android:theme="@style/GodotAppSplashTheme"
            android:launchMode="singleTop"
            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>
		
        <!-- 3. Аctivity-alias for Game Activity -->
        <activity-alias
            android:enabled="true"
            android:exported="true"
            android:name=".RuStoreDeeplink"
            android:targetActivity=".GodotApp" >

            <!-- 4. Deeplink 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="@string/rustore_PayClientSettings_deeplinkScheme" />
            </intent-filter>
        </activity-alias>
    </application>
</manifest>

Значение deeplinkScheme должно располагаться в файле ресурсов, например: your_project/android/build/res/values/rustore_values.xml.

Внимание!

Не задавайте значение deeplinkScheme напрямую в манифесте.

Пример rustore_values.xml

<?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>
	
    <!-- Deeplink scheme -->
    <string name="rustore_PayClientSettings_deeplinkScheme" translatable="false">yourappscheme</string>
</resources>

Работа с SDK

Перед использованием всех методов плагина должен быть создан экземпляр объекта RuStoreGodotPayClient.

Создание инстанса RuStoreGodotPayClient

var _pay_client: RuStoreGodotPayClient = RuStoreGodotPayClient.get_instance()

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

Для проверки доступности платежей, вызовите метод get_purchase_availability. При его вызове проверяются следующие условия.

• У компании подключена монетизация через консоль разработчика RuStore.
• Приложение не должно быть заблокировано в RuStore.
• Пользователь не должен быть заблокирован в RuStore.

Если все указанные выше условия выполняются, возвращается RuStorePayGetPurchaseAvailabilityResult.isAvailable == true.

В противном случае возвращается RuStorePayGetPurchaseAvailabilityResult.isAvailable == false и RuStorePayGetPurchaseAvailabilityResult.cause, где cause — это ошибка о невыполненном условии (возможные ошибки описаны в разделе Обработка ошибок).

Перед использованием метода необходимо единожды выполнить подписку на события:

• 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):
    # 
    # Processing
    # 
	
    # Free memory
    result.free()
	
func _on_get_purchase_availability_failure(error: RuStoreError):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

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

_pay_client.get_purchase_availability()

Проверка статуса авторизации пользователя

Для проверки статуса авторизации пользователя, вызовите метод get_user_authorization_status. Результатом выполнения метода является значение перечисления ERuStorePayUserAuthorizationStatus.Item:

• AUTHORIZED — пользователь авторизован в RuStore.
• UNAUTHORIZED — пользователь неавторизован в RuStore. Данное значение также вернется если у пользователя нет установленного МП RuStore на девайсе.

Перед использованием метода необходимо единожды выполнить подписку на события:

• on_get_user_authorization_status_success;
• on_get_user_authorization_status_failure.

Подписка на события

func _ready():
    # Инициализация _pay_client
     
    _pay_client.on_get_user_authorization_status_success.connect(_on_get_user_authorization_status_success)
    _pay_client.on_get_user_authorization_status_failure.connect(_on_get_user_authorization_status_failure)
 
func _on_get_user_authorization_status_success(result: ERuStorePayUserAuthorizationStatus.Item):
    pass
 
func _on_get_user_authorization_status_failure(error: RuStoreError):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

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

_pay_client.get_user_authorization_status()

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

Для получения продуктов, добавленных в ваше приложение через 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]):
    # 
    # Processing
    # 
	
    # Free memory
    for product in products:
        if is_instance_valid(product):
            product.free()
    products.clear()
 
func _on_get_products_failure(error: RuStoreError):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

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

var PRODUCT_IDS: Array[RuStorePayProductId] = [
    RuStorePayProductId.new("con_1"),
    RuStorePayProductId.new("non_con_1"),
]
 
_pay_client.get_products(PRODUCT_IDS)

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

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

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

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

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 — ссылка на картинку.

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

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

Перед использованием методов необходимо единожды выполнить подписку на события:

• on_get_purchases_success;
• on_get_purchases_failure.

Подписка на события

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]):
    # 
    # Processing
    # 
	
    # Free memory
    for purchase in purchases:
        if is_instance_valid(purchase):
            purchase.free()
    purchases.clear()
   
func _on_get_purchases_failure(error: RuStoreError):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

Вызов метода получения списка покупок пользователя

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

# Вызов без фильтра
_pay_client.get_purchases()

# Вызов с фильтром
var productType = ERuStorePayProductType.Item.CONSUMABLE_PRODUCT
var purchase_status = ERuStorePayPurchaseStatus.Item.CONFIRMED
_pay_client.get_purchases(productType, purchase_status)

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

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 sandbox: bool = false

• purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
• orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
• PurchaseType — тип покупки:
  • ONE_STEP - одностадийная покупка;
  • TWO_STEP - двухстадийная покупка;
  • UNDEFINED - стадийность не определена.
• productType — тип продукта. (CONSUMABLE/NON-CONSUMABLE - потребляемый/непотребляемый.)
• description - описание покупки.
• purchaseTime — время покупки.
• price — цена в минимальных единицах (в копейках).
• amountLabel — отформатированная цена покупки, включая валютный знак.
• currency — код валюты ISO 4217.
• quantity — количество продукта.
• status — состояние покупки:
  • INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
  • CANCELLED — покупка отменена покупателем;
  • PROCESSING — запущена оплата;
  • REJECTED — покупка отклонена (например, ввиду недостатка средств);
  • EXPIRED — истекло время на оплату покупки;
  • PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
  • CONFIRMED — покупка успешно оплачена;
  • REFUNDING — инициирован возврат, запрос отправлен в эквайер;
  • REFUNDED — запрос на возврат средств за покупку совершён успешно. Деньги будут возвращены пользователю в течение 10 рабочих дней.;
  • REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.
• developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации

• sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

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

Для получения информации о покупке, используйте метод 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):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

Вызов метода получения информации о покупке пользователя

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 sandbox: bool = false

• purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• invoiceId — идентификатор счёта. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
• orderId - уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
• PurchaseType — тип покупки:
  • ONE_STEP - одностадийная покупка;
  • TWO_STEP - двухстадийная покупка;
  • UNDEFINED - стадийность не определена.
• productType — тип продукта. (CONSUMABLE/NON-CONSUMABLE - потребляемый/непотребляемый.)
• description - описание покупки.
• purchaseTime — время покупки.
• price — цена в минимальных единицах (в копейках).
• amountLabel — отформатированная цена покупки, включая валютный знак.
• currency — код валюты ISO 4217.
• quantity — количество продукта.
• status — состояние покупки:
  • INVOICE_CREATED — создан счёт на оплату, покупка ожидает оплаты;
  • CANCELLED — покупка отменена покупателем;
  • PROCESSING — запущена оплата;
  • REJECTED — покупка отклонена (например, ввиду недостатка средств);
  • EXPIRED — истекло время на оплату покупки;
  • PAID — только для двухстадийной оплаты, промежуточный статус, средства на счёте покупателя захолдированы, покупка ожидает подтверждения от разработчика;
  • CONFIRMED — покупка успешно оплачена;
  • REFUNDING — инициирован возврат, запрос отправлен в эквайер;
  • REFUNDED — запрос на возврат средств за покупку совершён успешно. Деньги будут возвращены пользователю в течение 10 рабочих дней.;
  • REVERSED — только для двухстадийной оплаты, покупка была отменена разработчиком или не было произведено подтверждение покупки в течение 6 часов, холдирование средств отменено.
• developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации

• sandbox — флаг тестового платежа. Значение true — тестовый платёж, false— реальный платёж.

Статусная модель покупки

Статусная модель одностадийного платежа.

Статусная модель двухстадийного платежа.

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

Пояснения по работе с одностадийными и двухстадийными оплатами

• При использовании одностадийного платежа покупка не требует подтверждения, денежные средства сразу списываются со счёта покупателя, а с разработчика удерживается комиссия. В таком случае, если требуется вернуть денежные средства клиенту (например, по какой-то причине нет возможности поставить продукт), возможен только возврат средств через RuStore Консоль, денежные средства возвращаются покупателю через несколько дней. Возвращается полная стоимость покупки, при этом удержанная комиссия разработчику не возмещается.
• В случае использования двухстадийного платежа сначала производится холдирование средств на счете покупателя. Комиссия в этом случае не удерживается. После холдирования покупка требует подтверждения или отмены. Комиссия с разработчика удерживается при подтверждении покупки. Отмена покупки означает снятие холда - денежные средства мгновенно снова доступны покупателю.

Важно

Двухстадийная оплата доступна только для определенного набора способов оплаты (на текущий момент — только для карт). Технологии СБП не поддерживают двухстадийную оплату. Если выбран способ оплаты, который не поддерживает холдирование, то покупка будет запущена по сценарию с одной стадией.

Оплата с выбором типа покупки

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

Перед использованием метода необходимо единожды выполнить подписку на события:

• on_purchase_success;
• on_purchase_failure.

Подписка на события

func _ready():
    # Инициализация _pay_client
 
    _pay_client.on_purchase_success(_on_purchase_success)
    _pay_client.on_purchase_failure(_on_purchase_failure)
 
func _on_purchase_success(result: RuStorePayProductPurchaseResult):
    # 
    # Processing
    # 
	
    # Free memory
    result.free()
   
func _on_purchase_failure(product_id: RuStorePayProductId, error: RuStoreError):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

Вызов метода покупки продукта

var parameters = RuStorePayProductPurchaseParams.new(
      RuStoreProductId.new("product_id"), # productId
      null, # appUserEmail
      null, # appUserId
      null, # developerPayload
      null, # orderId
      RuStoreQuantity.new(1)); # quantity

var preferredPurchaseType = ERuStorePayPreferredPurchaseType.Item.ONE_STEP

_pay_client.purchase(parameters, preferredPurchaseType)

• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
• orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
• developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются.
• appUserId — внутренний ID пользователя в вашем приложении (опциональный параметр). Строка с максимальной длиной в 128 символов.
  提示

  Например, данный параметр может использоваться для выявления случаев мошенничества в вашем приложении, что позволит повысить его безопасность.

• appUserEmail - это необязательный параметр, позволяющий задать адрес электронной почты пользователя в вашем приложении. Если адрес электронной почты покупателя был указан при регистрации в приложении, его можно передать для автоматического заполнения поля email при отправке чека — как для платежей вне RuStore, так и для случаев, когда пользователь не авторизован в RuStore. Это избавляет пользователя от необходимости вручную вводить email, сокращает путь до покупки и способствует повышению конверсии.
• preferredPurchaseType — желаемый тип покупки: одностадийная (ONE_STEP) или двухстадийная (TWO_STEP).

Важно

Данный метод по умолчанию запускается по одностадийному сценарию оплаты (preferredPurchaseType = ERuStorePayPreferredPurchaseType.Item.ONE_STEP), т.е. без холдирования средств.

Для двухстадийной оплаты нужно указать preferredPurchaseType = ERuStorePayPreferredPurchaseType.Item.TWO_STEP. Двухстадийная оплата (т.е. оплата с холдированием средств) для данного метода не гарантирована и напрямую зависит от того, какой способ оплаты (карта, СПБ и др.) выбрал пользователь.

При запуске данного метода (с предпочитаемым preferredPurchaseType = twoStep), до тех пор пока пользователь не выберет способ оплаты, стадийность покупки будет UNDEFINED. Учитывайте данное поведение при обработке результатов отмены (ProductPurchaseCancelled) или ошибки (ProductPurchaseException) покупки.

Двухстадийная оплата (с холдированием средств)

信息

При вызове данного метода пользователю будет доступен ограниченный набор способов оплаты — только те, которые поддерживают двухстадийную оплату.

Для вызова покупки продукта используйте метод 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):
    # 
    # Processing
    # 
	
    # Free memory
    result.free()
   
func _on_purchase_two_step_failure(product_id: RuStorePayProductId, error: RuStoreError):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

Вызов метода покупки продукта

var parameters = RuStorePayProductPurchaseParams.new (
      RuStoreProductId.new("product_id"), # productId
      null, # appUserEmail
      null, # appUserId
      null, # developerPayload
      null, # orderId
      RuStoreQuantity.new(1)); # quantity
   );
 
_pay_client.purchase_two_step(parameters)

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

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

class_name RuStorePayProductPurchaseParams extends RefCounted

var productId: RuStorePayProductId = null
var appUserEmail: RuStorePayAppUserEmail = null
var appUserId: RuStorePayAppUserId = null
var developerPayload: RuStorePayDeveloperPayload = null
var orderId: RuStorePayOrderId = null
var quantity: RuStorePayQuantity = null

func _init(
   productId: RuStorePayProductId,
   appUserEmail: RuStorePayAppUserEmail = null,
   appUserId: RuStorePayAppUserId = null,
   developerPayload: RuStorePayDeveloperPayload = null,
   orderId: RuStorePayOrderId = null,
   quantity: RuStorePayQuantity = null
):
   self.productId = productId
   self.appUserEmail = appUserEmail
   self.appUserId = appUserId
   self.developerPayload = developerPayload
   self.orderId = orderId
   self.quantity = quantity

• productId — идентификатор продукта, который был присвоен продукту в RuStore Консоли (обязательный параметр).
• quantity — количество продукта. Необязательный параметр со стандартным значением 1. Применим только к покупке потребляемых товаров.
• orderId — уникальный идентификатор оплаты, сформированный приложением (опциональный параметр). Если вы укажете этот параметр в вашей системе, вы получите его в ответе при работе с API. Если не укажете, он будет сгенерирован автоматически (uuid). Максимальная длина 150 символов.
• developerPayload — строка с дополнительной информацией о заказе, которую вы можете установить при подтверждении покупки. Эта строка переопределяет значение, заданное при инициализации. Максимальная длина 250 символов. Символы не экранируются.
• appUserId — внутренний ID пользователя в вашем приложении (опциональный параметр). Строка с максимальной длиной в 128 символов.
  提示

  Например, данный параметр может использоваться для выявления случаев мошенничества в вашем приложении, что позволит повысить его безопасность.

• appUserEmail — это необязательный параметр, позволяющий задать адрес электронной почты пользователя в вашем приложении. Если адрес электронной почты покупателя был указан при регистрации в приложении, его можно передать для автоматического заполнения поля email при отправке чека — как для платежей вне RuStore, так и для случаев, когда пользователь не авторизован в RuStore. Это избавляет пользователя от необходимости вручную вводить email, сокращает путь до покупки и способствует повышению конверсии.

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

class_name RuStorePayProductPurchaseResult extends Object

var invoiceId: RuStorePayInvoiceId = null
var orderId: RuStorePayOrderId = null
var productId: RuStorePayProductId = null
var purchaseId: RuStorePayPurchaseId = null
var purchaseType: ERuStorePayPurchaseType.Item = 0
var quantity: RuStorePayQuantity = null
var sandbox: bool = false

• invoiceId — идентификатор счета. Используется для серверной валидации платежа, поиска платежей в консоли разработчика, а также отображается покупателю в истории платежей в мобильном приложении RuStore.
• orderId — уникальный идентификатор оплаты, указанный разработчиком или сформированный автоматически (uuid).
• productId — идентификатор приобретенного продукта, указанный при создании в консоли разработчика RuStore.
• purchaseId — идентификатор покупки. Используется для получения информации о покупке в SDK методом получения информации о покупке.
• purchaseType — тип покупки (ONE_STEP/TWO_STEP/UNKNOWN — одностадийная/двухстадийная/стадийность не определена).
• quantity — количество товара.
• sandbox — флаг, указывающий признак тестового платежа в песочнице. Если TRUE - покупка совершена в режиме тестирования.

Обработка ошибки оплаты

Если в процессе оплаты возникает ошибка или пользователь отменяет покупку, выполнение метода оплаты (как с выбором типа покупки, так и двухстадийного метода) завершается с ошибкой:

• ProductPurchaseException — ошибка покупки продукта.
• ProductPurchaseCancelled — ошибка, вызванная отменой покупки продукта (пользователь закрыл платежную шторку) до получения результата покупки. В таком случае рекомендуется дополнительно проверить статус покупки методом получения информации о покупке.

Структура ошибки и отмены покупки:

Структура классов ошибок

class ProductPurchaseException extends RuStorePaymentException:
	
   var invoiceId: RuStorePayInvoiceId = null
   var orderId: RuStorePayOrderId = null
   var productId: RuStorePayProductId = null
   var purchaseId: RuStorePayPurchaseId = null
   var purchaseType: ERuStorePayPurchaseType.Item = 0
   var quantity: RuStorePayQuantity = null
   var sandbox: bool = false

class ProductPurchaseCancelled extends RuStorePaymentException:

   var purchaseId: RuStorePayPurchaseId = null
   var purchaseType: ERuStorePayPurchaseType.Item = 0

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

func _on_any_purchase_failure(product_id: RuStorePayProductId, error: RuStoreError):
   if is_instance_of(error, RuStorePaymentException.ProductPurchaseCancelled):
      var cancelled_error = error as RuStorePaymentException.ProductPurchaseCancelled
      OS.alert(cancelled_error.purchaseId.value, error.name)
		
   elif is_instance_of(error, RuStorePaymentException.ProductPurchaseException):
      var exception_error = error as RuStorePaymentException.ProductPurchaseException
      OS.alert(exception_error.purchaseId.value, error.name)
		
   else:
      OS.alert(error.description, error.name)
   
   # Free memory
   error.free()

Серверная валидация покупки

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

Получение subscriptionToken из результата покупки

func _on_purchase_two_step_success(result: RuStorePayProductPurchaseResult):
   if result is RuStorePayProductPurchaseResult.SuccessProductPurchaseResult:
      yourApi.validate(result.subscriptionToken);

Также можно получить subscriptionToken в сущности Purchase. Сущность Purchase можно получить используя метод get_purchases.

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

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):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

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

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: RuStorePayPurchaseId):
    pass
  
func _on_cancel_two_step_purchase_failure(purchase_id: RuStorePayPurchaseId, error: RuStoreError):
    # 
    # Processing
    # 
	
    # Free memory
    error.free()

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

# Ваша реализация 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 с информацией об ошибке. Структура ошибки описана в разделе Обработка ошибок.

RuStoreUtils

RuStoreUtils — это блок в нативном SDK, содержащий набор публичных методов, предназначенных для взаимодействия с приложением RuStore на устройстве пользователя.

Для доступа к методам блока в среде Godot используется синглтон класса RuStoreGodotCoreUtils.

Метод is_rustore_installed проверяет наличие приложения RuStore на устройстве пользователя.

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

var _core_client: RuStoreGodotCoreUtils = RuStoreGodotCoreUtils.get_instance()

var is_rustore_installed: Variant = _core_client.is_rustore_installed()

if is_rustore_installed == true:
    print("RuStore установлен на устройстве пользователя")
elif is_rustore_installed == false:
    print("RuStore не установлен на устройстве пользователя")
else:
    print("Состояние неизвестно (null)")

Метод open_rustore_download_instruction открывает веб-страницу для скачивания мобильного приложения RuStore.

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

var _core_client: RuStoreGodotCoreUtils = RuStoreGodotCoreUtils.get_instance()

_core_client.open_rustore_download_instruction();

Метод open_rustore запускает мобильное приложение RuStore. При вызове данного метода, в случае отсутствия установленного приложения RuStore, будет отображено Toast уведомление с сообщением "Не удалось открыть приложение".

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

var _core_client: RuStoreGodotCoreUtils = RuStoreGodotCoreUtils.get_instance()

_core_client.Instance.open_rustore();

Метод open_rustore_authorization запускает мобильное приложение RuStore для авторизации. После успешной авторизации пользователя приложение RuStore автоматически закрывается. При вызове данного метода, в случае отсутствия установленного приложения RuStore, будет отображено Toast уведомление с сообщением "Не удалось открыть приложение".

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

var _core_client: RuStoreGodotCoreUtils = RuStoreGodotCoreUtils.get_instance()

_core_client.Instance.open_rustore_authorization();

Список ошибок

RuStoreError — базовый класс ошибки.

Класс RuStoreError

class_name RuStoreError extends Object

var name: String = ""
var description: String = ""

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

RuStorePaymentException — базовый класс ошибки платёжного клиента.

class_name RuStorePaymentException extends RuStoreError

var cause: RuStoreError = null

...

func _notification(what):
    if what == NOTIFICATION_PREDELETE:
        if is_instance_valid(cause):
            cause.free()
        cause = null

• cause – дополнительная информация об ошибке.

Унаследованные поля:

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

RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK. В модели ошибки возвращается код ошибки (поле code), по которому можно определить причину ошибки. Таблица с кодами ошибок доступна в разделе коды ошибок.

Класс RuStorePaymentNetworkException

class_name RuStorePaymentException extends RuStoreError

...

class RuStorePaymentNetworkException extends RuStorePaymentException:
	
    var code = ""
    var id: String = ""

• code — код ошибки.
• id — идентификатор ошибки.

Унаследованные поля:

• name – имя ошибки.
• description – описание ошибки.
• cause – дополнительная информация об ошибке.

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

• RuStorePaymentNetworkException — ошибка сетевого взаимодействия SDK;
• RuStorePaymentCommonException — общая ошибка SDK;
• RuStorePayClientAlreadyExist — ошибка повторной инициализации SDK;
• RuStorePayClientNotCreated — попытка обратиться к публичным интерфейсам SDK до момента её инициализации;
• RuStorePayInvalidActivePurchase — запущен процесс оплаты неизвестного типа продукта;
• RuStorePayInvalidConsoleAppId — не задан обязательный параметр console_application_id для инициализации SDK;
• RuStorePaySignatureException — неверная сигнатура ответа. Возникает при попытке совершить мошеннические действия;
• EmptyPaymentTokenException — ошибка получения платёжного токена;
• InvalidCardBindingIdException — ошибка оплаты сохранённой картой;
• ApplicationSchemeWasNotProvided — не указана схема для обратного диплинка;
• ProductPurchaseException - ошибка покупки продукта. Структура модели представлена в разделе структура результата покупки;
• ProductPurchaseCancelled - произошла отмена покупки продукта (пользователь закрыл платёжную шторку). Структура модели представлена в разделе структура результата покупки;
• ProductPurchaseException — ошибка покупки продукта;
• RuStoreNotInstalledException — на устройстве пользователя не установлен RuStore;
• RuStoreOutdatedException — установленная на устройстве версия RuStore не поддерживает платежи;
• RuStoreUserUnauthorizedException — пользователь не авторизован в RuStore;
• RuStoreApplicationBannedException — приложение заблокировано в RuStore;
• RuStoreUserBannedException — пользователь заблокирован в RuStore.