3.1.2. Sending Rich Push Notifications Using AppDelegate

Setup guide with Mindbox’s AppDelegate

🚧

Before you begin, make sure you have successfully completed the following steps:

• Setting up Integration Points for Your iOS App
• Getting Keys for iOS App and Setting up Connection to APNs
• Adding SDK to Your App
• Initializing SDK
• Sending Push Notifications

👍

If Sending Rich Push Notifications Using AppDelegate is successful:

• The target device will display a mobile push notification with a small square image on the right, unfolding to full screen once the image is long tapped.
• Once expanded, the mobile push notification displays the buttons you set up.

In addition to the usual title and body text in standard push notifications, rich push notifications can have a clickable image with up to 3 clickable buttons.

Displaying images in push notifications

👍

As a result of this step:

A push notification is displayed with a small square image on the right. A long tap unfolds the image to full screen.

To check that your push notifications with images are sent correctly, refer to How to check that a mobile push notification with an image is sent correctly.

To display images in push notifications, you’ll need to implement the Notification Service Extension.

1. Adding an extension

1. Open Xcode and go to Select File → New → Target...:

2. Select Notification Service Extension and click Next:

3. Enter the Product name MindboxNotificationServiceExtension and click Finish.
4. Click Cancel in the Activate Scheme dialog box.

2. Setting up the extension

2.1. App Groups

1. Open the project settings.
2. Select MindboxNotificationServiceExtension from the Targets.
3. Go to the Signing & Capabilities tab.
4. Click Add and select App Groups.
5. Add a new group named as group.cloud.Mindbox.{Bundle ID of your app}.

Example: with the app’s Bundle ID being Mindbox-Sample-App, name the relevant App Group as group.cloud.Mindbox.Mindbox-Sample-App.

❗️

App Groups setup is a prerequisite for Mindbox’s SDK

If you skip App Groups setup, the extension will fail to work when a push notification is received.

2.2. Signing the extension

Sign the extension using the same certificate you used to sign the app. With auto-signing enabled, the signature will be applied automatically. If not, you will have to manually create certificates for your targets and publish them on the Signing & Capabilities tab.

❗️

Check releases of your iOS Deployment Targets

Make sure that your main Target, Service extension, and Content extension specify the same iOS Deployment Target.

Go to your Target → Build Phases → Embed App. Extension and unselect Copy only when installing:

3. Implementing the extension code

3.1. Adding the SDK to the extension

Adding MindboxNotifications using Cocoapods: Service Extension

Open the Podfile and add the guide below to ensure that Mindbox’s SDK is used by the extension:

....
  
use_frameworks!

....
  
target '<your application>' do
  # Comment the next line if you don't want to use dynamic frameworks
  pod 'Mindbox'
end

...

# --- NEW ----
# Pods for MindboxNotificationServiceExtension
target 'MindboxNotificationServiceExtension' do
   pod 'MindboxNotifications'
end

...

Adding MindboxNotifications using Carthage: Service Extension

Set up MindboxNotifications for MindboxNotificationsServiceExtension:

1. Close Xcode with your project.
2. Access your Project folder from the terminal: cd path/to/project.
3. Run touch Cartfile to create a Cartfile.
4. Add the echo 'github "https://github.com/mindbox-cloud/ios-sdk.git"' → Cartfile to your Cartfile.
5. Run carthage update --no-use-binaries --use-xcframeworks. For Xcode 11 or older, run carthage update --no-use-binaries. Note that in the latter case all the .xcframework command examples should read as .framework.
6. Open your project in Xcode.
7. Go to the Project settings to select your Target. Go to the MindboxNotificationsServiceExtension tab.
8. Drag the MindboxNotifications.xcframework for your Extension onto the Frameworks, Libraries, and Embedded Content tab.

Set up MindboxNotifications for MindboxNotifcationsContentExtension:

1. Close Xcode with your project.
2. Access your project folder from the terminal cd path/to/project.
3. Run touch Cartfile to create a Cartfile.
4. Add the echo 'github "https://github.com/mindbox-cloud/ios-sdk.git"' → Cartfile to your Cartfile.
5. Run carthage update --no-use-binaries --use-xcframeworks. For Xcode 11 or older, run carthage update --no-use-binaries. Note that in the latter case all the .xcframework command examples should read as .framework.
6. Open your project in Xcode.
7. Go to the Project settings to select your Target. Go to the MindboxNotifcationsContentExtension tab.
8. Drag MindboxNotifications.xcframework for your Extension onto the Frameworks, Libraries, and Embedded Content tab.

