iOS destination SDK for IBM Cloud Event Notifications service Version 0.0.5

iOS destination client library to interact with various IBM Cloud Event Notifications Service.

Disclaimer: this SDK is being released initially as a pre-release version. Changes might occur which impact applications that use this SDK.

Table of Contents

• Prerequisites
• Installation
• Using the SDK
• Questions
• Issues
• Open source @ IBM
• Contributing
• License

Overview

The IBM Cloud Event Notifications Service iOS destination SDK allows developers to register for APNS destiantion of Event Notifications service in IBM cloud.

Service Name	Artifact Coordinates
Event Notifications Service	ENPushDestination:0.0.5

Prerequisites

• An IBM Cloud account.
• An Event Notifications Instance
• An IAM API key to allow the SDK to access your account. Create one here.
• Xcode 10+
• Swift 4.2+
• iOS 12.0+

Installation

The current version of this SDK is: 0.0.5

To use the Event Notifications iOS destination SDK, define a dependency that contains the artifact coordinates (group id, artifact id and version) for the service, like this:

Cocoapods

use_frameworks!

target 'MyApp' do
    pod 'ENPushDestination', '~> 0.0.5'
end

Carthage

To install ENPushDestination using Carthage, add the following to your Cartfile.

  github "IBM/event-notifications-destination-ios-sdk" ~> 0.0.5

Then run the following command to build the dependencies and frameworks:

$ carthage update --platform iOS

Swift Package Manager

Add the following to your Package.swift file to identify ENPushDestination as a dependency. The package manager will clone ENPushDestination when you build your project with swift build.

dependencies: [
    .package(url: "https://github.com/IBM/event-notifications-destination-ios-sdk", from: "0.0.5")
]

Using the SDK

SDK Methods to consume

• Initialize SDK
  • Initialize SDK
• Register for notifications
  • Receiving notifications
  • Unregistering from notifications
• Event Notifications destination tags subscriptions
  • Subscribe to tags
  • Retrieve subscribed tags
  • Unsubscribe from tags
• Receiving push notifications on iOS devices
• Notification options
  • Interactive notifications
  • Adding custom DeviceId for registration
  • Enabling rich media notifications

Installation

Initialize SDK

Complete the following steps to enable iOS applications to receive notifications.

1. Add the import statements in your .swift file.

   import ENPushDestination
   

2. Initialize the ENPushDestination SDK

   
   let instanceGUID = "<instance_guid>>";
   let destinationID = "<instance_destination_id>";
   let apiKey = "<instance_apikey>";
   
   let enPush = ENPush.sharedInstance
   enPush.setCloudRegion(region: .usSouth)
   enPush.initialize(instanceGUID, destinationID, apiKey)
   

   • region : Region of the Event Notifications Instance. eg; Region.usSouth, Region.london, Region.sydney, Region.frankfurt and Region.madrid

Register for notifications

Use the ENPush.registerDevice() API to register the device with iOS destination in Event Notifications service.

The following options are supported:

• Register without userId:

   /**Register iOS devices*/
   enPush.registerWithDeviceToken(deviceToken: "<apns-device-token>") { response, statusCode, error in
  
       print(response?.id ?? "")
  
   }
  

• Register with UserId. For userId based notification, the register method will accept one more parameter - userId.

   /**Register iOS devices*/
   enPush.registerWithDeviceToken(deviceToken: "<apns-device-token>", withUserId: "userId") { response, statusCode, error in
           
       print(response?.id ?? "")
  
   }
  

The userId is used to pass the unique userId value for registering for Event notifications.

Unregistering from notifications

Use the following code snippets to un-register from Event Notifications.

enPush.unregisterDevice { response, statusCode, error in
    /**.....*/  
}

Note: To unregister from the UserId based registration, you have to call the registration method. See the Register without userId option in Register for notifications.

Event Notifications destination tags subscriptions

Subscribe to tags

The subscribe API will subscribe the device for a given tag. After the device is subscribed to a particular tag, the device can receive notifications that are sent for that tag.

Add the following code snippet to your iOS mobile application to subscribe to a list of tags.

// Subscribe to the given tag
enPush.subscribeToTags(tagName: "<tag_name>") { response, statusCode, error in
	/**.....*/  
});

