Перейти к основному содержимому

SDK Install Referrer для Unity (версия 10.6.1)

SDK Install referrer — инструмент атрибуции для рекламных и аналитических систем. Он позволяет отслеживать количество установок вашего приложения, загруженных из RuStore по рекламным ссылкам.

RuStore принимает ссылки вида https://www.rustore.ru/catalog/app/com.packagename.yourapp?referrerId=<referrer>.

Когда пользователь переходит по рекламной ссылке и запускает установку приложения, RuStore сохраняет значение referrer из этой ссылки. SDK обращается к RuStore, запрашивает значение referrer и передает его в ваше приложение в параметре InstallReferrer. Таким образом приложение получает информацию о том, что при переходе по определенной рекламной ссылке была выполнена установка.

После того как RuStore передает SDK значение referrer, оно удаляется из RuStore. Даже если SDK не запросил referrer, это значение хранится в RuStore только 10 дней, после чего удаляется.

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

Установка плагинов​

Из сетевого расположения (рекомендуется)

Пакеты RuStore публикуются в npm-registry и подключаются к проекту через Package Manager без ручного скачивания архивов.

  1. Откройте настройки: Edit → Project Settings → Package Manager.

  2. В разделе Scoped Registries нажмите + и заполните поля:

    • Name — RuStore Nexus;
    • URL — https://nexus-external.vkteam.ru/repository/npm-unity-rustore-exposed/;
    • Scopes — ru.rustore.
Настройка scoped registry в Unity

  1. Откройте Window → Package Manager — в списке источников появится реестр RuStore Nexus.

  2. Выберите RuStore Nexus и установите пакет ru.rustore.installreferrer кнопкой Install. Зависимость ru.rustore.core установится автоматически.

Настройка scoped registry в Unity

Из локального расположения

Для подключения скачайте со страницы релизов пакеты:

  • ru.rustore.core-version.tgz
  • ru.rustore.installreferrer-version.tgz

Импортируйте пакеты в проект через Package Manager (Window → Package Manager → + → Add package from tarball...).

подсказка

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

Для корректной обработки зависимостей 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.

Решение зависимостей​

Зависимости Android-сборки подключаются автоматически с помощью инструмента External Dependency Manager.

Для автоматического решения зависимостей воспользуйтесь командой: Assets → External Dependency Manager → Android Resolver → Force Resolve. Эту операцию следует выполнять каждый раз при добавлении новых версий плагинов или пересоздании файлов Assets / Plugins / Android / mainTemplate.gradle и Assets / Plugins / Android / settingsTemplate.gradle.

  • При установке плагинов RuStore через *.unitypackage External Dependency Manager не требует специальной установки.

  • При установке плагинов RuStore через Package Manager выполните следующие действия:

    • Откройте вкладку плагина RuStore Core в окне менеджера пакетов: Window → Package Manager → Packages RuStore → RuStore Core.
    • Перейдите на вкладку Samples.
    • Импортируйте сэмпл External Dependency Manager.

  • Последнюю версию External Dependency Manager также можно получить из репозитория разработчика на GitHub:

    • Откройте окно менеджера пакетов: 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.
Ошибка Google.IOSResolver.dll
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.

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

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

Инициализация InstallReferrerClient
InstallReferrerClient.Instance.Init();

Получение объекта InstallReferrer​

Вызовите GetInstallReferrer(), чтобы получить InstallReferrer:

Вызов метода GetInstallReferrer
InstallReferrerClient.Instance.GetInstallReferrer(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (result) => {
        // Process result
    });
})

  • При ответе onSuccess сохраните значение InstallReferrer в вашем приложении, если вы планируете его использовать. При повторном запросе вместо значения InstallReferrer вернется null.

    примечание

    InstallReferrer принимает значение null, если:

    • Приложение было установлено без передачи referrer.
    • InstallReferrer уже запрашивался ранее.
    • С того момента, как RuStore получил referrer, прошло 10 или более суток.

  • При ответе onFailure обработайте ошибку в соответствии с логикой вашего приложения. Все возможные ошибки описаны в разделе Возможные ошибки.

Класс InstallReferrer
public class InstallReferrer {

    public long installAppTimestamp { get; }
    public string packageName { get; }
    public long receivedTimestamp { get; }
    public string referrerId { get; }
    public long? versionCode { get; }
    public string? utmCampaign { get; }
    public string? utmGroup { get; }
    public string? utmBanner { get; }
	
    ...
}
  • installAppTimestamp — время установки приложения в виде метки времени.
  • packageName — имя пакета приложения.
  • receivedTimestamp — время получения данных о реферере в виде метки времени.
  • referrerId — идентификатор реферера.
  • versionCode — версия кода приложения, если доступна.
  • utmCampaign — название кампании.
  • utmGroup — название группы объявлений.
  • utmBanner — идентификатор баннера.