Adding MindboxNotifications using Swift Package Manager: Service Extension

1. Open Xcode and go to File → Add Packages... from the upper menu.
2. Enter the URL to Mindbox’s SDK https://github.com/mindbox-cloud/ios-sdk in the window that appears.
3. Select version 1.3.3 or higher to support the Swift Package Manager and click Add Package.
4. Once the package has been downloaded, specify your target:
   • add Mindbox to the main project target,
   • add MindboxNotificationsService to MindboxNotificationServiceExtension.

3.2. Implementing the extension code in your app

📘

A basic way to implement the extension code into an app that works if:

• your app only sends Mindbox’s push notifications;
• you need to integrate the code ASAP.

Open the main extension file to perform the following:

• import the MindboxNotifications library;
• call the MindboxNotificationService() method;
• add 2 method calls: didReceive and serviceExtensionTimeWillExpire.

Simple implementation example:

import UserNotifications
import MindboxNotifications

class NotificationService: UNNotificationServiceExtension {

  lazy var mindboxService = MindboxNotificationService()

  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
    mindboxService.didReceive(request, withContentHandler: contentHandler)
  }

  override func serviceExtensionTimeWillExpire() {
    // Called just before the extension will be terminated by the system.
    // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
    mindboxService.serviceExtensionTimeWillExpire()
  }
}`

📘

An advanced method to implement the extension code into an app that it works if:

• you use multiple mailing providers;
• you need to implement a non-trivial logic to process notifications;
• you need to process the payload data;
• you apply a custom Content Extension.

How to apply the advanced method:

• Call MindboxNotificationService() to access open-source API methods;
• Check if the uniqueKey field is empty in your push notification. If it is not empty, the notification is probably from Mindbox, so call mindboxService.pushDelivered(request) to notify Mindbox that its push notification was received. If this push notification was not from Mindbox, the receipt notification will be ignored;
• Implement push notification processing using one of the methods:
  • Apply the MindboxNotificationService() methods from the example above, or
  • Handle all the fields in the push notification to implement processing manually. Use the iOS push notification format.

Example with minimum code, without content processing:

import UserNotifications
import MindboxNotifications

class NotificationService: UNNotificationServiceExtension {

  lazy var mindboxService = MindboxNotificationService()

  var contentHandler: ((UNNotificationContent) -> Void)?
  var bestAttemptContent: UNMutableNotificationContent?

  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {

    if(request.content.userInfo["uniqueKey"] as? String != nil) {
      mindboxService.pushDelivered(request)
    } 

    self.contentHandler = contentHandler
    self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

    guard let bestAttemptContent = self.bestAttemptContent else { return }
    contentHandler(bestAttemptContent)
  }


  override func serviceExtensionTimeWillExpire() {
    // Called just before the extension will be terminated by the system.
    // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
    if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
      contentHandler(bestAttemptContent)
    }

  }
}

To check that push notifications images are sent correctly, refer to How to check that a mobile push notification with an image is sent correctly.

Displaying buttons

👍

As a result of this step:

Mobile push notifications will expand to display the buttons you have set up.

To check that buttons appear when you tap a push notification, please refer to this guide.

To enable buttons to be displayed in push notifications, you’ll need to add the Notification Content extension.

1. Adding the extension

1. Open Xcode and click Select File → New → Target...:

2. Click Notification Content Extension and then Next:

3. Enter MindboxNotificationContentExtension for the Product name and click Finish.
4. Click Cancel in the Activate Scheme window.

2. Setting up the extension

2.1. App Groups

1. Open the project settings.
2. Select the main target MindboxNotificationServiceExtension in the project settings.
3. Go to the Signing & Capabilities tab.
4. Click Add and go to App Groups.
5. Add a new group with the following name: group.cloud.Mindbox.{Bundle ID of your app}.

For example: if the app’s Bundle ID is Mindbox-Sample-App, the App Group name must be group.cloud.Mindbox.Mindbox-Sample-App.

❗️

App Groups setup is a prerequisite for Mindbox’s SDK

If you skip App Groups setup, the extension will fail to work when a push notification is received.

2.2. Signing the extension

Sign the extension using the same certificate you used to sign the app. With auto-signing enabled, the signature will be applied automatically. If not, you will have to manually create certificates for your targets and publish them on the Signing & Capabilities tab.

❗️

Check releases of your iOS Deployment Targets

Make sure that your Main target, Service extension, and Content extension specify the same iOS Deployment Target.

2.3. Unselect Copy only when installing

Go to your Target → Build Phases → Embed App. Extension and unselect Copy only when installing:

3. Implementing the extension code

3.1. Adding SDK to the extension

Adding MindboxNotifications using Cocoapods: Content Extension

Open the Podfile and add the command below to ensure that Mindbox’s SDK is used by the extension.

....
  
use_frameworks!

....
  
target '<your application>' do
  # Comment the next line if you don't want to use dynamic frameworks
  pod 'Mindbox'
end

...

# Pods for MindboxNotificationServiceExtension
target 'MindboxNotificationServiceExtension' do
   pod 'MindboxNotifications'
end

...

# ---- NEW ----
# Pods for MindboxNotificationContentExtension
target 'MindboxNotificationContentExtension' do
   pod 'MindboxNotifications'
end

...

Adding MindboxNotifications using Carthage: Content Extension

Set up MindboxNotifications for MindboxNotificationsContentExtension:

1. Close Xcode with your project.
2. Access your Project folder from the terminal: cd path/to/project.
3. Run touch Cartfile to create a Cartfile.
4. Add the echo 'github "https://github.com/mindbox-cloud/ios-sdk.git"' → Cartfile to your Cartfile.
5. Run carthage update --no-use-binaries --use-xcframeworks. For Xcode 11 or older, run carthage update --no-use-binaries. Note that in the latter case all the .xcframework command examples should read as .framework.
6. Open your project in Xcode.
7. Go to the Project settings to select your Target. Go to the MindboxNotificationsContentExtension tab.
8. Drag the MindboxNotifications.xcframework for your Extension onto the Frameworks, Libraries, and Embedded Content tab.

Adding MindboxNotifications using Swift Package Manager: Content Extension

1. Open Xcode and go to File →Add Packages... from the upper menu.
2. Enter the URL to Mindbox’s SDK https://github.com/mindbox-cloud/ios-sdk in the window that appears.
3. Select version 1.3.3 or higher to support the Swift Package Manager and click Add Package.
4. Once the package has been downloaded, specify your target:
   • add Mindbox to the main project target,
   • add MindboxNotificationsContent to MindboxNotificationContentExtension.

3.2. Implementing the extension code in your app

📘

A basic method to implement the extension code into an app that works if:

• your app sends Mindbox’s push notifications only;
• you need to integrate the code ASAP.

Simply follow these 2 steps:

• Import the library into NotificationViewController.swift and call the MindboxNotificationService() API method from the file;
• Adjust your settings in info.plist.

Example of the basic implementation method:

import UIKit
import UserNotifications
import UserNotificationsUI
import MindboxNotifications

class NotificationViewController: UIViewController, UNNotificationContentExtension {

  lazy var mindboxService = MindboxNotificationService()

  func didReceive(_ notification: UNNotification) {
    mindboxService.didReceive(notification: notification, viewController: self, extensionContext: extensionContext)
  }

}

3.3 Setting up info.plist

Adjust info.plist as follows:

1. Delete the NSExtensionMainStoryboard key.
2. Add the following keys:

Your result should look like one in this screenshot:

3.4 Deleting MainInterface.storyboard

When you add the extension, a .storyboard file is created in the folder. Delete it to leave Mindbox’s API method to handle the UI.

📘

If the simple method above does not work for you, you can code your Rich Push layout from scratch.

There are no specific recommendations here — you do not have to specify any additional methods.

To check that buttons are displayed when you tap a push notification, please refer to this guide.

To debug common errors, refer to the SDK integration checklist.

👍

By now, you should see the following results:

Your target device can display mobile push notifications with a small square image on the right, a single long tap expands the image to full screen.

Once expanded, the mobile push notification displays the buttons you set up.