Перейти к содержанию

Подключение поддержки уведомлений на клиенте🔗

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

Получение уведомлений🔗

Шаг 1. Импортируйте модуль уведомлений и добавьте разрешения🔗

  • Убедитесь, что на сайте MRGS добавлены сертификаты для Developer и Release сборок вашего приложения.
  • Добавьте SDK в проект:

Шаг 1. Добавьте зависимости

Через Package collection

  • В Xcode выберите File > Add Packages
  • Выберите «+» > "Add Swift Package Collection"
  • Вставьте URL: https://mrgs-nexus.my.games/repository/ios-sdks/MRGSPackageCollection.json
  • Выберите модуль MRGSNotifications из "MRGS Package Collection".
  • Или вы можете выбрать пакет «MRGS» из "MRGS Package Collection" (содержит все модули mrgs в качестве продуктов), а затем выбрать только продукт "MRGS/Notifications".

Отдельными пакетами

  • В Xcode выберите File > Add Packages
  • В строке поиска в правом верхнем углу вставьте URL: https://mrgs-gitea.my.games/mrgs/mrgsnotifications-ios-sdk.git
  • Добавьте модуль в свой проект
  • Или вы можете вставить URL https://mrgs-gitea.my.games/mrgs/ios-sdks.git, чтобы подключить пакет "MRGS", который содержит все модули mrgs в качестве продуктов, а затем выбрать только продукт "MRGS/Notifications".

Шаг 2. Добавьте поддержку категорий ObjectiveC

  • В настройках проекта установите флаг -ObjC в поле "Other linker Flags".
  • Импортируйте модуль в коде: @import MRGServiceKit; или @import MRGSNotifications; или #import <MRGSNotifications/MRGSNotifications.h>

Шаг 1. Добавьте источники

В вашем podfile добавьте источники в начало файла:

source 'https://github.com/CocoaPods/Specs.git' # For main repo
source 'https://mrgs-gitea.my.games/mrgs/cocoapods-specs.git'  # For MRGS repo

Шаг 2. Добавьте зависимости

В target добавьте последнюю версию MRGSNotifications:

Чтобы добавить через subspecs:

target 'MyProject' do
    pod 'MRGS', '~> 5.0.0', :subspecs => ['Notifications']
end

Для добавления через отдельные модули:

target 'MyProject' do
    pod 'MRGSNotifications', '~> 5.0.0'
end

Чтобы добавить все модули mrgs:

target 'MyProject' do
    pod 'MRGS/AllKits', '~> 5.0.0'
end

Шаг 3. Установите зависимости

  • Выполните pod install (или pod install --repo-update если необходимо)
  • Импортируйте модуль в коде: @import MRGServiceKit; или @import MRGSNotifications; или #import <MRGSNotifications/MRGSNotifications.h>

Шаг 1. Добавьте зависимости

Добавьте зависимость в ваш Cartfile:

binary "https://mrgs-nexus.my.games/repository/ios-sdks/MRGSNotifications/MRGSNotifications.json" ~> 5.0.0

Шаг 2. Установите зависимости

  • Выполните carthage update --use-xcframeworks
  • Добавьте загруженные фреймворки в свой проект (убедитесь, что опция "do not embed" включена)
  • В настройках проекта установите флаг -ObjC в поле "Other linker Flags".
  • Импортируйте модуль в коде: @import MRGServiceKit; или @import MRGSNotifications; или #import <MRGSNotifications/MRGSNotifications.h>
  • Загрузите последнюю версию библиотеки. Распакуйте архив.
  • Добавьте MRGSNotifications.xcframework из скачанного архива в ваш проект (Перетащите библиотеки в раздел "Linked frameworks and Libraries") (для совместимости в архиве также находится MRGSNotifications.framework - fat framework старого вида)

  • В настройках проекта установите флаг -ObjC в поле "Other linker Flags".

  • Импортируйте модуль в коде: @import MRGSNotifications; или #import <MRGSNotifications/MRGSNotifications.h>
  • Также, вы можете добавить из архива файлы MRGServiceKit.h и module.modulemap в свой проект, либо в настройках проекта укажите путь до них в разделе Build Settings -> Header search paths. Теперь вместо импорта каждого из наших фреймворков по отдельности, вы можете импортировать только один заголовочный файл: @import MRGServiceKit;

