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

SDK Push-уведомления для Kotlin/Java (версия 7.5.0)

Как push-sdk получает уведомления​

На мобильном устройстве пользователя должно быть установлено приложение, которое отвечает за доставку push-уведомлений от нашего SDK. Такое приложение называется «дистрибьютором». Оно периодически обращается к серверу, проверяет наличие новых уведомлений для конкретного приложения, где включен наш SDK, и при их появлении отправляет push-уведомления в конечное приложение.

Основным дистрибьютором служит RuStore, однако если у пользователя нет RuStore, роль резервного дистрибьютора может взять на себя одно из других приложений VK. Выбор делается удаленно на сервере, поэтому мы не раскрываем полный список возможных резервных вариантов. Состав приложений-дистрибьюторов может динамически меняться, поэтому на устройстве конкретного пользователя в любой момент может оказаться другое приложение в этой роли.

Для проверки того, что приложение-дистрибьютор установлено на устройстве пользователя, используйте метод RuStorePushClient.checkPushAvailability.

На устройстве пользователя только одно приложение может работать в качестве дистрибьютора, остальные находятся в "спящем" режиме. Если дистрибьютор был удален с устройства или у него изменились настройки, которые могут влиять на доставку push-уведомлений, то новый дистрибьютор автоматически выберется из резервных.

Условия работы push-уведомлений​

Ниже перечислены условия работы push-уведомлений.

Важно
  • Подпись и package name различных типов сборок вашего приложения (debug, release и т.д.) могут отличаться друг от друга. В таком случае вы должны создать в разделе Push-уведомления > Проекты из RuStore Консоль проект под каждый тип сборки..
  • Используется актуальная версия SDK.
  • Загружены данные о приложении в разделе Push-уведомления > Проекты из RuStore Консоль.

  • На устройстве пользователя установлено приложение-дистрибьютор (RuStore и т.д.)

    Для проверки того, что приложение-дистрибьютор установлено на устройстве пользователя, используйте метод RuStorePushClient.checkPushAvailability..
  • Если установлено приложение RuStore, то ему разрешен доступ к работе в фоновом режиме. Без этого разрешения push-уведомления будут приходить, но со значительной задержкой.
  • Отпечаток подписи приложения, установленного на девайсе, совпадает с отпечатком подписи приложения, которое добавлено в разделе Push-уведомления > Проекты из RuStore Консоль.

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

Ознакомьтесь с приложением-примером, чтобы узнать, как правильно интегрировать SDK push-уведомлений:

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

Важно

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

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

build.gradle
repositories {
    maven {
        url = uri("https://nexus-external.rustore.ru/repository/maven-rustore-exposed/")
    }
}
Важно

Если для получения артефактов вы использовали репозиторий https://artifactory-external.vkpartner.ru/artifactory/maven, перейдите на новый адрес https://nexus-external.rustore.ru/repository/maven-rustore-exposed/. В какой-то момент старый репозиторий может перестать работать.

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

build.gradle
dependencies {
    implementation("ru.rustore.sdk:pushclient:7.5.0")
}

Редактирование манифеста приложения​

Объявите службу, расширяющую RuStoreMessagingService.

AndroidManifest.xml
<service
    android:name=".MyRuStoreMessagingService"
    android:exported="true"
    tools:ignore="ExportedService">
    <intent-filter>
        <action android:name="ru.rustore.sdk.pushclient.MESSAGING_EVENT" />
    </intent-filter>
</service>

Если нужно изменить иконку или цвет стандартной нотификации, добавьте следующий код.

AndroidManifest.xml
<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_icon"
    android:resource="@drawable/ic_baseline_android_24" />
<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_color"
    android:resource="@color/your_favorite_color" />

Если нужно переопределить канал уведомлений, добавьте следующий код.

AndroidManifest.xml
<meta-data
    android:name="ru.rustore.sdk.pushclient.default_notification_channel_id"
    android:value="@string/pushes_notification_channel_id" />

