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

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

Важно

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

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

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

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

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

Скачайте RuStore Push SDK.
Импортируйте SDK в проект: Assets > Import Package > Custom Package. Зависимости подключаются автоматически с помощью External Dependency Manager, который включён в SDK.
Установите Minimum API level не ниже 24.
Отключите минификацию приложения (ProGuard/R8) в настройках проекта: File > Build Settings > Player Settings > Publishing Settings > Minify. Она не поддерживается.

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

Объявите службу RuStoreUnityMessagingService.

<service
    android:name="ru.rustore.unitysdk.pushclient.RuStoreUnityMessagingService"
    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-уведомлений вы должны создать канал самостоятельно.

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

Для инициализации переопределите в проекте класс Application.

Необходимый исходный код уже содержится в файле Assets/RuStoreSDK/PushClient/Android/RuStoreUnityApplication.java.

RuStoreUnityApplication.java
package ru.rustore.unitysdk;
import android.app.Application;
import ru.rustore.unitysdk.pushclient.RuStoreUnityPushClient;
public class RuStoreUnityApplication extends Application {
    @Override public void onCreate() {
         super .onCreate();
         RuStoreUnityPushClient.init(
            application = this
         );
    }
}

application — экземпляр класса Application.

Этот класс укажите AndroidManifest.xml проекта.

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

Параметры, с которыми инициализируется библиотека, настраиваются в редакторе Unity. Выберите в меню редактора пункт Window > RuStoreSDK > Settings > Push Client.

VKPNS Project Id — идентификатор проекта из RuStore Консоль. Чтобы получить его, на странице приложения перейдите в раздел Push-уведомления > Проекты и скопируйте значение в поле ID проекта.
Allow Native Error Handling — разрешить обработку ошибок в нативном SDK.

Перед вызовом методов библиотеки из кода C# вызовите её инициализацию.

var сonfig =  new RuStorePushClientConfig() {
    allowNativeErrorHandling = true ,
    messagingServiceListener = pushServiceListener,
    logListener = pushLogListener
};
RuStorePushClient.Instance.Init(сonfig);

allowNativeErrorHandling — разрешить обработку ошибок в нативном SDK, см. раздел Обработка ошибок.
messagingServiceListener — объект класса, который реализует интерфейс IMessagingServiceListener.
logListener — объект класса, который реализует интерфейс ILogListener.

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

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

RuStorePushClient.Instance.CheckPushAvailability(
    onFailure: (error) => {
        // Process error
    },
    onSuccess: (response) => {
        if (!response.isAvailable) {
            // Process push unavailable
        }
    }
);

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

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

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

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

После инициализации библиотеки вы можете использовать метод RuStorePushClient.getToken(), чтобы получить текущий push-токен пользователя.

Вызов метода GetToken
RuStorePushClient.Instance.GetToken(
    onFailure: (error) => {
        // Process error 
    },
    onSuccess: (token) => {
        // Process success 
    }
);

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

После инициализации библиотеки вы можете использовать метод RuStorePushClient.deleteToken(), чтобы удалить текущий push-токен пользователя.

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

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

После инициализации библиотеки вы можете использовать метод SubscribeToTopic(your_topic_name) для подписки на топик.

Вызов метода SubscribeToTopic
RuStorePushClient.Instance.SubscribeToTopic(
    topicName: "your_topic_name",
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    }
);

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

После инициализации библиотеки вы можете использовать метод UnsubscribeFromTopic(your_topic_name) для отписки от топика.

Вызов метода UnsubscribeFromTopic
RuStorePushClient.Instance.UnsubscribeFromTopic(
    topicName: "your_topic_name",
    onFailure: (error) => {
        // Process error
    },
    onSuccess: () => {
        // Process success
    }
);

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

Для получения и обработки данных push-уведомлений на стороне Unity реализуйте интерфейс IMessagingServiceListener. Объект реализующий интерфейс должен быть передан в методе инициализации плагина.

IMessagingServiceListener.cs
using System.Collections.Generic;

namespace RuStore.PushClient {

    public interface IMessagingServiceListener {