Также, если вы хотите поддержки push-уведомлений, то необходимо в настройках проекта в XCode добавить необходимые разрешения на работу с ними:

Notification setting 1

И SilentPush-уведомлениями:

Notification setting 2

Если Вы хотите использовать уведомления с локацией

Если Вы будете использовать локальные уведомления, основанные на геопозиции пользователя (для подробностей смотрите пункт MRGSNotificationTrigger), то в Info.plist Вашего приложения необходимо добавить поле NSLocationWhenInUseUsageDescription (Xcode отображает его как "Privacy - Location When In Use Usage Description"), в котором необходимо описать зачем Вам необходимо разрешение на использование локации, пример необходимой части Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Мы хотим присылать Вам уведомления, когда Вы подходите к своей базе!</string>

Шаг 2. Настройка параметров🔗

При старте SDK MRGS необходимо добавить установку настроек allowPushNotificationHooks, shouldResetBadge:

@interface YourAppDelegate (MRGS)
@end
@implementation YourAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
    // MRGService settings
    MRGServiceParams *mrgsParams = [[MRGServiceParams alloc] initWithAppId: <MRGS_APP_ID> secret: <CLIENT_SECRET>];
    mrgsParams.allowPushNotificationHooks = YES; // Включить работу с уведомлениями
    mrgsParams.shouldResetBadge = YES; //Сброс номера на иконке при разворачивании

    //Дальнейшая настройка и инициализация MRGS
    // ...
}

Флаг shouldResetBadge необходимо выставить в true, если Вы хотите, чтобы MRGS работал с номером на иконке приложения - при запуске приложения номер на иконке будет обнуляться.

Также, если Вы хотите получать уведомление об открытии приложения по нажатию на уведомление, в AppDelegate в метод didFinishLaunchingWithOptions необходимо не забыть добавить код:

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [MRGService application:application didFinishLaunchingWithOptions:launchOptions];
    return YES;
}

Далее после старта SDK, MRGS все сделает сам, а именно:

  1. Запросит разрешение на отправку уведомлений
  2. При соглашении пользователя мы отправим на сервер MRGS deviceToken для отправки push-уведомлений

Запрос разрешения позже

Если Вам необходимо запросить разрешение на уведомления не на старте, а позже или если Вы не ставили вышеупомянутые флаги, и хотите вручную провести данный процесс (регистрации), обратитесь к разделу Ручное управление регистрацией и запросом разрешения

Trial notifications

iOS позволяет присылать уведомления до разрешения их пользователем, которые затем можно разрешить или отказаться от них.

notifications-ios-trial-notifications

Если вы хотите использовать такой тип разрешений, ознакомьтесь с разделом Работа с Trial (Provisional) Notifications

Запрос не всех разрешений (например, только баннеры, исключив звуки и бейджи)

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

// MRGService settings
MRGServiceParams *mrgsParams = [[MRGServiceParams alloc] initWithAppId: <MRGS_APP_ID> secret: <CLIENT_SECRET>];
// ...
// Исключение бейджей на иконке и звука, останутся только баннеры
[MRGSNotificationCenter excludePermissionsForNotificationsAuthorizationRequest:kMRGSAuthorizationOptionBadge + kMRGSAuthorizationOptionSound];

// Дальнейшая настройка и инициализация MRGS
// ...

Можно оставить только трекинг

Даже если Вы не хотите работать с уведомлениями с помощью MRGS, Вы можете отметить вышеупомянутые флаги в TRUE, MRGS просто будет наблюдать за приходом уведомлений и отправлять статистику на сервер. Единственное условие для такой "не мешающей и тихой" работы - на IOS 10+ Вами должен использоваться новый UNUserNotificationCenter, иначе, мы можем подписаться на его делегат, и уведомления о приходе уведомлений не будут доходить до старого делегата.

Шаг 3. Настройка делегата🔗

3.1. Делегат получения уведомлений🔗

Для получения callback'a о приходе уведомления, или о нажатии по нему, необходимо установить и реализовать делегат типа MRGSNotificationCenterDelegate.