При добавлении канала push-уведомлений вы должны создать канал самостоятельно.

Запрос разрешения на показ уведомлений в Android 13+​

В версии Android 13 появилось новое разрешение для отображения push-уведомлений. Это затронет все приложения, которые работают на Android 13 или выше и используют RuStore Push SDK.

По умолчанию RuStore Push SDK версии 1.4.0 и выше включает разрешение POST_NOTIFICATIONS, определенное в манифесте. Однако приложению также нужно запросить это разрешение во время выполнения через константу android.permission.POST_NOTIFICATIONS. Приложение сможет показывать push-уведомления, только когда пользователь предоставит на это разрешение.

Запрос разрешения на показ push-уведомлений.

Activity/Fragment
// Declare the launcher at the top of your Activity/Fragment:
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission(),
) { isGranted: Boolean ->
    if (isGranted) {
      // RuStore Push SDK (and your app) can post notifications.
    } else {
      // TODO: Inform user that your app will not show notifications.
    }
}

private fun askNotificationPermission() {
    // This is only necessary for API level>= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT>= Build.VERSION_CODES.TIRAMISU) {
         if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                 PackageManager.PERMISSION_GRANTED) {
             // RuStore Push SDK (and your app) can post notifications.
         } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
             // TODO: display an educational UI explaining to the user the features that will be enabled
             //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
             //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
             //       If the user selects "No thanks," allow the user to continue without notifications.
         } else {
             // Directly ask for the permission
             requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
         }
    }
}

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

Для инициализации понадобится идентификатор проекта из RuStore Консоль. Чтобы получить его, на странице приложения перейдите в раздел Push-уведомления > Проекты и скопируйте значение в поле ID проекта.

img
Обратите внимание

Обратите внимание, что Push SDK не поддерживает работу в нескольких процессах одновременно.
Если ваше приложение использует несколько процессов, необходимо инициализировать SDK только в главном процессе.

Если инициализация происходит в дополнительном процессе, это может привести к некорректной работе push-уведомлений.

Ручная инициализация в Application​

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

Инициализация
class App : Application() {
 
    override fun onCreate() {
        super.onCreate()
        RuStorePushClient.init(
            application = this,
            projectId = "i5UTx96jw6c1C9LvdlE4cdNrWHMNyRBt",
            logger = DefaultLogger()
        )
    }
}
  • application — экземпляр класса Application.
  • projectId — идентификатор вашего проекта из RuStore Консоль.
  • logger — логгер, по умолчанию используется вывод в logcat (опционально).

Инициализация в фоновом потоке​

Начиная с версии 7.4.0 SDK можно инициализировать не в главном потоке — метод RuStorePushClient.init() можно вызывать из любого потока. Требование вызывать инициализацию в Application.onCreate() при этом сохраняется — запуск инициализации должен стартовать именно там.

Все публичные методы SDK потокобезопасны: если какой-либо компонент SDK (сервис, броадкастресивер, вызов через IPC) обратится к SDK до завершения инициализации, он подождет ее завершения не более 5 секунд.

Обратите внимание

Если инициализация не успеет завершиться за 5 секунд, асинхронные методы RuStorePushClient, возвращающие Task, завершатся с ошибкой SdkIsNotInitializedException. Оборачивать методы SDK в try catch не нужно — эта ошибка будет передана в addOnFailureListener.

Важно

Рекомендуем логировать ошибку SdkIsNotInitializedException в системе мониторинга крашей. Рост числа таких ошибок означает, что инициализация SDK не успевает завершиться за 5 секунд, например, из-за тяжелых операций в Application.onCreate() перед вызовом init(). Если вы часто наблюдаете такую ошибку, то попробуйте пересмотреть архитектуру инициализации push SDK в вашем приложении.

Инициализация в фоновом потоке
class App : Application() {

    override fun onCreate() {
        super.onCreate()

        CoroutineScope(Dispatchers.Default).launch {
            RuStorePushClient.init(
                application = this@App,
                projectId = "i5UTx96jw6c1C9LvdlE4cdNrWHMNyRBt",
                logger = DefaultLogger()
            )
        }
    }
}

