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

SDK Install Referrer для Kotlin (версия 10.0.0)

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 дней, после чего удаляется.

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

Важно

Минимально поддерживаемая версия Kotlin — 1.8

Минимальная версия Android SDK — определяется настройками проекта.

Добавление репозитория​

build.gradle
repositories {
    maven {
        url = uri("https://artifactory-external.vkpartner.ru/artifactory/maven")
    }
}

Подключение зависимости​

build.gradle
dependencies {
    implementation("ru.rustore.sdk:installreferrer:10.0.0")
}

Создание InstallReferrerClient​

Для работы с referrer создайте InstallReferrerClient при помощи конструктора класса:

Инициализация
val client = InstallReferrerClient(context)

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

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

client.getInstallReferrer()
    .addOnSuccessListener { result ->
        // Сохранение InstallReferrer
    }
    .addOnFailureListener { throwable ->
        // Обработка ошибки
    }

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

    примечание

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

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

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

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

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

SDK RuStore Install referrer начиная с версии 10.0.0 имеет возможность передавать номер телефона авторизовавшегося пользователя в систему Full Stream Attribution.

к сведению

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

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

val phoneNumber = PhoneNumber("1234567890")
val authEvent = AuthEvent(phoneNumber, "authToken")
 
client.sendAuthEvent(authEvent)
    .addOnSuccessListener {
        // Событие успешно отправлено
    }
    .addOnFailureListener { throwable ->
        // Обработка ошибки
    }

Для отправки телефона в систему Full Stream Attribution необходимо передать в SDK токен авторизации (authToken).

подсказка

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

SDK осуществляет передачу номера телефона и токена авторизации на сервер VK Рекламы.

Методы обработки результатов​

Класс Task предоставляет несколько методов для обработки результатов:

  • addOnCompletionListener() — оба результата: и успешный и с ошибкой.
  • addOnSuccessListener() — только успешный результат.
  • addOnFailureListener() — только результат с ошибкой.

Подробнее об этих методах — в статье Task API.

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

client.getInstallReferrer()
    .addOnCompletionListener { cause ->
        if (cause == null) {
            // Task завершен успешно
        } else {
            // Task завершен с ошибкой
        }
    }

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

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

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

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

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