跳到主要内容

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

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

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

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

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

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

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

Для подключения скачайте RuStore RemoteConfig SDK и импортируйте его в проект (Assets > Import Package > Custom Package). Зависимости подключаются автоматически с помощью External Dependency Manager (включен в SDK).

提示

Если вы используете операционную систему macOS, измените настройки утилиты архивации. В настройках Archive Utility снимите флажок Keep expanding if possible. В противном случае архив проекта будет скачан некорректно.

Также вы можете склонировать код с помощью Git.

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

  1. Откройте настройки проекта: Edit > Project Settings > Player > Android Settings.

  2. В pазделе Publishing Settings включите следующие настройки.

    • Custom Main Manifest.
    • Custom Main Gradle Template.
    • Custom Gradle Properties Template.

  3. В разделе Other Settings настройте:

    • package name.
    • Minimum API Level = 24.
    • Target API Level = 34.

  4. Откройте настройки External Dependency Manager: Assets > External Dependency Manager > Android Resolver > Settings, включите следующие настройки.

    • Use Jetifier.
    • Patch mainTemplate.gradle.
    • Patch gradleTemplate.properties.

  5. Обновите зависимости проекта: Assets > External Dependency Manager > Android Resolver > Force Resolve.

Обновление

Версии плагина 6.1.0 и выше содержат измененную структуру директорий. Измененная структура позволяет использовать преимущества раздельных сборок частей проекта Assembly definitions.

Перед установкой обновления выполните удаление следующих папок.

  • Assets > RuStoreSDK > RemoteConfigClient > Editor.
  • Assets > RuStoreSDK > Common > Editor.
img

После удаления импортируйте новый .unitypackage в проект как при обычной установке (Assets > Import Package > Custom Package).

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

UpdateBehaviour​

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

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

UpdateBehaviourОписание

Actual

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

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

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

Default

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

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

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

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

Snapshot

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

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

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

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

Создание RemoteConfigClient​

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

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

Файл RuStoreRemoteConfigApplication.java
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.

AndroidManifest.xml
<application
    android:name="ru.rustore.unitysdk.RuStoreRemoteConfigApplication">

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

Для доступа к методам SDK из C# выполните инициализацию плагина, используя метод Init.

Вызов метода Init
IRemoteConfigClientEventListener eventListener = /* Реализация интерфейса */;

RuStoreRemoteConfigClient.Instance.Init(eventListener);

Для работы в режиме UpdateBehaviour.Actual инициализация может быть выполнена без создания расширения класса Application. При этом параметр APP_ID должен быть передан из C#.

Вызов метода Init
IRemoteConfigClientEventListener eventListener = /* Реализация интерфейса */;

var settings = new RuStoreRemoteConfigClientSettings() {
    appId = APP_ID,
    account = ACCOUNT,
    language = LANGUAGE
};

RuStoreRemoteConfigClient.Instance.Init(settings, eventListener);

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

Установить опциональные параметры инициализации в C# можно через экземпляр класса RuStoreRemoteConfigClientSettings.

Класс 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 можно установить дополнительные параметры, которые могут быть использованы для получения конкретной конфигурации.

Вызов методов SetAccount и SetLanguage в C#
string ACCOUNT = "MyAccount";
string LANGUAGE = "ru";

RuStoreRemoteConfigClient.Instance.SetAccount(ACCOUNT);
RuStoreRemoteConfigClient.Instance.SetLanguage(LANGUAGE);

IRemoteConfigClientEventListener​

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

Объект реализующий интерфейс должен быть передан в методе инициализации плагина.

Интерфейс IRemoteConfigClientEventListener
namespace RuStore.RemoteConfig {

    public interface IRemoteConfigClientEventListener {

        public void InitComplete();
        public void RemoteConfigNetworkRequestFailure(RuStoreError error);
    }
}
  • InitComplete — вызывается при окончании инициализации.
  • RemoteConfigNetworkRequestFailure — вызывается при ошибке сетевого запроса Remote Config.

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

Получение конфигурации происходит через вызов метода GetRemoteConfig.
Вызов метода GetRemoteConfig
RuStoreRemoteConfigClient.Instance.GetRemoteConfig(
    onSuccess: (response) => {
        // Process success
    },
    onFailure: (error) => {
        // Process error
    });

  • Обратный вызов (callback) Success возвращает структуру RemoteConfig с информацией от текущем наборе данных в параметре Response.

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

Класс RemoteConfig​

Экземпляр 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, не рекомендуется отображать ошибку пользователю. Отображение ошибки может негативно повлиять на пользовательский опыт.

Класс RuStoreError
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Появляется при сетевой ошибке.