Пример обработки ошибки SdkIsNotInitializedException.

Обработка ошибки SdkIsNotInitializedException
RuStorePushClient.getToken()
    .addOnSuccessListener { token ->
        // используем токен
    }
    .addOnFailureListener { throwable ->
        if (throwable is SdkIsNotInitializedException) {
            // SDK не успел проинициализироваться за 5 секунд
        }
    }

Автоматическая инициализация​

Для автоматической инициализации добавьте в AndroidManifest.xml следующий код.

AndroidManifest.xml
<meta-data
    android:name="ru.rustore.sdk.pushclient.project_id"
    android:value="i5UTx96jw6c1C9LvdlE4cdNrWHMNyRBt" />
<meta-data
    android:name="ru.rustore.sdk.pushclient.params_class"
    android:value="com.example.RuStorePushClientParams" />
  • projectId — идентификатор вашего проекта из RuStore Консоль.
  • (опционально) com.example.RuStorePushClientParams — полное имя класса своей реализации AbstractRuStorePushClientParams или SimpleRuStorePushClientParams. Нужен для указания дополнительных параметров инициализации push-клиента.

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

RuStorePushClientParams
class RuStorePushClientParams(context: Context) 
  : AbstractRuStorePushClientParams(context) {

    override fun getLogger(): Logger = DefaultLogger("your_tag")

    override fun getTestModeEnabled(): Boolean = false

    override fun getClientIdCallback(): ClientIdCallback =
        ClientIdCallback { ClientId("your_gaid_or_oaid", ClientIdType.GAID) }
}
предупреждение

В реализации класса AbstractRuStorePushClientParams должен быть только один конструктор с одним аргументом Context.

Ручной вызов RuStorePushClient.init() после автоматической инициализации будет проигнорирован.

Логирование событий​

Если вы хотите логировать события библиотеки push-уведомлений, добавьте в вызов RuStorePushClient.init параметр logger. Этот параметр необязателен для инициализации.

Создайте интерфейс Logger.

Интерфейс Logger
interface Logger {
    fun verbose(message: String, throwable: Throwable? = null)
    fun debug(message: String, throwable: Throwable? = null)
    fun info(message: String, throwable: Throwable? = null)
    fun warn(message: String, throwable: Throwable? = null)
    fun error(message: String, throwable: Throwable? = null)
 
    fun createLogger(tag: String): Logger
}

Если не передать Logger, SDK использует реализацию по умолчанию с AndroidLog.

Пример реализации логгера
public class DefaultLogger(
    private val tag: String? = null,
) : Logger {
    override fun verbose(message: String, throwable: Throwable?) {
        Log.v(tag, message, throwable)
    }
 
    override fun debug(message: String, throwable: Throwable?) {
        Log.d(tag, message, throwable)
    }
 
    override fun info(message: String, throwable: Throwable?) {
        Log.i(tag, message, throwable)
    }
 
    override fun warn(message: String, throwable: Throwable?) {
        Log.w(tag, message, throwable)
    }
 
    override fun error(message: String, throwable: Throwable?) {
        Log.e(tag, message, throwable)
    }
 
    override fun createLogger(tag: String): Logger {
        val newTag = if (this.tag != null) {
            "${this.tag}:$tag"
        } else {
            tag
        }
        return DefaultLogger(newTag)
    }
}

Проверка возможности получать push-уведомления​

Ниже перечислены условия работы push-уведомлений.

