SDK Remote Config для Godot Engine (версия 7.0.0)

SDK Remote Config – это облачный сервис, который позволяет изменять поведение и внешний вид вашего приложения, не требуя от пользователей загрузки обновления приложения. Плагин инкапсулирует в себе запрос конфигурации с сервера, кэширование, фоновое обновление. Имеет удобный интерфейс API для получения данных.

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

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

Ключевые особенности

Выбор наиболее удобного механизма обновления конфигурации.
Возможность указывать процент распространения конфигурации на аудиторию.
Возможность передавать дополнительную информацию для построения воронки конкретной конфигурации. Формировать конфигурацию можно даже для конкретных пользователей.
Набор callback, который можно использовать для аналитики.
Минимальное количество внешних зависимостей.

Подключение в проект

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

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

Скопируйте проекты плагина и приложения-примера из официального репозитория RuStore на GitFlic.
Скопируйте содержимое каталога godot_example/android/plugins в каталог your_project/android/plugins.
В пресете сборки Android в списке Плагины отметьте Ru Store Godot Remote Config и Ru Store Godot Core.

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

Создание `RemoteConfigClient`

Инициализация RuStoreGodotRemoteConfigBuilder должна происходить в момент Application.onCreate(), так как при запуске фоновой синхронизации SDK должна быть проинициализирована.

Для инициализации RemoteConfigClient выполните расширение класса Application и добавьте в метод onCreate следующий код.

import ru.rustore.godot.remoteconfig.model.GodotUpdateBehaviour;
import ru.rustore.godot.remoteconfig.RuStoreGodotRemoteConfigBuilder;

public class GodotRemoteConfigApplication extends Application {

    public final String APP_ID = "a83c91d3-21b4-4891-841e-0ed0fc39a562";
    public final int UPDATE_TIME = 15;
    public final GodotUpdateBehaviour UPDATE_BEHAVIOUR = GodotUpdateBehaviour.Actual;
	
    @Override
    public void onCreate() {
        super.onCreate();
		
        RuStoreGodotRemoteConfigBuilder.INSTANCE.init(APP_ID, UPDATE_BEHAVIOUR, UPDATE_TIME, null, null, getApplicationContext());
    }
}

APP_ID — уникальный идентификатор инструмента Remote Config. Доступен в консоли разработчика RuStore на странице создания параметров Remote Config.
UPDATE_TIME — интервал таймера обновления в минутах.
UPDATE_BEHAVIOUR — параметр, определяющий поведение SDK. См. также Различия в значениях UpdateBehaviour.

Для замены класса Application на GodotRemoteConfigApplication добавьте атрибут android:name к тегу application в файле манифеста AndroidManifest.xml. В Godot 4.6+ манифест находится в android/build/src/main/, в <4.6 — android/build/.

AndroidManifest.xml
<application
    android:name="com.godot.game.GodotRemoteConfigApplication">

`UpdateBehaviour`

UpdateBehaviour — это параметр, определяющий поведение SDK. При создании экземпляра RemoteConfigClientBuilder, по умолчанию используется значение UpdateBehaviour.Default с интервалом синхронизации 15 минут.

Различия в значениях UpdateBehaviour

UpdateBehaviour Описание

`UpdateBehaviour`	Описание
`Actual`	При инициализации каждый запрос конфигурации выполняется через запрос к серверу. Значение `Actual` гарантирует получение самой актуальной конфигурации, но скорость выполнения запроса зависит от скорости сети. Этот тип инициализации отменяет процесс фонового обновления.
`Default`	При инициализации запрос конфигурации выполняется из локального постоянного хранилища, которое обновляется в указанный интервал. Если инициализация выполняется первый раз и локальное постоянное хранилище пустое, запрос отправляется на сервер. Скорость выполнения запроса зависит от объема данных и скорости сети. Доступ к конфигурации будет ожидать завершения инициализации. Значение `Default` не гарантирует, что в рамках жизни процесса запрос конфигурации будет отдавать одинаковый результат, так как синхронизация данных может выполниться в фоне. Этот тип инициализации запускает процесс фонового обновления.
`Snapshot`	При инициализации запрос конфигурации выполняется из локального inMemory-хранилища. inMemory-хранилище заполняется результатом первого запроса из постоянного хранилища и сохраняется в таком виде до конца жизни процесса. Если инициализация выполняется первый раз и локальное постоянное хранилище пустое, запрос отправляется на сервер. Скорость выполнения запроса зависит от объема данных и скорости сети. Доступ к конфигурации будет ожидать завершения инициализации. Значение `Snapshot` гарантирует, что в рамках жизни процесса запросы конфигурации будут отдавать одинаковый результат. Этот тип инициализации запускает процесс фонового обновления.

Actual

При инициализации каждый запрос конфигурации выполняется через запрос к серверу.

Значение Actual гарантирует получение самой актуальной конфигурации, но скорость выполнения запроса зависит от скорости сети.

Этот тип инициализации отменяет процесс фонового обновления.

Default

