Расширенная настройка уведомлений, дополнительные возможности🔗

MRGS позволяет Вам работать со всеми функциями и новшествами в уведомлениях, а именно:

1. Запрашивать разрешение на отправку уведомлений в нужное вам время (для iOS)
2. Получить настройки уведомлений пользователя
3. Работать с доставленными и запланированными уведомлениями
4. Добавлять в уведомления кнопки и кастомизировать их вид.
5. Настраивать группировку уведомлений, включая вид summary и его аргументы.
6. Добавлять вложения к уведомлениям. (IOS 10+)
7. Добавлять собственные звуки к уведомлениям.
8. Удобно включать и выключать уведомления на клиенте одним методом, а мы позаботимся об отмене уведомлений или инвалидации токена (полезно для проектов, где в настройках есть переключатель доступности уведомлений)
9. Выставлять номер на иконке приложения на iOS.
10. Работать с Trial notifications на iOS.

Поздний запрос разрешения на уведомления🔗

В iOS/Android(13+), при первом запросе разрешения на отправку уведомлений, пользователю будет показан попап. При стандартной настройке MRGSNotificationCenter данный попап будет показан на самом старте приложения, что может негативно сказаться на количестве разрешений, т.к. это является плохой практикой, сначала лучше объяснить пользователю, зачем нужны уведомления.

Если Вам необходимо первый раз запросить разрешение у пользователя позже (например, по нажатию на кнопку, или после определенного экрана), то Вы можете запустить наш MRGSNotificationCenter в нужный момент. После запуска будет запрошено разрешение на отправку уведомлений, получен токен. Для этого на шаге настройки параметров необходимо выставить флаги отложенного старта в true:

using MRGS;

public class MasterController : MonoBehaviour
{
    void Awake()
    {
        var serviceParams = new MRGServiceParams(MRGS_APP_ID, CLIENT_SECRET);

        serviceParams.IOSExtraOptions.DefferedMRGSNotificationCenterStart = true;
        serviceParams.AndroidExtraOptions.DeferredPushStart = true;

        // Further setup and initialization of MRGS
        // ...
    }
}

Затем, в момент, когда вы готовы показать пользователю запрос, необходимо вызвать метод:

MRGSNotificationCenter.Instance.EnableMRGSNotifications();

Или другие вариации данного метода (подробнее про включение и отключение уведомлений читайте в соответствующем разделе).

После вызова метода будет произведен старт нашего MRGSNotificationCenter, показан попап. В дальнейшем данный метод вызывать каждый раз уже не обязательно, мы сами автоматически будем запускать MRGSNotificationCenter на старте приложения, если попап был показан хотя бы раз.

MRGSNotificationCenter.Instance.RequestNotificationsPermissions();

Работа с Trial (Provisional) Notifications на iOS🔗

Когда вы явно запрашиваете разрешение на отправку уведомлений, пользователи должны сразу решить, разрешить или запретить их, прежде чем они увидят уведомления от приложения. У пользователей может не оказаться достаточно информации для принятия решения, и они могут отклонить авторизацию. Вы можете использовать Provisional авторизацию - тогда пользователи смогут сначала оценить уведомления, а потом принять решение, разрешать их или нет.

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

Если пользователь нажимает кнопку «Оставить», система предлагает ему выбрать между обычными или тихими уведомлениями. Если пользователь выбирает обычные уведомления, ваше приложение получает все разрешения. Если пользователь выбирает получение беззвучных уведомлений, система разрешает вашему приложению отправлять уведомления, но не разрешает вашему приложению показывать предупреждения, воспроизводить звуки или отмечать номер на иконке приложения - Ваше уведомление отображается только в истории центра уведомлений. Если пользователь нажимает кнопку «Выключить», система подтверждает выбор, прежде чем отказывать вашему приложению в авторизации для отправки уведомлений. Подробнее читайте в официальной документации

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

// MRGService settings
MRGServiceParams serviceParams = new MRGServiceParams(MRGS_APP_ID, CLIENT_SECRET);
// ...

MRGSNotificationCenter.AddExtraPermissionsForNotificationsAuthorizationRequest(MRGSNotificationAuthorizationOptionType.Provisional);

// Further setup and initialization of MRGS
// ...

Так как данный функционал работает только на iOS 12+, на версиях ниже он будет игнорироваться MRGS. Для того, чтобы проверить, доступен ли функционал Trial Notifications, вы можете воспользоваться методом:

MRGSNotificationCenter.IsProvisionalNotificationsRequestAvailable();

Включение и выключение уведомлений🔗

MRGS позволит вам с легкостью включить или выключить конкретные типы уведомлений на устройстве пользователя. Данный функционал полезен для проектов, где в настройках есть переключатель доступности уведомлений. Так вы можете управлять доступностью локальных и push уведомлений:

