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

SDK push-уведомлений для ReactNative (версия 2.1.1)

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

  • Используется актуальная версия SDK.
  • Приложение загружено в Консоль RuStore.
  • Приложение прошло модерацию (публиковать приложение необязательно).
  • На устройстве пользователя установлена актуальная версия RuStore.
  • Приложение RuStore поддерживает функциональность push-уведомлений.
  • Приложению RuStore разрешен доступ к работе в фоновом режиме. Без этого разрешения push-уведомления будут приходить, но со значительной задержкой.
  • Отпечаток подписи приложения, установленного на девайсе, совпадает с отпечатком подписи приложения, которое загружено в Консоль RuStore.

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

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

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

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

// HTTPS
npm install git+https://git@gitflic.ru/project/rustore/react-native-rustore-push-sdk.git

// SSH
npm install git+ssh://git@gitflic.ru/project/rustore/react-native-rustore-push-sdk.git

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

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

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-уведомлений:

const requestNotificationPermission = async () => {
  try {
    const granted = await PermissionsAndroid.request(
      PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS,
      {
        title: 'Разрешение на показ уведомлений',
        message: 'Приложению необходимо предоставить разрешение на показ уведомлений',
        buttonNeutral: 'Спросить меня позже',
        buttonNegative: 'Отменить',
        buttonPositive: 'OK',
      },
    );
    if (granted === PermissionsAndroid.RESULTS.GRANTED) {
      console.log('Вы можете показывать уведомления');
    } else {
      console.log('Разрешение на показ уведомлений отклонено');
    }
  } catch (err) {
    console.warn(err);
  }
};

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

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

img

Инициализация SDK push-уведомлений​

Добавьте в 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.ReactRuStorePushClientParams" />
  • projectId — идентификатор проекта из RuStore Консоль. Чтобы получить его, на странице приложения перейдите в раздел «Push-уведомления» — «Проекты» и скопируйте значение в поле «ID проекта».
  • (опционально) com.example.ReactRuStorePushClientParams — полное имя класса своей реализации ReactRuStorePushClientParams. Параметр нужен для указания дополнительных параметров инициализации push-клиента.

Класс – наследник AbstractRuStorePushClientParams, он по умолчанию реализован на стороне SDK и имеет вид:

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

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

  override fun getTestModeEnabled(): Boolean = false
}

Вы можете переопределить его в своем приложении. Для этого добавьте в Android модуль зависимости.

build.gradle
repositories {
    maven {
        url = uri("https://artifactory-external.vkpartner.ru/artifactory/maven")
    }
}
build.gradle
dependencies {
    implementation("ru.rustore.sdk:pushclient:2.1.1")
}

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

ReactRuStorePushClientParams.kt
class ReactRuStorePushClientParams(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) }
}

Далее указать в AndroidManifest.xml

AndroidManifest.xml
<meta-data
    android:name="ru.rustore.sdk.pushclient.params_class"
    android:value="com.example.ReactRuStorePushClientParams" />
предупреждение

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

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

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

  • Используется актуальная версия SDK.
  • Приложение загружено в Консоль RuStore.
  • Приложение прошло модерацию (публиковать приложение необязательно).
  • На устройстве пользователя установлена актуальная версия RuStore.
  • Приложение RuStore поддерживает функциональность push-уведомлений.
  • Приложению RuStore разрешен доступ к работе в фоновом режиме. Без этого разрешения push-уведомления будут приходить, но со значительной задержкой.
  • Отпечаток подписи приложения, установленного на девайсе, совпадает с отпечатком подписи приложения, которое загружено в Консоль RuStore.
Для проверки того, что приложение RuStore установлено на устройстве пользователя, используйте метод RustorePushClient.checkPushAvailability. 
try {
  const isAvailable = await RustorePushClient.checkPushAvailability();
  console.log(`available success: ${isAvailable}`);
}  catch (err) {
  console.log(available error ${err});
}

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

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

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

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