Пример оформления реферальной ссылки:

https://www.rustore.ru/catalog/app/ru.rustore.installreferrer?referrerId=test0&utm_campaign=test1&utm_group=test2&utm_banner=test3

Передача информации в ВК Реклама Full Stream Attribution​

Full Stream Attribution — технология, которая обеспечивает практически мгновенную передачу пользовательских сигналов от рекламодателя в систему оптимизации VK Рекламы. Это позволяет модели буквально в режиме реального времени корректировать стратегию показа и с высокой точностью попадать в интересы конкретного пользователя.

SDK RuStore Install referrer начиная с версии 10.3.0 имеет возможность передавать номер телефона авторизовавшегося пользователя (с версии 10.0.0), токен авторизации и типа события в систему Full Stream Attribution.

Для передачи номера телефона, токена авторизации и типа события в SDK используйте следующий метод:

Вызов метода FsaEvent
var phoneNumber = new PhoneNumber("81234567890");
var authToken = "Token";
var fsaEventType = new FsaEventType.ViewOffer("product_id");

var fsaEvent = new FsaEvent(phoneNumber, authToken, fsaEventType);

InstallReferrerClient.Instance.SendFsaEvent(
    fsaEvent: fsaEvent,
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    }
);
  • fsaEvent — данные события Full Stream Attribution.

Передача номера телефона не является обязательной и не работает, если явно не включить данный функционал в SDK. Также для отправки номера телефона в систему Full Stream Attribution необходимо передать в SDK токен авторизации (authToken).

подсказка

Токен авторизации authToken необходимо запросить у менеджера VK Рекламы.

SDK осуществляет передачу данных FsaEvent на сервер VK Рекламы.

Класс FsaEvent
public class FsaEvent : BaseFields {

    public PhoneNumber phoneNumber { get; }
    public string authToken { get; }
    public FsaEventType eventType { get; }

    public FsaEvent(
        PhoneNumber phoneNumber,
        string authToken,
        FsaEventType eventType
    ) { ... }
}
  • phoneNumber — номер телефона.
    • Примеры корректных номеров:
      • 79991234567 — ровно 11 цифр.
      • +7 (999) 123-45-67 — 11 цифр после нормализации.
      • 8(999)1234567 — 11 цифр после нормализации.
    • Примеры некорректных номеров:
      • 123 — слишком короткий (3 цифры).
      • 12345678901234567890 — слишком длинный (20 цифр).
      • abc-def — после нормализации 0 цифр.
  • authToken — токен авторизации.
  • eventType — тип события.
Класс FsaEventType
public abstract class FsaEventType {
    public static string NameOf<T>() where T : FsaEventType => typeof(T).Name;

    private FsaEventType() { }

    public sealed class Install : FsaEventType {
        public Install() { }
    }
	
    public sealed class ViewOffer : FsaEventType {
        public string productId { get; }
        public ViewOffer(string productId) {
            this.productId = productId;
        }
    }

    public sealed class AddToCart : FsaEventType {
        public string productId { get; }
        public AddToCart(string productId) {
            this.productId = productId;
        }
    }

    public sealed class Purchase : FsaEventType {
        public string productId { get; }
        public Purchase(string productId) {
            this.productId = productId;
        }
    }

    public sealed class AddToWishlist : FsaEventType {
        public string productId { get; }
        public AddToWishlist(string productId) {
            this.productId = productId;
        }
    }
}
  • Install — установка приложения / первая авторизация.
  • ViewOffer — просмотр предложения.
  • AddToCart — добавление в корзину.
  • Purchase — покупка.
  • AddToWishlist — добавление в список желаний.

VKR-аналитика​

VKR (VK Referrer Analytics) — дополнительная аналитика, которая автоматически отправляет данные реферера при вызове getInstallReferrer().

Условия активации​

VKR работает только если в AndroidManifest.xml приложения добавлен мета-тег:

<meta-data
    android:name="ru.rustore.sdk.install.referrer.ENABLE_VKR_ANALYTICS"
    android:value="true" />

Если мета-тег отсутствует — VKR полностью отключен.

Поведение​

  • Запускается автоматически при успешном getInstallReferrer() если получен не-null реферер.
  • Передает referrerId, UTM-поля, текущий timestamp и GAID (Google Advertising ID).
  • Ошибки VKR не влияют на результат getInstallReferrer() — они подавляются внутри SDK.

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

  • RuStoreNotInstalledException — на устройстве пользователя не установлен RuStore.

  • RuStoreOutdatedException — версия RuStore, установленная на устройстве пользователя, не поддерживает данный SDK.

  • RuStoreException — базовая ошибка RuStore, от которой наследуются остальные ошибки.

  • InstallReferrerException.ClientNotCreated — ошибка создания клиента Install Referrer.

  • InstallReferrerException.InvalidPhoneNumberException — неверный формат номера телефона.