SDK Remote Config для Unity (версия 6.1.0)
SDK Remote Config – это облачный сервис, который позволяет изменять поведение и внешний вид вашего приложения, не требуя от пользователей загрузки обновления приложения. Плагин инкапсулирует в себе запрос конфигурации с сервера, кэширование, фоновое обновление. Имеет удобный интерфейс API для получения данных.
Пример реализации
Ознакомьтесь с приложением-примером, чтобы узнать, как правильно интегрировать SDK Remote Config.
Ключевые особенности
- Возможность указывать процент распространения конфигурации на аудиторию.
- Возможность передавать дополнительную информацию для построения воронки конкретной конфигурации. Формировать конфигурацию можно даже для конкретных пользователей.
- Набор callback, который можно использовать для аналитики.
- Минимальное количество внешних зависимостей.
Подключение в проект
- Установка через .unitypackage
- Установка через Package Manager
Для подключения скачайте RuStore RemoteConfig SDK и импортируйте его в проект (Assets > Import Package > Custom Package). Зависимости подключаются автоматически с помощью External Dependency Manager (включен в SDK).
Если вы используете операционную систему macOS, измените настройки утилиты архивации. В настройках Archive Utility снимите флажок Keep expanding if possible. В противном случае архив проекта будет скачан некорректно.
Также вы можете склонировать код с помощью Git.
Для корректной обработки зависимостей SDK выполните следующие настройки.
-
Откройте настройки проекта: Edit > Project Settings > Player > Android Settings.
-
В pазделе Publishing Settings включите следующие настройки.
- Custom Main Manifest.
- Custom Main Gradle Template.
- Custom Gradle Properties Template.
-
В разделе Other Settings настройте:
- package name.
- Minimum API Level = 24.
- Target API Level = 34.
-
Откройте настройки External Dependency Manager: Assets > External Dependency Manager > Android Resolver > Settings, включите следующие настройки.
- Use Jetifier.
- Patch mainTemplate.gradle.
- Patch gradleTemplate.properties.
-
Обновите зависимости проекта: Assets > External Dependency Manager > Android Resolver > Force Resolve.
Обновление
Версии плагина 6.1.0 и выше содержат измененную структуру директорий. Измененная структура позволяет использовать преимущества раздельных сборок частей проекта Assembly definitions.
Перед установкой обновления выполните удаление следующих папок.
- Assets > RuStoreSDK > RemoteConfigClient > Editor.
- Assets > RuStoreSDK > Common > Editor.
После удаления импортируйте новый .unitypackage
в проект как при обычной установке (Assets > Import Package > Custom Package).
Для подключения скачайте файлы:
и импортируйте в проект через Package Manager (Window > Package Manager > + > Add package from tarball...).
Зависимости подключаются автоматически с помощью External Dependency Manager:
- Откройте окно менеджера пакетов (Window > Package Manager > + > Add package from git URL...).
- Используйте ссылку https://github.com/googlesamples/unity-jar-resolver.git?path=/upm для подключения пакета.
- Для устранения ошибки
Google.IOSResolver.dll will not be loaded
установите модуль сборки iOS для вашей версии Unity (UnityHub > Installs > Ваша версия Unity > Add modules > iOS Build Support).
Assembly 'Packages/com.google.external-dependency-manager/ExternalDependencyManager/Editor/1.2.182/Google.IOSResolver.dll' will not be loaded due to errors:
Unable to resolve reference 'UnityEditor.iOS.Extensions.Xcode'. Is the assembly missing or incompatible with the current platform?
Reference validation can be disabled in the Plugin Inspector.
Если вы используете операционную систему macOS, измените настройки утилиты архивации. В настройках Archive Utility снимите флажок Keep expanding if possible. В противном случае архив проекта будет скачан некорректно.
Для корректной обработки зависимостей SDK выполните следующие настройки.
-
Откройте настройки проекта: Edit > Project Settings > Player > Android Settings.
-
В pазделе Publishing Settings включите следующие настройки.
- Custom Main Manifest.
- Custom Main Gradle Template.
- Custom Gradle Properties Template.
-
В разделе Other Settings настройте:
- package name.
- Minimum API Level = 24.
- Target API Level = 34.
-
Откройте настройки External Dependency Manager: Assets > External Dependency Manager > Android Resolver > Settings, включите следующие настройки.
- Use Jetifier.
- Patch mainTemplate.gradle.
- Patch gradleTemplate.properties.
-
Обновите зависимости проекта: Assets > External Dependency Manager > Android Resolver > Force Resolve.
Инициализация
UpdateBehaviour
UpdateBehaviour
— это параметр, определяющий поведение SDK.
При создании экземпляра RemoteConfigClientBuilder
, по умолчанию используется значение UpdateBehaviour.Default
с интервалом синхронизации 15 минут.
Различия в значениях UpdateBehaviour
UpdateBehaviour | Описание |
---|---|
| При инициализации каждый запрос конфигурации выполняется через запрос к серверу. Значение Этот тип инициализации отменяет процесс фонового обновления. |
| При инициализации запрос конфигурации выполняется из локального постоянного хранилища, которое обновляется в указанный интервал. Если инициализация выполняется первый раз и локальное постоянное хранилище пустое, запрос отправляется на сервер. Скорость выполнения запроса зависит от объема данных и скорости сети. Доступ к конфигурации будет ожидать завершения инициализации. Значение Этот тип инициализации запускает процесс фонового обновления. |
| При инициализации запрос конфигурации выполняется из локального inMemory-хранилища. inMemory-хранилище заполняется результатом первого запроса из постоянного хранилища и сохраняется в таком виде до конца жизни процесса. Если инициализация выполняется первый раз и локальное постоянное хранилище пустое, запрос отправляется на сервер. Скорость выполнения запроса зависит от объема данных и скорости сети. Доступ к конфигурации будет ожидать завершения инициализации. Значение Этот тип инициализации запускает процесс фонового обновления. |
Создание RemoteConfigClient
Инициализация RuStoreUnityRemoteConfigClient
с параметрами UpdateBehaviour.Default
и UpdateBehaviour.Snapshot
должна происходить в момент Application.onCreate()
, так как при запуске фоновой синхронизации SDK должна быть проинициализирована.
Для этого выполните расширение класса Application
и добавьте в метод onCreate
следующий код.
package ru.rustore.unitysdk;
import android.app.Application;
import ru.rustore.unitysdk.remoteconfigclient.RuStoreUnityRemoteConfigClient;
import ru.rustore.unitysdk.remoteconfigclient.model.RemoteConfigClientParameters;
import ru.rustore.unitysdk.remoteconfigclient.model.UnityRemoteConfigClientEventListener;
public class RuStoreRemoteConfigApplication extends Application {
public final String APP_ID = "a83c91d3-21b4-4891-841e-0ed0fc39a562";
public final int UPDATE_TIME = 15;
public final String UPDATE_BEHAVIOUR = "Default";
public RemoteConfigClientParameters parameters = null;
public UnityRemoteConfigClientEventListener listener = null;
@Override
public void onCreate() {
super.onCreate();
RuStoreUnityRemoteConfigClient.INSTANCE.init(APP_ID, UPDATE_TIME, UPDATE_BEHAVIOUR, parameters, listener, getApplicationContext());
}
}
APP_ID
— уникальный идентификатор инструмента Remote Config. Доступен в консоли разработчика RuStore на странице создания параметров Remote Config.UPDATE_TIME
— интервал таймера обновления в минутах.UPDATE_BEHAVIOUR
— параметр, определяющий поведение SDK. См. также Различия в значенияхUpdateBehaviour
.parameters
— опциональные параметры инициализации, реализация интерфейсаRemoteConfigClientParameters
.listener
— объект слушателя событий, реализация интерфейсаIRemoteConfigClientEventListener
.
Для замены класса Application
на RuStoreRemoteConfigApplication
добавьте атрибут android:name
к тегу application
в файле манифеста вашего проекта Assets/Plugins/Android/AndroidManifest.xml
.
<application
android:name="ru.rustore.unitysdk.RuStoreRemoteConfigApplication">
Инициализация плагина
Для доступа к методам SDK из C# выполните инициализацию плагина, используя метод Init
.
IRemoteConfigClientEventListener eventListener = /* Реализация интерфейса */;
RuStoreRemoteConfigClient.Instance.Init(eventListener);
Для работы в режиме UpdateBehaviour.Actual
инициализация может быть выполнена без создания расширения класса Application. При этом параметр APP_ID
должен быть передан из C#.
IRemoteConfigClientEventListener eventListener = /* Реализация интерфейса */;
var settings = new RuStoreRemoteConfigClientSettings() {
appId = APP_ID,
account = ACCOUNT,
language = LANGUAGE
};
RuStoreRemoteConfigClient.Instance.Init(settings, eventListener);
Опциональные параметры инициализации
- C#
- Java
Установить опциональные параметры инициализации в C# можно через экземпляр класса RuStoreRemoteConfigClientSettings
.
namespace RuStore.RemoteConfig {
public class RuStoreRemoteConfigClientSettings {
public enum Environment {
Default,
Alpha,
Beta,
Release,
}
public string appId;
public string osVersion;
public string deviceModel;
public string language;
public string account;
public string deviceId;
public string appVersion;
public Environment environment = Environment.Default;
public string appBuild;
}
}
Параметр | Описание |
---|---|
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 со значением, установленным в интерфейсе. |
Через методы setAccount
и setLanguage
можно установить дополнительные параметры, которые могут быть использованы для получения конкретной конфигурации.
string ACCOUNT = "MyAccount";
string LANGUAGE = "ru";
RuStoreRemoteConfigClient.Instance.SetAccount(ACCOUNT);
RuStoreRemoteConfigClient.Instance.SetLanguage(LANGUAGE);
Установить опциональные параметры инициализации можно через интерфейс RemoteConfigClientParameters
. Объект реализующий интерфейс должен быть передан в методе инициализации RuStoreUnityRemoteConfigClient
.
package ru.rustore.unitysdk.remoteconfigclient.model;
public interface RemoteConfigClientParameters {
String getOsVersion();
String getDeviceModel();
String getDeviceId();
String getAppVersion();
String getEnvironment();
String getAppBuild();
}
Параметр | Описание |
---|---|
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 со значением, установленным в интерфейсе. |
Через методы setAccount
и setLanguage
можно установить дополнительные параметры, которые могут быть использованы для получения конкретной конфигурации.
String ACCOUNT = "MyAccount";
String LANGUAGE = "ru";
RuStoreUnityRemoteConfigClient.INSTANCE.setAccount(ACCOUNT);
RuStoreUnityRemoteConfigClient.INSTANCE.setLanguage(LANGUAGE);
IRemoteConfigClientEventListener
Реализация RemoteConfigClientEventListener
дает возможность получать обратные вызовы (callback) о работе SDK, такие как завершение инициализации и обновление постоянного хранилища.
- C#
- Java
Объект реализующий интерфейс должен быть передан в методе инициализации плагина.
namespace RuStore.RemoteConfig {
public interface IRemoteConfigClientEventListener {
public void InitComplete();
public void RemoteConfigNetworkRequestFailure(RuStoreError error);
}
}
InitComplete
— вызывается при окончании инициализации.RemoteConfigNetworkRequestFailure
— вызывается при ошибке сетевого запроса Remote Config.
Объект реализующий интерфейс должен быть передан в методе инициализации RuStoreUnityRemoteConfigClient
.
package ru.rustore.unitysdk.remoteconfigclient.model;
public interface UnityRemoteConfigClientEventListener {
void backgroundJobErrors(Throwable exception);
void firstLoadComplete();
void initComplete();
void memoryCacheUpdated();
void persistentStorageUpdated();
void remoteConfigNetworkRequestFailure(Throwable throwable);
}
backgroundJobErrors
— возвращает ошибку фоновой работы.firstLoadComplete
— вызывается при окончании первой загрузки.initComplete
— вызывается при окончании инициализации.memoryCacheUpdated
— вызывается при изменении кэша в памяти.persistentStorageUpdated
— вызывается при изменении постоянного хранилища.remoteConfigNetworkRequestFailure
— вызывается при ошибке сетевого запроса Remote Config.
Получение конфигурации
Получение конфигурации происходит через вызов метода GetRemoteConfig
.
RuStoreRemoteConfigClient.Instance.GetRemoteConfig(
onSuccess: (response) => {
// Process success
},
onFailure: (error) => {
// Process error
});
-
Обратный вызов (callback)
Success
возвращает структуруRemoteConfig
с информацией от текущем наборе данных в параметреResponse
. -
Обратный вызов (callback)
Failure
возвращает структуруRuStoreError
с информацией об ошибке в параметреError
. Все ошибки описаны в разделе Возможные ошибки.
Класс RemoteConfig
Экземпляр RemoteConfig
– это текущий набор всех данных, полученных в зависимости от выбранной политики обновления при инициализации.
Объект содержит весь набор ключей, которые были переданы с сервера, в зависимости от параметров, указанных при инициализации. Для получения данных используются методы для извлечени и приведения к определенным типам.
namespace RuStore.RemoteConfig {
public abstract class RemoteConfig {
public abstract bool ContainsKey(string key);
public abstract bool GetBool(string key);
public abstract int GetInt(string key);
public abstract long GetLong(string key);
public abstract string GetString(string key);
public abstract double GetDouble(string key);
public abstract float GetFloat(string key);
}
}
Возможные ошибки
Если вы получили в ответ Failure
, не рекомендуется отображать ошибку пользователю. Отображение ошибки может негативно повлиять на пользовательский опыт.
namespace RuStore {
public class RuStoreError {
public string name;
public string description;
}
}
name
— название ошибки. Содержит имяsimpleName
класса ошибки.description
— сообщение ошибки.
Ошибка | Описание |
---|---|
BackgroundConfigUpdateError | Появляется при ошибке в работе фоновой синхронизации. |
FailedToReceiveRemoteConfig | Появляется в случае ошибки при вызове метода получения конфигурации. |
RemoteConfigCastException | Появляется в случае некорректного получения данных по ключу из класса RemoteConfig . Ошибка может быть связана с невозможностью приведения к типу, либо значение по передаваемому ключу отсутствует. |
RemoteConfigClientAlreadyExist | Появляется в случае повторного создания RemoteConfigClient в рамках жизни процесса. |
RemoteConfigClientNotCreated | Появляется в случае доступа к RemoteConfigClient через статическое поле instance до создания RemoteConfigClient . |
RemoteConfigCommonException | Общая непредвиденная ошибка. |
RemoteConfigNetworkException | Появляется при сетевой ошибке. |