//Установка общего делегата без разбиения по типу получаемых уведомлений (локальные или push)
[MRGSNotificationCenter currentCenter].delegate = self; //Где self - объект, реализующий протокол MRGSNotificationCenterDelegate

При получении уведомления, или нажатии на него, будет вызван метод делегата:

- (void)didReceiveNotification:(MRGSNotification* _Nonnull)notification{ //Получение
    NSLog(@"Received notification: %@", [notification description]);
}
- (void)didClickOnNotification:(MRGSNotification* _Nonnull)notification{ //Нажатие
    NSLog(@"Clicked on notification: %@", [notification description]);
}

Вы можете узнать тип полученного уведомления с помощью параметра notification.trigger.triggerType, о котором будет сказано ниже.

Что делать, если мы хотим раздельные делегаты для локальных и серверных уведомлений?

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

//Установка разделенного делегата с разбиением по типу получаемых уведомлений (отдельно локальные, отдельно push)
[MRGSNotificationCenter currentCenter].remoteDelegate = self;
[MRGSNotificationCenter currentCenter].localDelegate = self;

При получении уведомления, или нажатии на него, будет вызван метод делегата:

- (void)didReceive(Local|Remote)Notification:(MRGSNotification*)notification; //Получение
- (void)didClickedOn(Local|Remote)Notification:(MRGSNotification*)notification; //Нажатие

3.2. Делегат разрешения уведомлений🔗

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

Пример:

//Установка делегата
[MRGSNotificationCenter currentCenter].authorizationDelegate = self;

//Получение callback'a
- (void)didRequestUserNotificationsAuthorizationWithResult:(BOOL)granted {
    NSLog(@"Received notifiication that %@",[NSString stringWithFormat:@"User has %@ app to send notifications", granted ? @"granted" : @"not granted"]);
}

Работа с уведомлениями🔗

Основной объект, описывающий уведомление - MRGSNotification. Необходим для отправки локальных уведомлений, а также описывает полученное уведомление (как push, так и локальное).

Шаг 1. Создание🔗

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

MRGSNotification* notification = [MRGSNotification new];

Затем необходимо настроить уведомление:

notification.identifier = @"..."; //Уникальный идентификатор уведомления
notification.title = @"....."; //Заголовок уведомления
notification.subtitle = @"....."; //Подзаголовок уведомления.
notification.body = @"....."; //Тело уведомления. (Основной текст уведомления.)
notification.badge = 2; //Номер на иконке приложения. Если nil - номер не изменится, если 0 - номер будет спрятан. Значение по умолчанию - 1.

notification.userInfo = @{....}; //Дополнительная информация, добавляемая к уведомлению. (Для Push-уведомлении в данном поле находится payload)

//Настраиваем правило срабатывания (читайте ниже подробнее про MRGSNotificationTrigger)
notification.trigger = [MRGSNotificationTrigger triggerWithTimeInterval:7 repeats:NO]; //В данном случае уведомление будет показано через 7 секунд.

Мы также предоставляем возможность "быстрого" создания объектов уведомлений, вы можете воспользоваться быстрым созданием уведомления с помощью методов:

[MRGSNotification notificationWithTitle:@"..." body:@"..." identifier:@"..." trigger:TRIGGER]; //где TRIGGER - объект класса MRGSNotificationTrigger
[MRGSNotification notificationWithTitle:@"..." body:@"..."  trigger:TRIGGER];

[MRGSNotification notificationWithTitle:@"..." body:@"..." identifier:@"..." fireDate:DATE]; //где DATE - объект класса NSDate
[MRGSNotification notificationWithTitle:@"..." body:@"..."  fireDate:DATE]; //где DATE - объект класса NSDate
Значения по умолчанию

При создании объекта MRGSNotification поля по умолчанию:

  1. Поле sound = "default" - стандартный звук уведомлений
  2. Поле badge = 1

Шаг 2. Правила срабатывания🔗