        public void OnNewToken(string token);
        public void OnMessageReceived(RemoteMessage message);
        public void OnDeletedMessages();
        public void OnError(List<RuStoreError> errors);
    }
}

Название метода	Описание
`onNewToken`	Метод вызывается при получении нового push-токена. После вызова этого метода ваше приложение становится ответственно за передачу нового push-токена на свой сервер. Метод возвращает значение нового токена.
`onMessageReceived`	Метод вызывается при получении нового push-уведомления. Если в объекте `notification` есть данные, RuStore SDK самостоятельно отображает уведомление. Если вы не хотите этого, используйте объект `data`, а `notification` оставьте пустым. Метод вызывается в любом случае. Получить `payload` push-уведомления `Dictionary<string, string>` можно из поля `message.data`.
`DeletedMessagesResponse`	Метод вызывается, если один или несколько push-уведомлений не доставлены на устройство. Например, если время жизни уведомления истекло до момента доставки. При вызове этого метода рекомендуется синхронизироваться со своим сервером, чтобы не пропустить данные.
`ErrorResponse`	Метод вызывается, если в момент инициализации возникает ошибка. Он возвращает массив объектов с ошибками. Возможные ошибки: `UnauthorizedException` — пользователь не авторизован в RuStore. Ошибка может не возникать, даже если пользователь не авторизован в RuStore. Это поведение управляется динамически в Push SDK. Если ваши пользователи не получают такую ошибку, то все равно имеет смысл ее обрабатывать; `HostAppNotInstalledException` — RuStore отсутствует на устройстве пользователя; `HostAppBackgroundWorkPermissionNotGranted` — у RuStore нет разрешения на работу в фоне. Ошибка не критична. Пуши продолжат приходить, но хуже, чем если бы разрешение на работу в фоне было выдано. Все возможные ошибки описаны в разделе Обработка ошибок.

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

Структура полного уведомления
public class RemoteMessage {
    public string collapseKey;
    public Dictionary< string ,  string > data;
    public string messageId;
    public Notification notification;
    public int priority;
    public sbyte [] rawData;
    public int ttl;
}

messageId — уникальный ID сообщения. Является идентификатором каждого сообщения.
priority — возвращает значение приоритетности (на данный момент не учитывается). Сейчас заложены следующие варианты:
- 0 — UNKNOWN;
- 1 — HIGH;
- 2 — NORMAL.
ttl — время жизни push-уведомления типа Int в секундах.
from — поле, по которому можно понять, откуда пришло уведомление:
- для уведомлений, отправленных в топик, в поле отображается имя топика;
- в других случаях — часть вашего сервисного токена.
.
collapseKey — идентификатор группы уведомлений (на данный момент не учитывается).
data — словарь, в который можно передать дополнительные данные для уведомления.
rawData — словарь data в виде массива байтов.
notification — объект уведомления.

Структура объекта Notification
public class Notification {
    public string title;
    public string body;
    public string channelId;
    public string imageUrl;
    public string color;
    public string icon;
    public string clickAction;
}

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 — intent action, с помощью которого будет открыта активити при клике на уведомление.

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

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

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

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

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

Класс RuStoreError
namespace RuStore {

    public class RuStoreError {

        public string name;
        public string description;
    }
}

name — название ошибки. Содержит имя simpleName класса ошибки.
description — сообщение ошибки.

Если при инициализации SDK вы передали параметр allowNativeErrorHandling == true, в случае ошибки:

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

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

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

Запрет нативной обработки ошибок
RuStorePushClient.Instance.AllowNativeErrorHandling = false;

warning

Значение RuStorePushClient.Instance.AllowNativeErrorHandling должно задаваться после инициализации плагина.

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

RuStoreNotInstalledException — на устройстве пользователя не установлен RuStore.
RuStoreOutdatedException — версия RuStore, установленная на устройстве пользователя, не поддерживает данный SDK.
RuStoreUserUnauthorizedException — пользователь не авторизован в RuStore.
RuStoreFeatureUnavailableException — RuStore не имеет разрешения на работу в фоне.
RuStoreException — базовая ошибка RuStore, от которой наследуются остальные ошибки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также​