Важно
  • Подпись и package name различных типов сборок вашего приложения (debug, release и т.д.) могут отличаться друг от друга. В таком случае вы должны создать в разделе Push-уведомления > Проекты из RuStore Консоль проект под каждый тип сборки..
  • Используется актуальная версия SDK.
  • Загружены данные о приложении в разделе Push-уведомления > Проекты из RuStore Консоль.

  • На устройстве пользователя установлено приложение-дистрибьютор (RuStore и т.д.)

    Для проверки того, что приложение-дистрибьютор установлено на устройстве пользователя, используйте метод RuStorePushClient.checkPushAvailability..
  • Если установлено приложение RuStore, то ему разрешен доступ к работе в фоновом режиме. Без этого разрешения push-уведомления будут приходить, но со значительной задержкой.
  • Отпечаток подписи приложения, установленного на девайсе, совпадает с отпечатком подписи приложения, которое добавлено в разделе Push-уведомления > Проекты из RuStore Консоль.
Для проверки того, что приложение-дистрибьютор установлено на устройстве пользователя, используйте метод RuStorePushClient.checkPushAvailability.
Пример реализации RuStorePushClient.checkPushAvailability
RuStorePushClient.checkPushAvailability()
    .addOnSuccessListener { result ->
        when (result) {
            FeatureAvailabilityResult.Available -> {
                // Process push available
            }

            is FeatureAvailabilityResult.Unavailable -> {
                result.cause.resolveForPush(requireContext())
            }
        }
    }
    .addOnFailureListener { throwable ->
        // Process error
    }

Методы для работы с push-токеном​

Получение push-токена пользователя​

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

Если у пользователя нет push-токена, метод создаст и вернет новый push-токен.

После инициализации библиотеки вы можете использовать метод RuStorePushClient.getToken(), чтобы получить текущий push-токен пользователя.
Пример реализации RuStorePushClient.getToken
RuStorePushClient.getToken()
    .addOnSuccessListener { result ->
        // Process success
    }
    .addOnFailureListener { throwable ->
        // Process error
    }

Удаление push-токена пользователя​

После инициализации библиотеки вы можете использовать метод RuStorePushClient.deleteToken(), чтобы удалить текущий push-токен пользователя.
Пример реализации RuStorePushClient.deleteToken
RuStorePushClient.deleteToken()
    .addOnSuccessListener { result ->
        // Process success
    }
    .addOnFailureListener { throwable ->
        // Process error
    }

Методы для работы с push-топиком​

Подписка на push-уведомления по топику​

После инициализации библиотеки вы можете использовать метод RuStorePushClient.subscribeToTopic(your_topic_name) для подписки на топик.
Пример реализации RuStorePushClient.subscribeToTopic(your_topic_name)
RuStorePushClient.subscribeToTopic("your_topic_name")
    .addOnSuccessListener { result ->
        // Process subscribe success
    }
    .addOnFailureListener { throwable ->
        // Process subscribe error
    }

Отписка от push-уведомлений по топику​

После инициализации библиотеки вы можете использовать метод RuStorePushClient.unsubscribeFromTopic(your_topic_name) для отписки от топика.
Пример реализации RuStorePushClient.unsubscribeFromTopic(your_topic_name)
RuStorePushClient.unsubscribeFromTopic("your_topic_name")
    .addOnSuccessListener { result ->
        // Process unsubscribe success
    }
    .addOnFailureListener { throwable ->
        // Process unsubscribe error
    }

Получение данных от RuStore SDK​

Чтобы получить данные от RuStore SDK, создайте свой сервис, который наследуется от RuStoreMessagingService.

warning

Ваш сервис должен обработать любой метод в течение 20 секунд с момента вызова. По истечении этого времени сервис может быть убит системой.

RuStoreMessagingService
class MessagingService: RuStoreMessagingService() {
     
    override fun onNewToken(token: String) {
    }

    override fun onMessageReceived(message: RemoteMessage) {
    }

    override fun onDeletedMessages() {
    }

    override fun onError(errors: List<RuStorePushClientException>) {
    }
}
Название методаОписание

onNewToken

Метод вызывается при получении нового push-токена. После вызова этого метода ваше приложение становится ответственно за передачу нового push-токена на свой сервер. Метод возвращает значение нового токена.

onMessageReceived

Метод вызывается при получении нового push-уведомления.