После инициализации библиотеки вы можете использовать метод RuStorePushClient.getToken(), чтобы получить текущий push-токен пользователя. 
try {
  const pushToken = await RustorePushClient.getToken();
  console.log(`push token: ${pushToken}`);
} catch (err: any) {
  console.log(JSON.stringify(err));
}

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

После инициализации библиотеки вы можете использовать метод RuStorePushClient.deleteToken(), чтобы удалить текущий push-токен пользователя. 
try {
  const pushToken = await RustorePushClient.deleteToken();
  console.log("delete success");
} catch (err: any) {
  console.log(JSON.stringify(err));
}

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

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

Вы можете использовать метод RustorePushClient.subscribeToTopic(your_topic_name) для подписки на топик.

Пример реализации RustorePushClient.subscribeToTopic(your_topic_name)
try {
  RustorePushClient.subscribeToTopic("your_topic_name");
} catch (err) {
  console.log(JSON.stringify(err));
}

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

Вы можете использовать метод RustorePushClient.unsubscribeFromTopic(your_topic_name) для отписки от топика.

Пример реализации RustorePushClient.unsubscribeFromTopic(your_topic_name)
try {
  RustorePushClient.unsubscribeFromTopic("your_topic_name");
} catch (err) {
  console.log(JSON.stringify(err));
}

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

Создание эмиттера​

Для создания эмиттера вызовите данный метод, который создаст генератор событий на стороне SDK.

RustorePushClient.createPushEmitter();

Структура эмиттера

interface RuStorePushEmitter {

   fun onNewToken(token: String)

   fun onMessageReceived(message: RemoteMessage)

   fun onDeletedMessages()

   fun onError(errors: String)
}

Если эмиттер вам больше не нужен, вы можете вызвать метод удаления.

RustorePushClient.removePushEmitter();

Получение информации о push-уведомлениях​

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

Чтобы подписаться на события, используйте метод eventEmitter.addListener.

const onNewTokenListener = useRef<EmitterSubscription>();
const onMessageReceivedListener = useRef<EmitterSubscription>();
const onDeletedMessageListener = useRef<EmitterSubscription>();
const onErrorListener = useRef<EmitterSubscription>();


onNewTokenListener.current = eventEmitter.addListener(PushEvents.ON_NEW_TOKEN, (token: string) => {
     // эвент ON_NEW_TOKEN
     console.log("token", token)
    });

onMessageReceivedListener.current = eventEmitter.addListener(PushEvents.ON_MESSAGE_RECEIVED, (message: RemoteMessage) => {
     // эвент ON_MESSAGE_RECEIVED
     console.log("messageId", message.messageId)
    });

onDeletedMessageListener.current = eventEmitter.addListener(PushEvents.ON_DELETED_MESSAGES, () => {
     // эвент ON_DELETED_MESSAGES
    });

onErrorListener.current = eventEmitter.addListener(PushEvents.ON_ERROR, (errors: string) => {
     // эвент ON_ERROR
     console.log("errors", errors)
    });
Структура PushEvents
enum PushEvents {
    ON_NEW_TOKEN = 'ON_NEW_TOKEN',
    ON_MESSAGE_RECEIVED = 'ON_MESSAGE_RECEIVED',
    ON_DELETED_MESSAGES = 'ON_DELETED_MESSAGES',
    ON_ERROR = 'ON_ERROR'
}
Название событияОписание

ON_NEW_TOKEN

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

ON_MESSAGE_RECEIVED

Событие отрабатывает при получении нового push-уведомления. Получить payload push-уведомления =Map<string, string> можно из поля message.data.

ON_DELETED_MESSAGES

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

ON_ERROR

Событие отрабатывает, если в момент инициализации возникает ошибка. Возвращает строку с ошибками. < p/> Возможные ошибки:

  • UnauthorizedException — пользователь не авторизован в RuStore.
  • HostAppNotInstalledException — RuStore отсутствует на устройстве пользователя.
  • HostAppBackgroundWorkPermissionNotGranted — у RuStore нет разрешения на работу в фоне.
