Overview

Skill Level: Intermediate

Prerequisites

To get started, you need:

  • The Mobile App Messaging SDK for Android 3.7.1.3 or higher. The Carousel will only be displayed if SDK 3.7.1.3 or later is used.
  • A properly configured client app that can receive and display mobile app messages.
  • An account with Watson Campaign Automation.
  • An API account in order to send the payload (the Carousel plugin is not yet supported in the UI).

 

How the plug-in works

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.

When the notification is expanded, the first image will appear with its label. The label’s text is the name of the image action. Under the image and the text there will be two buttons: next and previous. Clicking on them will change the image to the next/previous image and the the label to the next/previous image label.

Clicking on the image or the text removes the notification and performs the image action. 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.

Like all expandable notifications, the Carousel plugin works only on Android 5 (API 21, Lollipop) and higher. If a carousel message is sent to a device with a lower version of Android, a simple notification will be displayed and the action will be the first image action.

 

 

 

The carousel payload contains an array of items with URLs and text, which correspond to the images that are displayed in the carousel.

Note: If you use images that are too large, Android stops the carousel plugin. Ensure that you consider the size limitation when using the carousel plugin.

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 Android project:

    Follow these steps:

    1. Open your Android Studio project.
    2. Add carousel.json to your assets/mce.plugins directory.
    3. Add ibm-mobile-push-android-sdk-plugin-carousel-3.7.1.3.jar to your project’s libs directory.
    4. Copy the mce_carousel_*.png images into  your res/drawable directory.
    5. Copy mce_carousel_notification.xml into your res/layout directory.
  2. Send a carousel action via API:

    The carousel payload is:

    {
    "next": "<text of next image button>",
    "prev": "<text of previous image button>",
    "carousel": <array of carousel actions> (carousel action is )
    }
    

    The carousel action is:

    {
    "image": "<image url>",
    "action": <mce action element>
    }
    

    The MCE action element is the same format as the notification action.

    Configuring the payload:

    The payload contains the following keys: 

    • type: must be “carousel”
    • subject: the subject (string) displayed before the carousel is opened
    • message: the message (string) displayed before the carousel is opened
    • payload: JSON which contains next, prev and carousel entries.
    • next: the text (string) of the button which moves the carousel forward
    • prev: the text (string) of the button which moves the carousel backward
    • carousel: a JSON array of image and action fields
    • image: a URL (string) of an image to display
    • action: JSON which contains the usual type, name and value to take when an image is clicked

    Sample payload from Carousel:

    {
      "alert": {
        "type": "carousel",
        "subject": "Carousel Subject",
        "message": "Carousel Message",
        "payload": {
          "next": "Next",
          "prev": "Prev",
          "carousel": [
            {"image": "https://pviq.com/images/pexels-photo-573316.jpg", "action": {"type": "openApp", "name": "Take photos"}},
            {"image": "https://pviq.com/images/pexels-photo-877695.jpg", "action": {"type": "url", "name": "Drink coffee", "value": "http://www.google.com"}},
            {"image": "https://pviq.com/images/pexels-photo-879718.jpg", "action": {"type": "dial", "name": "See the future", "value": "11111111111"}},
            {"image": "https://pviq.com/images/pexels-photo-879474.jpg", "action": {"type": "url", "name": "Hold the light", "value": "http://www.cnn.com"}},
            {"image": "https://pviq.com/images/pexels-photo-618545.jpg", "action": {"type": "url", "name": "Capture the moment", "value": "http://www.ibm.com"}}
          ]
        }
      },
      "mce": {
        "attribution": "ATTR",
        "mailingId": "MAILID"
      }
    }
    

     

     

Expected outcome

The carousel plug-in is registered with the Android 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 *