public enum MRGSNotificationsType
{
    All = 1,
    Local = 2,
    Remote = 3,
}

Для отключения конкретного типа уведомлений, необходимо вызвать метод:

// Pass the notification type to be disabled to the method
MRGSNotificationCenter.Instance.DisableMRGSNotifications(MRGSNotificationsType.Local);

// Or a method that disables all types of notifications
// (equivalent to the call above, i.e. with the MRGSNotificationsType.All parameter):
MRGSNotificationCenter.Instance.DisableMRGSNotifications();

После отключения локальных уведомлений, мы очистим текущую очередь запланированных и доставленных уведомлений, и будем игнорировать добавление новых локальных уведомлений (с выводом в лог ошибки), пока их снова не включат.

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

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

// Pass the notification type to be enabled to the method
MRGSNotificationCenter.Instance.EnableMRGSNotifications(MRGSNotificationsType.Local);

// Or a method that enables all types of notifications
// (equivalent to the call above, i.e. with the MRGSNotificationsType.All parameter):
MRGSNotificationCenter.Instance.EnableMRGSNotifications();

Для проверки, включен ли на текущий момент конкретный тип уведомлений (все, локальные, пуши), предусмотрен метод:

// Pass the notification type to be checked into the method
bool res = MRGSNotificationCenter.Instance.IsMRGSNotificationsEnabled(MRGSNotificationsType.All);

Таким образом, можно легко включать и выключать определенный тип уведомлений, или же сразу оба типа. Небольшой пример приведен ниже:

public void Toggle(bool toggleStatus)
{
    if(toggleStatus){
        // Пользователь включил все уведомления
        MRGSNotificationCenter.Instance.EnableMRGSNotifications();
    }else{
        // Пользователь выключил все уведомления
        MRGSNotificationCenter.Instance.DisableMRGSNotifications();
    }
}

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

Если Вам необходимо узнать общую доступность уведомлений, то можете воспользоваться методом, который вернет Вам TRUE, если уведомления доступны:

MRGSNotificationCenter.Instance.IsNotificationsEnabled((bool enabled) =>  {
    if (enabled) {
        // Everything is fine, you can send notifications
    }else{
        // The user has disabled notifications, you can ask him to turn them back on
    }
});

Для получения настроек, воспользуйтесь методом:

MRGSNotificationCenter.Instance.GetUserSettings((MRGSNotificationSettings settings) => {
    Debug.Log("MRGSNotificationSettings - " + settings);
});

Возвращаемый объект класса MRGSNotificationSettings содержит в себе настройки уведомлений, включающий в себя доступность, включены ли баннеры, звуки, цифры на иконке приложения и другие параметры (для IOS 10+), полный список полей можно найти в описании класса.

Управление доставленными и запланированными уведомлениями🔗

С помощью MRGS Вы можете:

Для запланированных уведомлений (Еще не доставленных, триггер еще не сработал):

1. Найти уведомление с необходимым идентификатором в запланированных
2. Получить список всех запланированных уведомлений
3. Отменить запланированные уведомления с необходимыми идентификаторами.
4. Отменить все запланированные уведомления

Для этого воспользуйтесь методами класса MRGSNotificationCenter:

void FindPendingNotification(string identifier,Action<MRGSNotification> completion)
void GetPendingNotifications(Action<List<MRGSNotification>> completion)
void RemovePendingNotifications(List<string> identifiersArray)
void RemoveAllPendingNotifications()

Пример:

MRGSNotificationCenter.Instance.GetPendingNotifications((List<MRGSNotification> pendingNotifications) =>
{
    foreach (MRGSNotification pendingNotification in pendingNotifications)
    {
        Debug.Log("Pending notification - " + pendingNotification);
    }
});

Подробное описание методов и параметров читайте в описании класса MRGSNotificationCenter.

Для доставленных уведомлений (будет работать на IOS 10+):

1. Найти уведомление с необходимым идентификатором в доставленных.
2. Получить список всех доставленных уведомлений
3. Отменить доставленные уведомления с необходимыми идентификаторами.
4. Отменить все доставленные уведомления

Для этого воспользуйтесь методами:

void FindDeliveredNotification(string identifier,Action<MRGSNotification> completion)
void GetDeliveredNotifications(Action<List<MRGSNotification>> completion)
void RemoveDeliveredNotifications(List<string> identifiersArray)
void RemoveAllDeliveredNotifications()

Добавление кнопок и кастомизация🔗

iOS🔗

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

Регистрация происходит не для отдельно кнопок, в для категорий (типов) уведомлений, которые, в свою очередь содержат кнопки. При работе с MRGS для регистрации используются классы MRGSNotificationAction и MRGSNotificationCategory

Для создания категории воспользуйтесь методом:

// Create buttons, they have an id that will return when clicked, and a display text
var playAction = new MRGSNotificationAction("StartPlayingButton", "Just play!");
var getRewardAction = new MRGSNotificationAction(identifier: "GetRewardButton", title: "Get reward!");
var actionsList = new List<MRGSNotificationAction> { playAction, getRewardAction };

// Create a notification type that contains the two buttons we created earlier and has a unique ID
var categoryOnReturn = new MRGSNotificationCategory("categoryOnReturnNotifications", actionsList);

Затем Вам необходимо зарегистрировать созданные категории:

// Registering an array of created categories
var categoriesList = new List<MRGSNotificationCategory> { categoryOnReturn };
MRGSNotificationCenter.Instance.RegisterCategories(categoriesList);

Чтобы добавить уведомление определенной категории, при настройке добавьте строку:

notification.IosExtraOptions.CategoryIdentifier = "categoryOnReturnNotifications"; //Идентификатор категории

В случае, если пользователь нажал на кнопку в уведомлении, то в пришедшем Вам callback'e в объекте MRGSNotification поле notification.IosExtraOptions.DeliveryChosenActionIdentifier будет содержать идентификатор (переданный при создании MRGSNotificationAction) нажатой кнопки.

project.SetBuildProperty(notificationExtensionTarget, "ARCHS", "$(ARCHS_STANDARD)");

Android🔗

Для использования собственной верстки уведомлений на Android необходимо выполнить следующие действия:

• Создайте layout (разметку) в ресурсах Android. Директория (res/layout)
• В ресурсы (res/drawable) необходимо положить изображения, которые вы хотите использовать внутри этой разметки
• Текст можно задавать напрямую, либо так же загружать из ресурсов Android

Пример:

//animated_notification - это имя файла разметки (res/layout/animated_notification.xml)
notification.AndroidExtraOptions.CustomView = "animated_notification";
//notification_icon - это id ImageView внутри разметки (<ImageView android:id="@+id/notification_icon">)
//app_icon - иконка в ресурсах (res/drawable/app_icon.png)
notification.AndroidExtraOptions.SetCustomViewImage("notification_icon", "app_icon");
//notification_text1 - это id TextView внутри разметки (<TextView android:id="@+id/notification_text1">)
//app_name - строковый ресурс (res/values/strings.xml <string name="app_name">Unity</string>)
notification.AndroidExtraOptions.SetCustomViewTextFromRes("notification_text1", "app_name");
//notification_text2 - это id TextView внутри разметки (<TextView android:id="@+id/notification_text2">)
//Hello, World - текст не из ресурсов для отображения в уведомлении
notification.AndroidExtraOptions.SetCustomViewText("notification_text2", "Hello, World!");

notification.AndroidExtraOptions.Icon = "imageName" // Имя файла БЕЗ расширения в директории с ресурсами (res/drawable)
notification.AndroidExtraOptions.LargeIcon = "imageName" // Имя файла БЕЗ расширения в директории с ресурсами (res/drawable)

Настройка группировки🔗

iOS🔗

В IOS 12 все уведомления сгруппированы, если вы хотите управлять группировкой, то есть разбить группу уведомлений от Вашего приложения, допустим, на две или три, необходимо при создании уведомления добавить строку:

notification.IosExtraOptions.ThreadIdentifier =@"THREAD_1"; //Выбор потока группировки

Идентификатор потока Вы выбираете сами. Например, чтобы было две группы уведомлений от приложения типа "мессенджер", то для каждого диалога укажите собственный ThreadIdentifier.

Если Вы хотите, чтобы при группировке одно уведомление считалось по "весу" за три, а также если Вы хотите уточнить название группы, воспользуйтесь полями:

notification.IosExtraOptions.SummaryArgumentCount = 3;
notification.IosExtraOptions.SummaryArgument = @"MRGSSS";

Если Вы хотите выбирать формат поясняющей строки при группировке, то при создании категории используйте метод:

// FORMAT is the format string for grouping
// PHOLDER is text if the user has notifications hidden on the lock screen enabled
MRGSNotificationCategory.Create(identifier: ..., actionsArray: ..., summary: "FORMAT", placeholder: "PHOLDER");

// For example:
var category = new MRGSNotificationCategory("some_id", <list>)
{
    CategorySummaryFormat = "to go",
    HiddenPreviewsBodyPlaceholder = "Some interesting info for you!"
};

Android🔗

По умолчанию Android не группирует уведомления. Если вы хотите объединить несколько уведомлений в одно, им необходимо задать Id группы

Воспользуйтесь полями:

notification.AndroidExtraOptions.GroupId = 1
notification.AndroidExtraOptions.GroupMessage = "Hello"
notification.AndroidExtraOptions.GroupTitle = "Some Title"