Все возможные ошибки описаны в разделе Обработка ошибок.

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

Структура полного уведомления
interface RemoteMessage {
    messageId?: string;
    priority?: number;
    ttl?: number;
    from: string;
    collapseKey?: string;
    rawData?:ArrayBuffer,
    notification: Notification;
}

  • messageId — уникальный ID сообщения. Является идентификатором каждого сообщения.

  • priority — возвращает значение приоритетности (на данный момент не учитывается). Сейчас заложены следующие варианты:
    • 0 — UNKNOWN.
    • 1 — HIGH.
    • 2 — NORMAL.

  • ttl — время жизни push-уведомления типа Int в секундах.

  • from — поле, по которому можно понять, откуда пришло уведомление:
    • Для уведомлений, отправленных в топик, в поле отображается имя топика.
    • В других случаях — часть вашего сервисного токена.

  • collapseKey — идентификатор группы уведомлений (на данный момент не учитывается).

  • data — словарь, в который можно передать дополнительные данные для уведомления.

  • rawData — словарь data в виде массива байтов.

  • notification — объект уведомления.

Структура объекта notification
interface Notification {
    title?: string;
    body: string;
    channelId?: string;
    imageUrl?: string;
    color?: string;
    icon?: string;
    clickAction?: string;
    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 ClickActionType {
    DEFAULT = "DEFAULT",
    DEEP_LINK = "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 создаст канал и отправит уведомление в него. В дальнейшем все уведомления без явного указания канала будут отправляться в этот канал.

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

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

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

  • RuStoreUserUnauthorizedException — пользователь не авторизован в RuStore.

  • RuStoreFeatureUnavailableException — RuStore не имеет разрешения на работу в фоне.

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

По умолчанию в плагине включена нативная обработка ошибок, в случае возникновения ошибки выполняются эти действия:

  • Вызовется соответствующий обработчик ошибки.

  • Ошибка передаётся в метод resolveForPush нативного SDK. Это нужно, чтобы показать пользователю диалог с ошибкой.

Метод resolveForPush
fun RuStoreException.resolveForPush(context: Context)

Чтобы отключить передачу ошибки в нативный SDK, вызовите функцию offNativeErrorHandling.

Запрет нативной обработки ошибок
RustorePushClient.offNativeErrorHandling();

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

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

  • Используется актуальная версия SDK.
  • Приложение загружено в Консоль RuStore.
  • Приложение прошло модерацию (публиковать приложение необязательно).
  • На устройстве пользователя установлена актуальная версия RuStore.
  • Приложение RuStore поддерживает функциональность push-уведомлений.
  • Приложению RuStore разрешен доступ к работе в фоновом режиме. Без этого разрешения push-уведомления будут приходить, но со значительной задержкой.
  • Отпечаток подписи приложения, установленного на девайсе, совпадает с отпечатком подписи приложения, которое загружено в Консоль RuStore.

Чтобы начать тестирование SDK, необходимо переопределить AbstractRuStorePushClientParams и в функции getTestModeEnabled вернуть true.

Пример включения тестового режима
class RuStorePushClientParams(context: Context) : AbstractRuStorePushClientParams(context) {

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

  override fun getTestModeEnabled(): Boolean = true
}

Далее указать в AndroidManifest.xml

AndroidManifest.xml
<meta-data
    android:name="ru.rustore.sdk.pushclient.params_class"
    android:value="com.example.RuStorePushClientParams" />

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

Пример отправки тестового push-уведомления
const testNotification = new TestNotificationPayload(
  'Тестовое уведомление',
  'Здесь будет тело уведомления',
  'https://static.rustore.ru/image/rustore_deeplink_600x315.jpg',
  { key: 'key', value: 'value'}
)

try {
  await RustorePushClient.sendTestNotification(testNotification)
} catch (err: any) {
  console.log(JSON.stringify(err));
}

См. также​