Overview

Skill Level: Intermediate

IBM Mobile App Messaging supports the iOS image carousel for displaying photos and videos.

Prerequisites

To get started, you need:

  • The Mobile App Messaging SDK for iOS V3.7.1.2 (or later) on iOS 12 (or later)
  • A properly configured client app that can receive and display mobile app messages
  • An account with Watson Campaign Automation
  • Notification Service Extension

Configuring the payload

The Carousel action plug-in that is provided in the IBM Mobile App Messaging sample app lets you¬† add a “carousel” of photos and videos to mobile app messages. When a mobile app message is sent to a device, a banner is displayed, which the mobile user can drag down or click on to open the first image. The image slides into view from the right and the next image is downloaded in the background. Users move through the carousel’s images by clicking the Next and Previous buttons.

 

Carousel is implemented as a dynamic action category that includes the next, prev, carousel, and open category-actions. The carousel category-action contains an array of items with urls and text, which correspond to the images that are displayed in the carousel. The mutable-content flag in the app’s notification service enables the app to intercept and pre-process mobile app messages before presenting them to users.

Note: If you use images that are too large, iOS kills the carousel plugin. Apple does not document the size limitation. Ensure that you consider the size limitation when using the carousel plugin.

The payload contains the following keys:

  • mutable-content – Executes the notification service extension when the mobile app message arrives on the device. The notification service creates the carousel action category and the actions specified by the carousel category, and then it delivers the mobile app message to the operating system for further processing. ¬†
  • category – Set to carousel.
  • notification-action – Set type to carousel. When a payload with a type of “carousel” is received by the device, the carousel action category is executed.
  • category-name – Set to carousel. The notification service creates an action category with the name “carousel”.¬†
  • category-actions – Specify the actions that you want. For example: next, prev, carousel, and open.
  • carousel block – Contains an item array where the url and text for each item is specified. Items correspond to images that are displayed in the carousel.

Example payload in NotificationViewController.m:

{
    "aps": {
        "mutable-content": 1,
        "category": "carousel",
        "alert": {
            "title": "Testing Title",
            "subtitle": "Testing Subtitle",
            "body": "Testing Body"
        },
        "sound": "default"
    },
    "notification-action": {
        "type": "carousel"
    },
    "category-name": "carousel",
    "category-actions": [{
        "type": "next",
        "name": "Next"
    }, {
        "type": "prev",
        "name": "Previous"
    }, {
        "type": "carousel",
        "name": "Open",
        "destructive": false,
        "authentication": true,
        "foreground": true
    }],
    "carousel": {
        "items": [
            {"url": "https://www.ibm.com/blogs/bluemix/wp-content/uploads/2017/10/City-Speed-Card.jpg", "text": "Speed"},
            {"url": "https://www.ibm.com/blogs/bluemix/wp-content/uploads/2017/10/Agriculture-Card.jpg", "text": "Agriculture"},
            {"url": "https://www.ibm.com/blogs/bluemix/wp-content/uploads/2017/10/Containers-Docker-Kubernetes-Card.jpg", "text": "Containers"},
            {"url": "https://www.ibm.com/blogs/bluemix/wp-content/uploads/2017/10/Connected-City-Card.jpg", "text": "Connected"},
            {"url": "https://www.ibm.com/blogs/bluemix/wp-content/uploads/2017/10/Cloud-Laptop-Card.jpg", "text": "Cloud"}
        ]
    }
}

 For more information about actions and the notification service extension, see Advanced iOS push actions and action categories.

Step-by-step

  1. Add the Carousel action plug-in to your iOS project.

    Follow these steps:

    1. Open the Xcode project.
    2. Select File > New > Target.
    3. Select Notification Content Extension.
    4. Click the Next button.
    5. Select Carousel as the product name and ObjC as the language.
    6. Click the Finish button.
    7. Replace the contents of NotificationViewController.h, NotificationViewController.m, MainInterface.storyboard, and info.plist with the files in the Image Carousel Plugin folder.
    8. Select Carousel Target and setup code signing by selecting a Team in the General Tab.
    9. Add CarouselAction.h and CarouselAction.m to Application Target.
  2. Register the Carousel plug-in in the Application Delegate.

    Open the AppDelegate.m file and follow these steps:

    1. Add CarouselAction.h to the list of import statements.  For example:
      // Action Plugins
      #import "ActionMenuPlugin.h"
      #import "AddToCalendarPlugin.h"
      #import "AddToPassbookPlugin.h"
      #import "SnoozeActionPlugin.h"
      #import "DisplayWebViewPlugin.h"
      #import "TextInputActionPlugin.h"
      #import "ExamplePlugin.h"
      #import "CarouselAction.h" // add this line

      // MCE Inbox Plugins
      #import "MCEInboxActionPlugin.h"
      #import "MCEInboxPostTemplate.h"
      #import "MCEInboxDefaultTemplate.h"

      // MCE InApp Plugins
      #import "MCEInAppVideoTemplate.h"
      #import "MCEInAppImageTemplate.h"
      #import "MCEInAppBannerTemplate.h"
    2. Add [CarouselAction registerPlugin]; to either init or application:didFinishLaunchingWithOptions:
      For example:
        // MCE Inbox plugins
      [MCEInboxActionPlugin registerPlugin];
      [MCEInboxPostTemplate registerTemplate];
      [MCEInboxDefaultTemplate registerTemplate];

      // MCE InApp Plugins
      [MCEInAppVideoTemplate registerTemplate];
      [MCEInAppImageTemplate registerTemplate];
      [MCEInAppBannerTemplate registerTemplate];

      // Action Plugins
      [ActionMenuPlugin registerPlugin];
      [ExamplePlugin registerPlugin];
      [AddToCalendarPlugin registerPlugin];
      [AddToPassbookPlugin registerPlugin];
      [SnoozeActionPlugin registerPlugin];
      [DisplayWebViewPlugin registerPlugin];
      [TextInputActionPlugin registerPlugin];
      [CarouselAction registerPlugin]; // add this line

     

     

Expected outcome

The carousel plug-in is registered with the iOS app. Next, configure the carousel action in Watson Campaign Automation. For information, see Managing actions.

Join The Discussion

Your email address will not be published. Required fields are marked *