Advanced notification settings, additional features🔗

MRGS allows you to work with all the features and novelties in notifications, namely:

1. Request permission to send notifications at the time you need.
2. Get notification settings of the user.
3. Work with delivered and scheduled notifications.
4. Add buttons to notifications and customize their appearance.
5. Manage notification grouping in IOS 12+, including the summary view and its arguments.
6. Add attachments to notifications. (IOS 10+).
7. Add custom sounds to notifications.
8. The convenient way to turn on and off notifications on the client with just one method call, and we will take care of canceling notifications or invalidating the token (feature is useful for projects with a switch for notifications availability in the settings)
9. Put the number on the application icon
10. Work with Trial notifications on iOS.

Delaying the notification permission request🔗

In iOS, the first time you request permission to send notifications, the user will be shown a popup. With the standard setting of MRGSNotificationCenter, this popup will be shown at the very start of the application, which can negatively affect the number of permissions, this is bad practice, first it’s better to explain to the user why understanding is needed.

If you need to request permission for the first time from the user later (for example, by pressing a button, or after a certain screen), then you can start our MRGSNotificationCenter at the right time. After launch, permission to send notifications will be requested, a token has been received. To do this, at the parameter configuration step, you must set the deferredMRGSNotificationCenterStart flag to true:

@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; // Enable notifications
    mrgsParams.shouldResetBadge = YES; //Reset the number on the icon when expanded

    mrgsParams.deferredMRGSNotificationCenterStart = YES; // Deffered start setting to show popup later

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

Then, at the moment when you are ready to show the user a request, you need to call the method:

[[MRGSNotificationCenter currentCenter] enableMRGSNotifications];

Or other variations of this method (for more details on enabling and disabling notifications, see corresponding section).

After calling the method, our MRGSNotificationCenter will be launched, the popup will be shown. In the future, it is not necessary to call this method every time, we ourselves will automatically run MRGSNotificationCenter at the application start if the popup has been shown at least once.

Working with Trial (Provisional) Notifications🔗

When you explicitly request permission to send notifications, users must immediately decide whether to allow or deny them before they see notifications from the app. Users may not have enough information to make a decision and may deny authorization. You can use Provisional authorization - then users can first evaluate the notifications, and then decide whether to allow them or not.

The system discreetly delivers Trial notifications - they do not interrupt the user with a sound or banner and do not appear on the lock screen. Instead, they only appear in the Action Center history. Trial notifications also include buttons that prompt the user to leave or turn off the notification.

If the user clicks the "Leave" button, the system prompts him to choose between regular or silent notifications. If the user selects regular notifications, your app gets all permissions. If the user chooses to receive silent notifications, the system allows your app to send notifications, but does not allow your app to show alerts, play sounds, or tag a number on the app icon - your notification is only displayed in the notification center history. If the user clicks the Disable button, the system confirms the choice before denying your application authorization to send notifications. Read more in official documentation

To enable this request, you need to call the addExtraPermissionsForNotificationsAuthorizationRequest method. This method should be called before MRGS is initialized at every start, we recommend calling it when setting parameters for starting MRGS. Example:

// MRGService settings
MRGServiceParams *mrgsParams = [[MRGServiceParams alloc] initWithAppId: <MRGS_APP_ID> secret: <CLIENT_SECRET>];
// ...

[MRGSNotificationCenter addExtraPermissionsForNotificationsAuthorizationRequest:kMRGSAuthorizationOptionProvisional];

// Further configuration and initialization of MRGS
// ...

Since this functionality only works on iOS 12+, it will be ignored by MRGS on versions below. In order to check if the Trial Notifications functionality is available, you can use the method:

[MRGSNotificationCenter isProvisionalNotificationsRequestAvailable];

Enabling or disabling notifications🔗

MRGS allows you to easily enable or disable specific types of notifications on a user's device. This functionality is useful for projects where in the settings there is a switch for notifications availability. So you can control the availability of local and push notifications:

