Skip to content

Connecting notifications on client🔗

To integrate notifications, you need to make a few simple steps:

Receiving notifications🔗

Step 1. Import the notification module and add permissions🔗

  • Make sure that the certificates for Developer and Release builds of your application are added on the MRGS website.
  • Add the SDK to the project:

Step 1: Add dependencies

Via Package collection

  • In Xcode select File > Add Packages
  • Select "+" > "Add Swift Package Collection"
  • Insert URL: https://mrgs-nexus.my.games/repository/ios-sdks/MRGSPackageCollection.json
  • Select module MRGSNotifications from "MRGS Package Collection".
  • Or you can select "MRGS" package from "MRGS Package Collection" (contains all mrgs modules as products) and then select "MRGS/Notifications" product only.

Individual packages

  • In Xcode select File > Add Packages
  • In the search bar at the top right, paste the URL: https://mrgs-gitea.my.games/mrgs/mrgsnotifications-ios-sdk.git
  • Add a module to your project
  • Or you can paste the url https://mrgs-gitea.my.games/mrgs/ios-sdks.git to include the "MRGS" package which contains all mrgs modules as products and then select only the product" MRGS/Notifications".

Step 2: Add support for ObjectiveC categories

  • Set the -ObjC flag in the "Other linker Flags" field in the project settings.
  • Import the module in code: @import MRGServiceKit; or @import MRGSNotifications; or #import <MRGSNotifications/MRGSNotifications.h>

Step 1. Add Sources

In your podfile, add sources to the top of the file:

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

Step 2: Add dependencies

Add the latest version of MRGSNotifications to target:

To add via subspecs:

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

To add via individual modules:

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

To add all mrgs modules:

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

Step 3: Install dependencies

  • Run pod install (or pod install --repo-update if necessary)
  • Import the module in code: @import MRGServiceKit; or @import MRGSNotifications; or #import <MRGSNotifications/MRGSNotifications.h>

Step 1: Add dependencies

Add the dependency to your Cartfile:

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

Step 2: Install dependencies

  • Run carthage update --use-xcframeworks
  • Add downloaded frameworks to your project (make sure "do not embed" option is enabled)
  • Set the -ObjC flag in the "Other linker Flags" field in the project settings.
  • Import the module in code: @import MRGServiceKit; or @import MRGSNotifications; or #import <MRGSNotifications/MRGSNotifications.h>
  • Download the latest version of the library. Unzip the archive.
  • Add MRGSNotifications.xcframework from the downloaded archive to your project (Drag the libraries to the "Linked frameworks and Libraries" section) (Also contains MRGSNotifications.framework for compatibility - fat framework)

  • Set the -ObjC flag in the "Other linker Flags" field in the project settings.

  • Import the module in code: @import MRGSNotifications; or #import <MRGSNotifications/MRGSNotifications.h>
  • Also, you can add the MRGServiceKit.h and module.modulemap files from the archive to your project, or specify the path to them in the project settings in the Build Settings -> Header search paths section. Now, instead of importing each of our frameworks separately, you can only import one header file: @import MRGServiceKit;

Additionally, if you want Push notifications support, you need to add the necessary permissions in the project settings in Xcode to work with them:

Notification setting 1

And Silent Push notifications:

Notification setting 2

If you want to use location-based notifications.

If you are going to use local notifications based on the user's geolocation (for details see MRGSNotificationTrigger), then in the Info.plist of your application you need to add the NSLocationWhenInUseUsageDescription field (Xcode displays it as "Privacy - Location When In Use Usage Description"), in which you need to describe why you need permission to use the location, here's an example of the necessary part of Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We want to send you notifications when you approach your base!</string>

Step 2. Parameter settings🔗

On launch of the MRGS SDK you need to add installation of the following settings 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; // Enable notifications
    mrgsParams.shouldResetBadge = YES; //Reset the number on the icon when expanded

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

The shouldResetBadge flag must be set to true if you want MRGS to work with the number on the application icon - when the application starts the number on the icon will be reset.

Additionally, if you'd like to receive a notification about the app being launched by a click on the notification, don't forget to add the following code into didFinishLaunchingWithOptions method in AppDelegate:

@implementation AppDelegate

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

