SDK push-уведомлений для Unity (версия 0.6.1)
Условия работы push-уведомлений:
- Используется актуальная версия SDK.
- Приложение загружено в Консоль RuStore.
- Приложение прошло модерацию (публиковать приложение необязательно).
- На устройстве пользователя установлена актуальная версия RuStore.
- Приложение RuStore поддерживает функциональность push-уведомлений.
- Приложению RuStore разрешен доступ к работе в фоновом режиме. Без этого разрешения 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>
Если нужно изм енить иконку или цвет стандартной нотификации, добавьте:
<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" />
Если нужно переопределить канал уведомлений, добавьте:
<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
:
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
проекта:
<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-уведомления
Для проверки того, что приложение RuStore установлено на устройстве пользователя, используйте методRuStorePushClient.checkPushAvailability
.
RuStorePushClient.Instance.CheckPushAvailability(
onFailure: (error) => {
// Process error
},
onSuccess: (response) => {
if (!response.isAvailable) {
// Process push unavailable
}
});
Методы для работы с push-токеном
Получение push-токена пользователя
Если у пользователя нет push-токена, метод создаст и вернёт новый push-токен.
RuStorePushClient.getToken()
, чтобы получить текущий push-токен пользователя.
RuStorePushClient.Instance.GetToken(
onFailure: (error) => {
// Process error
},
onSuccess: (token) => {
// Process success
});
Удаление push-токена пользователя
После инициализации библиотеки вы можете использовать методRuStorePushClient.deleteToken()
, чтобы удалить текущий push-токен пользователя.
RuStorePushClient.Instance.DeleteToken(
onFailure: (error) => {
// Process error
},
onSuccess: () => {
// Process success
});
Методы для работы с push-топиком
Подписка на push-уведомления по топику
После инициализации библиотеки вы можете использовать метод SubscribeToTopic(your_topic_name)
для подписки на топик.
RuStorePushClient.Instance.SubscribeToTopic(
topicName: "your_topic_name" ,
onFailure: (error) => {
// Process error
},
onSuccess: () => {
// Process success
});
Отписка от push-уведомлений по топику
Посл е инициализации библиотеки вы можете использовать метод UnsubscribeFromTopic(your_topic_name)
для отписки от топика.
RuStorePushClient.Instance.UnsubscribeFromTopic(
topicName: "your_topic_name" ,
onFailure: (error) => {
// Process error
},
onSuccess: () => {
// Process success
});
Получение данных от RuStore SDK
Для получения и обработки данных push-уведомлений на стороне Unity реализуйте интерфейс IMessagingServiceListener. Объект реализующий интерфейс должен быть передан в методе инициализации плагина.
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);
}
}
Название метода | Описание |
---|---|
| Метод вызывается при получении нового push-токена. После вызова этого метода ваше приложение становится ответственно за передачу нового push-токена на свой сервер. Метод возвращает значение нового ток ена. |
| Метод вызывается при получении нового push-уведомления.
< p/>
Если в объекте |
| Метод вызывается, если один или несколько push-уведомлений не доставлены на устройство. Например, если время жизни уведомления истекло до момента доставки. < p/> При вызове этого метода рекомендуется синхронизироваться со своим сервером, чтобы не пропустить данные. |
| Метод вызывается, если в момент инициализации возникает ошибка. Он возвращает массив объектов с ошибками. < p/> Возможные ошибки:
|
Структура уведомления
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
— объект уведомления.
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
, не рекомендуется отображать ошибку пользователю. Отображение ошибки может негативно повлиять на пользовательский опыт.
namespace RuStore {
public class RuStoreError {
public string name;
public string description;
}
}
name
— название ошибки. Содержит имяsimpleName
класса ошибки.description
— сообщение ошибки.
Если при инициализации SDK вы передали параметр allowNativeErrorHandling == true
, в случае ошибки:
-
Вызовется соответствующий обработчик
onFailure
. -
Ошибка передастся в метод
resolveForPush
нативного SDK. Это нужно, чтобы показать пользователю диалог с ошибкой.
fun RuStoreException.resolveForPush(context: Context)
Чтобы отключить передачу ошибки в нативный SDK, установите значение false
для свойства AllowNativeErrorHandling
.
RuStorePushClient.Instance.AllowNativeErrorHandling = false;
Возможные ошибки
-
RuStoreNotInstalledException
— на устройстве пользователя не установлен RuStore. -
RuStoreOutdatedException
— версия RuStore, установленная на устройстве пользователя, не поддерживает данный SDK. -
RuStoreUserUnauthorizedException
— пользователь не авторизован в RuStore. -
RuStoreFeatureUnavailableException
— RuStore не имеет разрешения на работу в фоне. -
RuStoreException
— базовая ошибка RuStore, от которой наследуются остальные ошибки.