MRGSNotificationTrigger - это класс для установки или определения правил срабатывания уведомлений. Он может быть четырех типов:

  1. kMRGSTimeIntervalTrigger - Триггер с заданным интервалом времени (Сработает через X секунд).
  2. kMRGSDateComponentsTrigger - Триггер с заданными правилами даты (Например, пятница, 15 часов 17 минут).
  3. kMRGSLocationTrigger - Триггер, основанный на локации пользователя.
  4. kMRGSRemoteTrigger - Триггер, говорящий о том, что уведомление является push-уведомлением.

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

//Создание kMRGSTimeIntervalTrigger триггера
MRGSNotificationTrigger* trigger = [MRGSNotificationTrigger triggerWithTimeInterval:70 repeats:NO]; //Сработает через 70 секунд.

//Создание kMRGSDateComponentsTrigger триггера
NSDateComponents* dateComponents = [[NSDateComponents alloc] init];
dateComponents.hour = 13;
dateComponents.minute = 00;
MRGSNotificationTrigger* trigger = [MRGSNotificationTrigger triggerWithDateComponents:dateComponents repeats:FALSE]; //Сработает в 13 часов 00 минут.

//Создание kMRGSLocationTrigger триггера
MRGSLocation* location = [MRGSLocation locationWithCenterX:55.797004 centerY:37.537710 radius:50]; //Задание географической области срабатывания
MRGSNotificationTrigger* trigger = [MRGSNotificationTrigger triggerWithLocation:location notifyOnEntry:TRUE notifyOnExit:TRUE repeats:FALSE]; //Сработает на входе и выходе из указанной области.

Параметр repeats: при создании говорит о том, будет ли триггер повторяемый (например повторяться каждые 70 секунд, каждый день в 13.00, срабатывать каждый раз при входе в указанную локацию).

Не забудьте отключить повтор

Иначе уведомления будут приходить бесконечно долго, пока установлено Ваше уведомление. На IOS 9 уведомления повторятся максимум десять раз, после этого нужно будет вновь добавить уведомление в очередь. При использовании kMRGSTimeIntervalTrigger триггера минимальный интервал для использования повторений должен быть 60 секунд.

Триггер в пришедшем уведомлении будет содержать поле triggerType, из которого можно понять, является ли данное уведомление локальным или удаленным, а также будет содержать соответствующие поля, содержащие данные для каждого типа триггера (интервал, или компоненты даты, или локацию).

Также можно воспользоваться быстрым созданием триггера на определенную дату в формате NSDate:

MRGSNotificationTrigger* trigger = [MRGSNotificationTrigger triggerWithDate:[NSDate dateWithTimeIntervalSinceNow:7]];

Шаг 3. Отправка🔗

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

[[MRGSNotificationCenter currentCenter] addNotification:notification];

Пример🔗

//В AppDelegate.m:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [MRGService application:application didFinishLaunchingWithOptions:launchOptions];
}

//В любом месте:
[MRGSNotificationCenter currentCenter].delegate = self;

//Отправка:
MRGSNotification* notification = [MRGSNotification new];
notification.title = @"Test local notification";
notification.body = @"Test local body";
notification.identifier = @"TestNotificationIdentifier1";
notification.userInfo = @{@"UserInfoTestKey" : @"UserInfoTestValue"};

notification.trigger = [MRGSNotificationTrigger triggerWithTimeInterval:70 repeats:NO];

[[MRGSNotificationCenter currentCenter] addNotification:notification];

//Получение:
- (void)didReceiveNotification:(MRGSNotification* _Nonnull)notification{
    NSLog(@"Received notification: %@", [notification description]);
    BOOL isRemote = notification.trigger.triggerType == kMRGSRemoteTrigger;
    NSLog(@"This notification is %@", isRemote ? @"Remote" : @"Local");
}
- (void)didClickOnNotification:(MRGSNotification* _Nonnull)notification{
    NSLog(@"Clicked on notification: %@", [notification description]);
    BOOL isRemote = notification.trigger.triggerType == kMRGSRemoteTrigger;
    NSLog(@"This notification is %@", isRemote ? @"Remote" : @"Local");
}

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

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

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

Для просмотра документации по данным функциями, перейдите в следующий раздел - кастомизация и дополнительные возможности


Последнее обновление: 2025-01-21
Дата создания: 2020-02-06