Further, after the SDK launch, MRGS will do everything itself, namely:

  1. Request permission to send notifications.
  2. If the user agrees, we will send deviceToken to the MRGS server to send Push notifications.

Delaying permission request.

If you need to request permission to send notifications not at launch, but later, or if you did not set the above flags and want to manually perform this process (registration), refer to the Manual control of registration and permission request section.

Trial notifications

iOS allows you to send notifications until the user allows them, which can then be allowed or refused.

notifications-ios-trial-notifications

If you want to use this type of permission, see the section Working with Trial (Provisional) Notifications

Requesting not all permissions (for example, only banners, excluding sounds and badges)

By default, we will request all available permissions: sounds, banners, badge on the icon. If you want to request only a part of them (for example, you can only request alerts and badges, excluding the sound), you can use the excludePermissionsForNotificationsAuthorizationRequest method. This method must be called before initializing MRGS 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>];
// ...
// Exclusion of badges on the icon and sound, only banners will remain
[MRGSNotificationCenter excludePermissionsForNotificationsAuthorizationRequest:kMRGSAuthorizationOptionBadge + kMRGSAuthorizationOptionSound];

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

You can leave only tracking

Even if you do not want to work with notifications using MRGS, you can set the flags above in TRUE, and MRGS will simply watch for notifications arrival and send statistics to the server. The only condition for such a "non-interfering and quiet" work is that on IOS 10+ you must use the new UNUserNotificationCenter, otherwise, we can subscribe to its delegate, and notifications of incoming notifications will not reach the old delegate.

Step 3. Delegate setup🔗

3.1. Notification receiving delegate🔗

To receive a callback about a notification arrival, or about a click on it, you must install and implement a delegate of the MRGSNotificationCenterDelegate type.

//Set up a general delegate without dividing by the type of notifications received (local or Push)
[MRGSNotificationCenter currentCenter].delegate = self; //Where self - an object implementing the MRGSNotificationCenterDelegate protocol

Upon the arrival of notification, or a click on it the delegate method will be called:

- (void)didReceiveNotification:(MRGSNotification* _Nonnull)notification{ //Receiving
    NSLog(@"Received notification: %@", [notification description]);
}
- (void)didClickOnNotification:(MRGSNotification* _Nonnull)notification{ //Clicking
    NSLog(@"Clicked on notification: %@", [notification description]);
}

You can find out the type of notification received by using the notification.trigger.triggerType parameter, which will be discussed below.

What if we want separate delegates for local and server notifications?

We have such a capability. In this case, you need to install and implement delegate types MRGSNotificationCenterLocalDelegate and MRGSNotificationCenterRemoteDelegate.

//Set up a split delegate with a breakdown by the received notifications type (separate local, separate Push)
[MRGSNotificationCenter currentCenter].remoteDelegate = self;
[MRGSNotificationCenter currentCenter].localDelegate = self;

Upon the arrival of notification, or a click on it the delegate method will be called:

- (void)didReceive(Local|Remote)Notification:(MRGSNotification*)notification; //Receiving
- (void)didClickedOn(Local|Remote)Notification:(MRGSNotification*)notification; //Clicking

3.2. Notification permission delegate🔗

If you want to receive a callback at the moment when the user clicks the "Allow notifications" button with information about their decision, you can use the MRGSNotificationCenterAuthorizationDelegate delegate. The delegate must be set as soon as possible.

Example:

//Delegate setup
[MRGSNotificationCenter currentCenter].authorizationDelegate = self;

//Receiving callback
- (void)didRequestUserNotificationsAuthorizationWithResult:(BOOL)granted {
    NSLog(@"Received notifiication that %@",[NSString stringWithFormat:@"User has %@ app to send notifications", granted ? @"granted" : @"not granted"]);
}

Working with notifications🔗

The main object that describes the notification is the MRGSNotification. It is necessary for sending local notifications, and also describes the notification received (both Push and local).

Step 1. Creation🔗

To create a notification object, use the following method:

MRGSNotification* notification = [MRGSNotification new];

Then you need to configure the notification:

notification.identifier = @"..."; //Unique notification identifier.
notification.title = @"....."; //Notification header.
notification.subtitle = @"....."; //Notification subtitle.
notification.body = @"....."; //The body of the notification. (The main text of the notification.)
notification.badge = 2; //Number on the application icon. If nil - the number will not change, if 0 - the number will be hidden. Default value - 1.

notification.userInfo = @{....}; //Additional information added to the notification. (payload for Push notifications is located in this field)

//Setting up the trigger rule (read below for more details about MRGSNotificationTrigger)
notification.trigger = [MRGSNotificationTrigger triggerWithTimeInterval:7 repeats:NO]; //In this case, the notification will be displayed after 7 seconds.

We also provide the ability to "quickly" create notification objects - you can use the quick creation of a notification using the following methods:

[MRGSNotification notificationWithTitle:@"..." body:@"..." identifier:@"..." trigger:TRIGGER]; //where TRIGGER is an object of MRGSNotificationTrigger class
[MRGSNotification notificationWithTitle:@"..." body:@"..."  trigger:TRIGGER];

[MRGSNotification notificationWithTitle:@"..." body:@"..." identifier:@"..." fireDate:DATE]; //where DATE is an object of NSDate class
[MRGSNotification notificationWithTitle:@"..." body:@"..."  fireDate:DATE]; //where DATE is an object of NSDate class
Default Values

When creating the MRGSNotification object, the default fields are:

  1. Field sound = "default" - standart notification sound
  2. Field badge = 1

Step 2. Trigger rules🔗

MRGSNotificationTrigger is a class for setting or defining rules for triggering notifications. There are four types:

  1. kMRGSTimeIntervalTrigger - Trigger with a set time interval (Will trigger after X seconds).
  2. kMRGSDateComponentsTrigger - Trigger with set date rules (For example, Friday, 15 hours 17 minutes).
  3. kMRGSLocationTrigger - Trigger based on the user's location.
  4. kMRGSRemoteTrigger - Trigger indicating that notification is the Push notification.

To create the selected trigger (except for kMRGSRemoteTrigger - it is created by MRGS upon receiving the notification) use the following method:

//Creating the kMRGSTimeIntervalTrigger trigger
MRGSNotificationTrigger* trigger = [MRGSNotificationTrigger triggerWithTimeInterval:70 repeats:NO]; //Will trigger after 70 seconds.

//Creating the kMRGSDateComponentsTrigger trigger
NSDateComponents* dateComponents = [[NSDateComponents alloc] init];
dateComponents.hour = 13;
dateComponents.minute = 00;
MRGSNotificationTrigger* trigger = [MRGSNotificationTrigger triggerWithDateComponents:dateComponents repeats:FALSE]; //Will trigger at 13 hours 00 minutes.

//Creating kMRGSLocationTrigger trigger
MRGSLocation* location = [MRGSLocation locationWithCenterX:55.797004 centerY:37.537710 radius:50]; //Set the geographic area of operation
MRGSNotificationTrigger* trigger = [MRGSNotificationTrigger triggerWithLocation:location notifyOnEntry:TRUE notifyOnExit:TRUE repeats:FALSE]; //Will trigger on entering and leaving the specified area.

The repeats: parameter, when created, indicates whether the trigger will be repeated (for example, will it repeat every 70 seconds, every day at 13.00, or work each time user enters the specified location).

Don't forget to disable repeat

Otherwise, notifications will be sent endlessly while your notification is set. On IOS 8 and 9, notifications will be repeated a maximum of ten times, after that you will need to re-add the notification to the queue. When using the kMRGSTimeIntervalTrigger trigger, the minimum interval for using it repeatedly should be 60 seconds.

The trigger in the arrived notification will contain the triggerTypefield, from which you can determine whether the notification is local or remote, and it will also contain the corresponding fields with data for each type of trigger (interval, or date components, or location).

You can also use the quick creation of a trigger for a specific date in NSDate format:

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

Step 3. Sending🔗

To send a notification, use the following method:

[[MRGSNotificationCenter currentCenter] addNotification:notification];

Example🔗

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

//Anywhere:
[MRGSNotificationCenter currentCenter].delegate = self;

//Sending:
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];

//Receiving:
- (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");
}

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.

To check out the documentation on these functions, go to the next section - customization and additional features.


Last update: 2025-01-21
Created: 2020-02-17