typedef enum MRGSNotificationsType : NSUInteger {
    /// Local and remote (push) notifications
    kMRGSNotificationsTypeAll = 1,
    /// Local notifications
    kMRGSNotificationsTypeLocal = 2,
    /// Remote notifications
    kMRGSNotificationsTypeRemote = 3,
} MRGSNotificationsType;

To disable a specific type of notification, you must call the method:

// Pass the type of notifications to be turned off to the method
[[MRGSNotificationCenter currentCenter] disableMRGSNotifications:kMRGSNotificationsTypeLocal];

// Or a method that disables all types of notifications
// (equivalent to calling above, i.e. with kMRGSNotificationsTypeAll parameter):
[[MRGSNotificationCenter currentCenter] disableMRGSNotifications];

After disabling local notifications, we will clear the current queue of scheduled and delivered notifications, and we will ignore the addition of new local notifications (with an output to the error log) until they are turned on again.

After disabling push notifications, we will send shutdown information to the MRGS server, and the token on the server will be disabled, that is, the notification will not reach the user. As soon as push notifications are turned on again, we will send a valid token to the MRGS server.

To enable a specific type of notifications again, use the method:

// In the method, pass the type of notifications that you need to turn on
[[MRGSNotificationCenter currentCenter] enableMRGSNotifications:kMRGSNotificationsTypeLocal];

// Or a method that turns on all types of notifications
// (equivalent to calling above, i.e. with kMRGSNotificationsTypeAll parameter):
[[MRGSNotificationCenter currentCenter] enableMRGSNotifications];

To check whether a specific type of notifications is currently enabled (all, local, push), a method is provided:

// Pass the type of notifications to be converted to a method
BOOL res = [[MRGSNotificationCenter currentCenter] isMRGSNotificationsEnabled:kMRGSNotificationsTypeAll];

Thus, you can easily turn on or off a certain type of notification, or both types at once. A small example is given below:

- (IBAction)enableNotificationsSwitched:(UISwitch *)sender {
    if(sender.isOn){
        // User turned on all notifications
        [[MRGSNotificationCenter currentCenter] enableMRGSNotifications];
    }else{
        // User turned off all notifications
        [[MRGSNotificationCenter currentCenter] disableMRGSNotifications];
    }
}

Getting user notification settings🔗

To get the settings, use the following method:

[[MRGSNotificationCenter currentCenter] getUserSettingsWithCompletionHandler:^(MRGSNotificationSettings * settings) {
    NSLog(@"User notification settings: %@", [settings getDictionaryRepresentation]);
}];

The returned object of the MRGSNotificationSettings class contains notification settings, including accessibility, whether banners, sounds, numbers on the application icon and other parameters are enabled (for IOS 10+), you can find the full list of fields in the class description.

If you need to know the general availability of notifications, then you can use the method that will return TRUE, if at least banners/display in the notification center/numbers on the icon/trial mode are enabled:

[[MRGSNotificationCenter currentCenter] isNotificationsEnabledWithCompletion:^(BOOL enabled) {
    if(enabled){
        //All ok, you can send notifications
    }else{
        //The user has disabled notifications, you can ask him to turn them back on
    }
}];

Managing delivered and scheduled notifications🔗

With MRGS you can:

For scheduled notifications (Not yet delivered, the trigger didn't fire yet):

1. Find a notification with the specified identifier in the scheduled notifications,
2. Get a list of all scheduled notifications,
3. Cancel scheduled notifications with specified identifiers,
4. Cancel all scheduled notifications.

For all of this, use the methods of the MRGSNotificationCenter class:

findPendingNotificationWithIdentifier:completionHandler:;
getPendingNotificationsWithCompletionHandler:;
removePendingNotificationsWithIdentifiers:;
removeAllPendingNotifications;

For already delivered notifications (will work on iOS 10+):

1. Find a notification with the specified identifier in the delivered ones,
2. Get a list of all delivered notifications,
3. Cancel the delivered notifications with the specified identifiers,
4. Cancel all delivered notifications.

For all of this, use the following methods:

findDeliveredNotificationWithIdentifier:completionHandler:;
getDeliveredNotificationsWithCompletionHandler:;
removeDeliveredNotificationsWithIdentifiers:;
removeAllDeliveredNotifications;

Adding buttons and customizing them🔗

In order for the system to know which buttons to display, it is necessary to register them.

Registration can't work for individual buttons, but for categories (types) of notifications, which, in turn, contain buttons. When working with MRGS, the classes MRGSNotificationAction and MRGSNotificationCategory are used for registration.

To create a category, use the following method:

//Create buttons, they have an identifier that will return when pressed and the displayed text
MRGSNotificationAction* action1 = [MRGSNotificationAction actionWithIdentifier:@"TestAction1_ID" title:@"TestAction1"];
MRGSNotificationAction* action2 = [MRGSNotificationAction actionWithIdentifier:@"TestAction2_ID" title:@"TestAction2"];

//Create a notification type that contains two previously created buttons and has a unique identifier
MRGSNotificationCategory* category1 = [MRGSNotificationCategory categoryWithIdentifier:@"CATEGORY_1" actions:@[action1, action2]];

Then you need to register the created categories:

//Register an array of created categories
[[MRGSNotificationCenter currentCenter] registerCategories:@[category1, ...]];

To add a notification from a certain category, add the following line when setting up:

notification.categoryIdentifier = @"CATEGORY_1"; //Category id

If the user clicked the button in the notification, then in the callback that came to you in the MRGSNotification object the deliveryChosenActionIdentifier field will contain the identifier (transferred when creating the MRGSNotificationAction) of the pressed button.

Managing grouping for IOS 12+🔗

On iOS 12, all notifications are grouped. If you want to manage the grouping (i.e., split the notification group from your application into, let's say, two or three groups), you need to add the following line when creating a notification:

notification.threadIdentifier =@"THREAD_1"; //Select a grouping stream

The choice of the stream identifier is up to you.

If you want one notification to be counted as three (by weight) when grouping, and if you want to specify the name of the group (displayed at the bottom right of the notification), use the following fields:

notification.summaryArgumentCount = 3;
notification.summaryArgument = @"MRGSSS";

If you want to choose the format of the explanatory line when grouping, then use the following method when creating a category:

[MRGSNotificationCategory categoryWithIdentifier: @"..." actions: @[...] summaryFormat: @"FORMAT" placeHolder: @"PHOLDER"]; //Where FORMAT is the format of the string when grouping, is the text if the user has enabled hiding notifications on a locked screen

Adding attachments to notifications🔗

To add an attachment, use the following field:

NSURL* attachment1 = [[NSBundle mainBundle] URLForResource:@"forest" withExtension:@"jpg"]; //Example of getting the URL of a picture from the mainBundle
NSArray* URLsOfAttachments = @[attachment1, ...];
notification.attachments = URLsOfAttachments; //Array with paths (URL) to attachments

Adding custom sounds to notifications🔗

To add your custom sound that plays when a notification arrives, use the following field:

notification.sound = @"CustomNotificationSound.caf"; //Where @"***.caf" - the name of the sound file you've put in the MainBundle of the application.

Placing a number on the application icon🔗

To do this, you can use the applicationIconBadgeNumber property:

[MRGSNotificationCenter currentCenter].applicationIconBadgeNumber = 5;

Show notification while app is running🔗

If you want to show a system notification while the application is running, implement the MRGSNotificationCenterDelegate delegate method, and return the required display options (None|Alert|Badge|etc.):

-(void)shouldPresentNotification:(MRGSNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler API_AVAILABLE(ios(10.0)){
    if([notification.categoryIdentifier isEqualToString:@"CATEGORY_1"]){
        completionHandler(UNNotificationPresentationOptionAlert);
    }else{
        completionHandler(UNNotificationPresentationOptionNone);
    }
}