При инициализации запрос конфигурации выполняется из локального постоянного хранилища, которое обновляется в указанный интервал.

Если инициализация выполняется первый раз и локальное постоянное хранилище пустое, запрос отправляется на сервер. Скорость выполнения запроса зависит от объема данных и скорости сети. Доступ к конфигурации будет ожидать завершения инициализации.

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

Этот тип инициализации запускает процесс фонового обновления.

Snapshot

При инициализации запрос конфигурации выполняется из локального inMemory-хранилища. inMemory-хранилище заполняется результатом первого запроса из постоянного хранилища и сохраняется в таком виде до конца жизни процесса.

Значение Snapshot гарантирует, что в рамках жизни процесса запросы конфигурации будут отдавать одинаковый результат.

Этот тип инициализации запускает процесс фонового обновления.

Опциональные параметры инициализации

Установить опциональные параметры инициализации можно через интерфейс RemoteConfigParameters.

Интерфейс RemoteConfigParameters
package ru.rustore.godot.remoteconfig.model;

public interface RemoteConfigParameters {
    String getAppBuild();
    String getAppVersion();
    String getDeviceId();
    String getDeviceModel();
    String getEnvironment();
    String getOsVersion();
}

Для динамической передачи доступны параметры Account и Language с помощью методов setAccount и setLanguage соответственно. Методы setAccount и setLanguage могут быть вызваны в любое время.

Инициализация с опциональными параметрами
import ru.rustore.godot.remoteconfig.model.GodotUpdateBehaviour;
import ru.rustore.godot.remoteconfig.RuStoreGodotRemoteConfigBuilder;

public final String APP_ID = "a83c91d3-21b4-4891-841e-0ed0fc39a562";
public final int UPDATE_TIME = 15;
public final GodotUpdateBehaviour UPDATE_BEHAVIOUR = GodotUpdateBehaviour.Actual;
public final String ACCOUNT = "MyAccount";
public final String LANGUAGE = "ru";

RemoteConfigClientParametersImpl parameters;
 
/* Ваша инициализация parameters */

RuStoreGodotRemoteConfigClient.INSTANCE.setAccount(ACCOUNT);
RuStoreGodotRemoteConfigClient.INSTANCE.setLanguage(LANGUAGE);
RuStoreGodotRemoteConfigBuilder.INSTANCE.init(APP_ID, UPDATE_TIME, UPDATE_BEHAVIOUR, parameters, null, getApplicationContext());

Получить текущие динамические параметры можно, используя методы getАccount и getLanguage.

Вызов методов getАccount и getLanguage
String account = RuStoreGodotRemoteConfigClient.INSTANCE.setAccount();
String language = RuStoreGodotRemoteConfigClient.INSTANCE.setLanguage();

Параметр	Описание
`OsVersion`	Условие в конфигураторе: Os Version Позволят сравнивать `OsVersion` со значением, установленным в интерфейсе. По умолчанию `OsVersion` не передается, в этом случае возвращается конфиг по умолчанию.
`DeviceModel`	Условие в конфигураторе: Device Model Позволят сравнивать `DeviceModel` со значением, установленным в интерфейсе. По умолчанию `DeviceModel` не передается, у этом случае возвращается конфиг по умолчанию.
`Language`	Условие в конфигураторе: Language Позволят сравнивать `Language` со значением, установленным в интерфейсе. По умолчанию `Language` не передается, у этом случае возвращается конфиг по умолчанию. Для передачи `Language` необходимо реализовать `ConfigRequestParameterProvider`.
`Account`	Условие в конфигураторе: Account Позволят сравнивать `account` со значением, установленным в интерфейсе. Условие в конфигураторе: Account Percentile Позволят раздавать конфиг по значению `account` на определенный процент. Условие в конфигураторе: Interval Account Percentile Позволят раздавать конфиг по значению `account` на определенный процент и в определенный день. Для передачи `Account` необходимо реализовать `ConfigRequestParameterProvider`.
`DeviceId`	Условие в конфигураторе: DeviceID Позволят сравнивать `DeviceId` со значением, установленным в интерфейсе. Условие в конфигураторе: DeviceID Percentile Позволят раздавать конфиг по значению `DeviceId` на определенный процент. Условие в конфигураторе: Interval DeviceID Percentile Позволят раздавать конфиг по значению `DeviceId` на определенный процент и в определенный день.
`AppVersion`	Условие в конфигураторе: App Version Позволят сравнивать `AppVersion` со значением, установленным в интерфейсе.
`Environment`	Условие в конфигураторе: App Environment Позволят сравнивать `Environment` со значением, установленным в интерфейсе `Environment` может принимать значения: `Alpha`, `Beta`, `Release`. Этот параметр удобно использовать для тестирования конфигурации на различных сборках приложения.
`AppBuild`	Условие в конфигураторе: App Build Позволят сравнивать `AppBuild` со значением, установленным в интерфейсе.

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

Перед вызовом методов библиотеки необходимо создать объект клиента RuStoreGodotRemoteConfigClient.