Добавление вложений к уведомлениям. (только на iOS)🔗

Для добавления вложения(картинки, как на первом скриншоте для iOS), воспользуйтесь полем:

var attachmentsList = new List<string> { "/path/to/image1", "/path/to/image2" };  //Массив с путями к вложениям
notification.IosExtraOptions.Attachments = attachmentsList;

Пути к вложениям должны быть заданы либо полностью до ресурса в ios-формате, либо можно указать относительный путь от mainBundle, то есть если картинка лежит в корне приложения, то достаточно будет написать:

notification.IosExtraOptions.Attachments = new List<string> {"imageName.png"};

То есть, задать путь до вложения можно двумя способами:

notification.IosExtraOptions.Attachments = new List<string>(){
    "forest.jpg", // Get from application root bundle
    "file://" + System.IO.Directory.GetParent(Application.dataPath) + "/" + "forest.jpg" // Manually set full path to file (in application root bundle in this example)
};

Настройка номера на иконке. (только на iOS)🔗

Воспользуйтесь полем:

notification.IosExtraOptions.Badge = 3; //При доставке номер на иконке станет равен 3

Добавление собственных звуков к уведомлениям.🔗

Обратите внимание, что имя файла для iOS и Android отличается.

Для добавления собственного звука, проигрываемого при приходе уведомления, воспользуйтесь полем:

#if UNITY_IOS
notification.Sound = "CustomNotificationSound.caf"; //Где "***.caf" - названия файла звука, лежащего в ресурсах приложения.
#elif UNITY_ANDROID
notification.Sound = "custom_notification_sound"; //Для Android имя файла должно быть без расширения
#endif

На Android 8.0 и выше нет возможности задавать звук у конкретного уведомления. Для настройки звука уведомления его необходимо указать при создании канала

Настройка каналов. (только на Android)🔗

Для указания канала, который будет использоваться, воспользуйтесь полем:

notification.AndroidExtraOptions.ChannelId = "mrgs_unity" // идентификатор канала
notification.AndroidExtraOptions.ChannelName = "UnityMRGS" // его название
notification.AndroidExtraOptions.ChannelGroupId = "mrgs_unity_group" // группа, к которой относится канал
notification.AndroidExtraOptions.ChannelGroupName = "UnityMRGSGroup" // название группы

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

1. Создайте группу, к которой будет относится канал:

var notificationGroup = new MRGSNotificationChannelGroup();
notificationGroup.Id = "mrgs_unity_test";
notificationGroup.Name = "MRGS Unity";
MRGSNotificationCenter.Instance.CreateNotificationChannelGroup(notificationGroup);

1. Создайте сам канал:

var notificationChannel = new MRGSNotificationChannel();
notificationChannel.Id = "mrgs_unity_test";
notificationChannel.Name = "MRGS Unity";
notificationChannel.Description = "MRGS Notifications";
notificationChannel.ShouldVibrate = true;
notificationChannel.ShowLights = true;
notificationChannel.Group = "mrgs_unity_test";
notificationChannel.Sound = "custom_notification_sound"; // имя файла без расширения, который лежит в директории res/raw вашего android проекта

MRGSNotificationCenter.Instance.CreateNotificationChannel(notificationChannel);

Теперь, при создании уведомлений, вы можете указывать ChannelId, ChannelName, ChannelName, ChannelGroupName созданные с помощью этих методов. Для того, чтобы в серверных пуш уведомлениях можно было использовать этот канал, его так же необходимо предварительно создать.

Для получения списка каналов можно воспользоваться методом

MRGSNotificationCenter.Instance.GetNotificationChannels()

Для удаления канала

MRGSNotificationCenter.Instance.DeleteNotificationChannel("channel_id")

Видимость уведомлений на LockScreen(Secure). (только на Android)🔗

Если требуется дополнительное управление видимостью уведомлений на защищенном LockScreen(Который защищен паролем, пинкодом и тд.) необходимо указать область видимости.

// visibility - One of: LockScreenVisibility.Public, LockScreenVisibility.Private, LockScreenVisibility.Secret;
notification.AndroidExtraOptions.Visibility = visibility;

Выставление номера на иконке приложения на iOS🔗

Для этого можете воспользоваться свойством ApplicationIconBadgeNumber:

MRGSNotificationCenter.Instance.ApplicationIconBadgeNumber = 5;

Управление удалением полученных уведомлений на старте приложения. (Только для Андроид)🔗

В момент запуска приложения, MRGS удаляет все полученные уведомления пользователем из панели уведомлений для текущего приложение. Данное поведение можно отключить:

    var serviceParams = new MRGServiceParams(appId: "<APP_ID>", appSecret: "<APP_SECRET>")
    {
        AndroidExtraOptions =
        {
            ShouldClearNotificationsTray = true
        }
    };