Если в объекте notification есть данные, RuStore SDK самостоятельно отображает уведомление. Если вы не хотите этого, используйте объект data, а notification оставьте пустым. Метод вызывается в любом случае.

Получить payload push-уведомления Map<String, String> можно из поля message.data.

onDeletedMessages

Метод вызывается, если один или несколько push-уведомлений не доставлены на устройство. Например, если время жизни уведомления истекло до момента доставки.

При вызове этого метода рекомендуется синхронизироваться со своим сервером, чтобы не пропустить данные.

onError

Метод вызывается, если в момент инициализации возникает ошибка. Он возвращает массив объектов с ошибками.

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

  • UnauthorizedException — пользователь не авторизован в RuStore. Ошибка может не возникать, даже если пользователь не авторизован в RuStore. Это поведение управляется динамически в Push SDK. Если ваши пользователи не получают такую ошибку, то все равно имеет смысл ее обрабатывать;
  • HostAppNotInstalledException — RuStore отсутствует на устройстве пользователя;
  • HostAppBackgroundWorkPermissionNotGranted — у RuStore нет разрешения на работу в фоне. Ошибка не критична. Пуши продолжат приходить, но хуже, чем если бы разрешение на работу в фоне было выдано.

Все перечисленные методы вызываются в фоновом потоке.

Структура уведомления​

Структура полного уведомления
public data class RemoteMessage(
    val messageId: String?,
    val priority: Int,
    val ttl: Int,
    val from: String,
    val collapseKey: String?,
    val data: Map<String, String>,
    val rawData: ByteArray?,
    val notification: Notification?
)
  • messageId — уникальный ID сообщения. Является идентификатором каждого сообщения.
  • priority — возвращает значение приоритетности (на данный момент не учитывается). Сейчас заложены следующие варианты:
    • 0 — UNKNOWN;
    • 1 — HIGH;
    • 2 — NORMAL.
  • ttl — время жизни push-уведомления типа Int в секундах.
  • from — поле, по которому можно понять, откуда пришло уведомление:
    • для уведомлений, отправленных в топик, в поле отображается имя топика;
    • в других случаях — часть вашего сервисного токена.
    .
  • collapseKey — идентификатор группы уведомлений (на данный момент не учитывается).
  • data — словарь, в который можно передать дополнительные данные для уведомления.
  • rawData — словарь data в виде массива байтов.
  • notification — объект уведомления.
Структура объекта notification
public data class Notification(
    val title: String?,
    val body: String?,
    val channelId: String?,
    val imageUrl: Uri?,
    val color: String?,
    val icon: String?,
    val clickAction: String?,
    val clickActionType: ClickActionType?
  )
  • title — заголовок уведомления.
  • body — тело уведомления.
  • channelId — возможность задать канал, в который отправится уведомление. Актуально для Android 8.0 и выше.
  • imageUrl — прямая ссылка на изображение для вставки в уведомление. Изображение должно быть не более 1 Мбайт.
  • color — цвет уведомления в HEX-формате, строкой. Например, #0077FF.
  • icon — значок уведомления из res/drawable в формате строки, которая совпадает с названием ресурса.
    Например, в res/drawable есть значок small_icon.xml, который доступен в коде через R.drawable.small_icon.
    Чтобы значок отображался в уведомлении, сервер должен указать в параметре icon значение small_icon    .
  • clickAction — поле с помощью которого будет сформировано действие при клике на уведомление.
  • clickActionType — тип поля clickAction.
Структура объекта ClickActionType
enum class ClickActionType {
    DEFAULT,
    DEEP_LINK
}

  • DEFAULT — тип поля clickAction при котором clickAction будет использоваться как intent action для открытия активити по клику на уведомление. Подробнее смотри документацию.

  • DEEP_LINK — тип поля clickAction при котором clickAction будет использоваться как deep link для открытия активити по клику на уведомление. Подробнее смотри документацию.

