Mobile Messaging SDK for iOS

Mobile Messaging SDK is designed and developed to easily enable push notification channel in your mobile application. In almost no time of implementation you get push notification in your application and access to the features of Infobip IP Messaging Platform. This document describes library integration steps. Additional information on advanced topics can be found in our wiki page.

Requirements

Xcode 10
Swift 4.2
iOS 9.0+

Quick start guide

This guide is designed to get you up and running with Mobile Messaging SDK integrated into your iOS application.

Prepare your App ID, provisioning profiles and APNs certificate (APNs Certificate Guide).
Prepare your Infobip account (https://portal.infobip.com/push/) to get your Application Code:
1. Create new application on Infobip Push portal.
2. Navigate to your Application where you will get the Application Code.
3. Mark the "Available on iOS" checkbox.
4. Mark the "Sandbox" checkbox if you are using sandbox environment for the application.
5. Click on "UPLOAD" under "APNS Certificates" and locate the .p12 certificate you exported from your Keychain earlier.
Configure your project to support Push Notifications:
1. Click on "Capabilities", then turn on Push Notifications. Entitlements file should be automatically created by XCode with set aps-environment value.
2. Turn on Background Modes and check the Remote notifications checkbox.
Installation

CocoaPods

To integrate MobileMessaging into your Xcode project using CocoaPods, specify it in your Podfile:
```
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!
pod 'MobileMessaging'
```
Notice

CocoaLumberjack logging used by default, in order to use other logging or switch it off follow this guide.

Carthage

If you use Carthage to manage your dependencies, just add MobileMessaging to your Cartfile:
```
github "infobip/mobile-messaging-sdk-ios"
```
If you use Carthage to build your dependencies, make sure you have added MobileMessaging.framework to the "Linked Frameworks and Libraries" section of your target, and have included them in your Carthage framework copying build phase (as described in Carthage documentation). If your application target does not contain Swift code at all, you should also set the EMBEDDED_CONTENT_CONTAINS_SWIFT build setting to “Yes”.
Perform code modification to the app delegate in order to receive push notifications.
At this step you are all set for receiving regular push notifications. There are several advanced features that you may find really useful for your product, though:
- Rich Notifications and better delivery reporting(available with iOS 10)
- Geofencing Service

App Delegate Changes

The simplest approach to integrate Mobile Messaging SDK with an existing app is by adding the SDK calls into your app delegate:

Import the library:

// Swift
import MobileMessaging

// Objective-C
@import MobileMessaging;

Start MobileMessaging service using your Infobip Application Code, obtained in step 2, and preferable notification type as parameters:

// Swift
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    MobileMessaging.withApplicationCode(<#your application code#>, notificationType: <#for example UserNotificationType(options: [.alert, .sound])#>)?.start()
	...
}

// Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    UserNotificationType *userNotificationType = [[UserNotificationType alloc] initWithOptions:<#for example @[UserNotificationType.alert, UserNotificationType.sound]#>;
    [[MobileMessaging withApplicationCode: <#your application code#> notificationType: userNotificationType] start:nil];
	...
}

Please note that it is not very secure to keep your API key (Application Code is an API key in fact) hardcoded so if the security is a crucial aspect, consider obfuscating the Application Code string (we can recommend UAObfuscatedString for string obfuscation).

Override method application:didRegisterForRemoteNotificationsWithDeviceToken: in order to inform Infobip about the new device registered:

// Swift
func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {
	MobileMessaging.didRegisterForRemoteNotificationsWithDeviceToken(deviceToken)
}

// Objective-C
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
	[MobileMessaging didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

Override method application:didReceiveRemoteNotification:fetchCompletionHandler: in order to send notification delivery reports to Infobip:

// Swift
func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject], fetchCompletionHandler completionHandler: (UIBackgroundFetchResult) -> Void) {
	MobileMessaging.didReceiveRemoteNotification(userInfo, fetchCompletionHandler: completionHandler)
}

// Objective-C
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
	[MobileMessaging didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
}

Skip this step is your apps minimum deployment target is iOS 10 or later. Override method application:didReceiveLocalNotification(for Objective-C) or application:didReceive:(for Swift) in order the MobileMessaging SDK to be able to handle incoming local notifications internally:

// Swift
func application(_ application: UIApplication, didReceive notification: UILocalNotification) {
	MobileMessaging.didReceiveLocalNotification(notification)
}

// Objective-C
-(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
    [MobileMessaging didReceiveLocalNotification:notification];
}

Mobile Messaging APIs

Events

Library informs you about following events using NSNotificationCenter:

Message received - is triggered after a message has been received.
Device token received - is triggered after an APNS registration token has been received from APNS.
Registration updated - is triggered after an APNS registration token has been successfully stored on the server.
API error - is triggered on every error returned by API.
Delivery reports sent - is triggered after a message delivery has been reported.
Message will be sent - is triggered when a mobile originated message is about to be sent to the server.
Message did send - is triggered after a mobile originated message has been sent to the server.
etc.

More information on library events available on our wiki page.

Linking with MSISDN

It is recommended that you link the GSM number (in MSISDN format). It will give an additional opportunity to target your application users and orchestrate your campaigns with OMNI Messaging service including SMS fallback feature.

// Swift
MobileMessaging.currentUser?.save(msisdn: <#for example "79091234567"#>, completion:
	{ error in
		<#handle the error if needed#>
	}
)

// Objective-C
[[MobileMessaging currentUser] saveWithMsisdn: <#for example @"79091234567"#>
								   completion: ^(NSError * _Nullable error)
{
	<#handle the error if needed#>
}];

akshardarji/mobile-messaging-sdk-ios