Создание клиента
var _remoteConfig_client: RuStoreGodotRemoteConfigClient = null

func _ready():
    _remoteConfig_client = RuStoreGodotRemoteConfigClient.get_instance()

Динамически передаваемые параметры

Для динамической передачи доступны параметры Account и Language с помощью методов set_account и set_language соответственно.

_remoteConfig_client.setAccount("Auff")
_remoteConfig_client.setLanguage("ru")

Получить текущие параметры можно, используя методы get_account и get_language.

var account: String = _remoteConfig_client.get_account()
var language: String = _remoteConfig_client.>get_language()

Обратные вызовы о работе SDK

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

rustore_background_job_errors – возвращает ошибку фоновой работы.
rustore_first_load_complete – вызывается при окончании первой загрузки.
rustore_init_complete – вызывается при окончании инициализации.
rustore_memory_cache_updated – вызывается при изменении кэша в памяти.
rustore_persistent_storage_updated – вызывается при изменении постоянного хранилища.
rustore_remote_config_network_request_failure – вызывается при ошибке сетевого запроса Remote Config.

Подписка на события
func _ready():
    # Инициализация _remoteConfig_client
	
    _remoteConfig_client.on_rustore_background_job_errors.connect(_on_rustore_background_job_errors)
    _remoteConfig_client.on_rustore_first_load_complete.connect(_on_rustore_first_load_complete)
    _remoteConfig_client.on_rustore_init_complete.connect(_on_rustore_init_complete)
    _remoteConfig_client.on_rustore_memory_cache_updated.connect(_on_rustore_memory_cache_updated)
    _remoteConfig_client.on_rustore_persistent_storage_updated.connect(_on_rustore_persistent_storage_updated)
    _remoteConfig_client.on_rustore_remote_config_network_request_failure.connect(_on_rustore_remote_config_network_request_failure)

func _on_rustore_background_job_errors(error: RuStoreError):
    pass

func _on_rustore_first_load_complete():
    pass

func _on_rustore_init_complete():
    pass

func _on_rustore_memory_cache_updated():
    pass

func _on_rustore_persistent_storage_updated():
    pass

func _on_rustore_remote_config_network_request_failure(error: RuStoreError):
    pass

Структра ошибки RuStoreError описана в разделе Возможные ошибки.

Получение конфигурации

Получение конфигурации происходит через вызов метода get_remote_config.

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

on_get_remote_config_success;
on_get_remote_config_success.

Подписка на события
func _ready():
    # Инициализация _remoteConfig_client
	
    _remoteConfig_client.on_get_remote_config_success.connect(_on_get_remote_config_success)
    _remoteConfig_client.on_get_remote_config_failure.connect(_on_get_remote_config_failure)
	
func _on_get_remote_config_success(data: Dictionary):
    pass

func _on_get_remote_config_failure(error: RuStoreError):
    pass

Вызов метода get_remote_config
_remoteConfig_client.get_remote_config()

Обратный вызов (callback) on_get_remote_config_success возвращает коллекцию Dictionary с набором доступных параметров. Коллекция имеет весь набор ключей и значений, которые были переданы с сервера. Этот набор зависит от параметров, указанных при инициализации и динамически задаваемых параметров.

Обратный вызов (callback) on_get_remote_config_failure возвращает объект RuStoreError с информацией об ошибке в параметре Error. Структра ошибки RuStoreError описана в разделе Возможные ошибки.

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

Если вы получили в ответ на вызов любого метода событие *_failure, не рекомендуется отображать ошибку пользователю. Отображение ошибки может негативно повлиять на пользовательский опыт.

Класс RuStoreError
class_name RuStoreError extends Object

var description: String

func _init(json: String = ""):
    if json == "":
        description = ""
    else:
        var obj = JSON.parse_string(json)
        description = obj["detailMessage"]

description — сообщение ошибки.

Ошибка	Описание
`BackgroundConfigUpdateError`	Появляется при ошибке в работе фоновой синхронизации.
`FailedToReceiveRemoteConfig`	Появляется в случае ошибки при вызове метода получения конфигурации.
`RemoteConfigCastException`	Появляется в случае некорректного получения данных по ключу из класса `RemoteConfig`. Ошибка может быть связана с невозможностью приведения к типу, либо значение по передаваемому ключу отсутствует.
`RemoteConfigClientAlreadyExist`	Появляется в случае повторного создания `RemoteConfigClient` в рамках жизни процесса.
`RemoteConfigClientNotCreated`	Появляется в случае доступа к `RemoteConfigClient` через статическое поле `instance` до создания `RemoteConfigClient`.
`RemoteConfigCommonException`	Общая непредвиденная ошибка.
`RemoteConfigNetworkException`	Появляется при сетевой ошибке.

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

Ключевые особенности​

Подключение в проект​

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

Создание RemoteConfigClient​

UpdateBehaviour​

Опциональные параметры инициализации​

Инициализация в GDScript​

Динамически передаваемые параметры​

Обратные вызовы о работе SDK​

Получение конфигурации​

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