Создание канала для отправки уведомления​

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

  • Если в push-уведомлении есть поле channelId, RuStore SDK отправит уведомление в указанный канал. Ваше приложение должно создать этот канал заранее.

  • Если в push-уведомлении нет поля channelId, но ваше приложение указало параметр с каналом в AndroidManifest.xml, используется указанный канал. Ваше приложение должно создать этот канал заранее.

  • Если в push-уведомлении нет поля channelId, и канал по умолчанию не задан в AndroidManifest.xml, RuStore SDK создаст канал и отправит уведомление в него. В дальнейшем все уведомления без явного указания канала будут отправляться в этот канал.

Обработка ошибок​

  1. Публичные методы класса RuStorePushClient при возникновении ошибки возвращают Throwable.

  2. Метод onError класса RuStoreMessagingService может возвращать следующий набор ошибок:

  • UnauthorizedException — пользователь не авторизован в RuStore. Ошибка может не возникать, даже если пользователь не авторизован в RuStore. Это поведение управляется динамически в Push SDK. Если ваши пользователи не получают такую ошибку, то все равно имеет смысл ее обрабатывать;
  • HostAppNotInstalledException — RuStore отсутствует на устройстве пользователя;
  • HostAppBackgroundWorkPermissionNotGranted — у RuStore нет разрешения на работу в фоне. Ошибка не критична. Пуши продолжат приходить, но хуже, чем если бы разрешение на работу в фоне было выдано.

    • Вышеперечисленные ошибки являются наследниками класса RuStorePushClientException, который в свою очередь является наследником класса RuStoreException.

  1. Метод checkPushAvailability класса RuStorePushClient при успешном ответе в объекте FeatureAvailabilityResult.Unavailable возвращает ошибку HostAppNotInstalledException

Если вы хотите использовать UI-интерфейс для работы с ошибками, используйте метод resolveForPush.

Пример реализации resolveForPush
fun RuStoreException.resolveForPush(context: Context)

Тестирование интеграции SDK​

Ниже перечислены условия работы push-уведомлений.

Важно
  • Подпись и package name различных типов сборок вашего приложения (debug, release и т.д.) могут отличаться друг от друга. В таком случае вы должны создать в разделе Push-уведомления > Проекты из RuStore Консоль проект под каждый тип сборки..
  • Используется актуальная версия SDK.
  • Загружены данные о приложении в разделе Push-уведомления > Проекты из RuStore Консоль.

  • На устройстве пользователя установлено приложение-дистрибьютор (RuStore и т.д.)

    Для проверки того, что приложение-дистрибьютор установлено на устройстве пользователя, используйте метод RuStorePushClient.checkPushAvailability..
  • Если установлено приложение RuStore, то ему разрешен доступ к работе в фоновом режиме. Без этого разрешения push-уведомления будут приходить, но со значительной задержкой.
  • Отпечаток подписи приложения, установленного на девайсе, совпадает с отпечатком подписи приложения, которое добавлено в разделе Push-уведомления > Проекты из RuStore Консоль.

Чтобы начать тестирование SDK, включите тестовый режим.

Пример включения тестового режима
RuStorePushClient.init(
    application = this ,
    projectId = "your_push_project_id" ,
    testModeEnabled = true
)

SDK В тестовом режиме не взаимодействует с бэкэндом. В этом режиме формируется тестовый push-токен и работает доставка только тестовых push-уведомлений, отправляемых через SDK. Они отправляются следующим методом.

Пример отправки тестового push-уведомления
val testNotificationPayload = TestNotificationPayload(
    title = "Test notification title",
    body = "Test notification message",
    imgUrl = "some_image_http_url",
    data = mapOf("some_key" to "some_value")
)
 
RuStorePushClient.sendTestNotification(testNotificationPayload).addOnCompleteListener(object : OnCompleteListener<Unit> {
    override fun onFailure(throwable: Throwable) {
        // Process send test push error
    }
 
    override fun onSuccess(result: Unit) {
        // Process send test push success
    }
})

См. также​