Retrieve subscribed tags

The retrieveSubscriptionsWithCompletionHandler API will return the list of tags to which the device is subscribed. Use the following code snippets in the mobile application to get the subscription list.

// Get a list of tags that to which the device is subscribed.
enPush.retrieveSubscriptionsWithCompletionHandler { response, statusCode, error in
    /**.....*/   
}

Unsubscribe from tags

The unsubscribeFromTags API will remove the device subscription from the list tags. Use the following code snippets to allow your devices to get unsubscribe from a tag.

// unsubscibe from the given tag ,that to which the device is subscribed.
enPush.unsubscribeFromTags(tagName: "<tag_name>") { response, statusCode, error in
  /**.....*/   
}

Receiving push notifications on iOS devices

To receive push notifications on iOS devices, add the following Swift method to the appDelegate.swift of your application:

 func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {

	//UserInfo dictionary will contain data sent from the server
 }

Notification options

The following notification options are supported.

Interactive notifications

1. To enable interactive push notifications, the notification action parameters must be passed in as part of the notification object. The following is a sample code to enable interactive notifications:

let actionOne = ENPushNotificationAction(identifierName: "FIRST", buttonTitle: "Accept", isAuthenticationRequired: false, defineActivationMode: .foreground)
    
let actionTwo = ENPushNotificationAction(identifierName: "SECOND", buttonTitle: "Reject", isAuthenticationRequired: false, defineActivationMode: .destructive)
    
let category = ENPushNotificationActionCategory(identifierName: "category", buttonActions: [actionOne, actionTwo])

let notificationOptions = ENPushClientOptions()
notificationOptions.setInteractiveNotificationCategories(categoryName: [category])
enPush.initialize(instanceGUID, destinationID, apiKey, notificationOptions)

2. Implement the callback method on AppDelegate.swift:

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
	switch response.actionIdentifier {
		case "Accept":
		print("Clicked Accept")
		case "Reject":
		print("Clicked Reject")
		default:
	}
	completionHandler()
 }

This callback method is invoked when user clicks the action button. The implementation of this method must perform tasks associated with the specified identifier and execute the block in the completionHandler parameter.

Adding custom DeviceId for registration

To send DeviceId use the setDeviceId method of ENPushClientOptions class.

	let options = ENPushClientOptions();
	options.setDeviceId(deviceId: "YOUR_DEVICE_ID");

Note: Remember to keep custom DeviceId unique for each device.

Enabling rich media notifications

Rich media notifications are supported on iOS 10 or later. To receive rich media notifications, implement UNNotificationServiceExtension. The extension will intercept and handle the rich media notification.

In the didReceive() method of your service extension, add the following code to retrieve the rich push notification content.

override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
	self.contentHandler = contentHandler
	bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
    ENPushRichPushNotificationOptions.didReceive(request, withContentHandler: contentHandler)
}

Sending Delivery Status for notifications

You can send notification status (SEEN/OPEN) back to Event Notifiation service, implement sendDeliveryStatus function to use this.

Based on when notification was received by intercepting the notification, you can send back SEEN and when its opened you can send back OPEN.

To use this function example is given below

For status open -

ENPush.sharedInstance.sendDeliveryStatus(notificationId:"en_nid",status: ENDeliveryStatus.open){ response, statusCode, error in
            guard error.isEmpty else {
                return
            }
            print(response ?? "")
        }

For status seen -

ENPush.sharedInstance.sendDeliveryStatus(notificationId:"en_nid",status: ENDeliveryStatus.seen){ response, statusCode, error in
            guard error.isEmpty else {
                return
            }
            print(response ?? "")
        }

Questions

If you are having difficulties using this SDK or have a question about the IBM Cloud services, please ask a question at Stack Overflow.

Issues

If you encounter an issue with the project, you are welcome to submit a bug report. Before that, please search for similar issues. It's possible that someone has already reported the problem.

Open source @ IBM

Find more open source projects on the IBM Github Page

Contributing

See CONTRIBUTING.

License

The IBM Cloud Event Notifications Service iOS destination SDK is released under the Apache 2.0 license. The license's full text can be found in LICENSE.