Overview

Skill Level: Intermediate

Creating in-app messages with templates.

Prerequisites

Notes:
  • Because of Apple changes, IBM Mobile App Messaging has rewritten the in-app message subsystem. If you are already using in-app messages and want to continue using them, you must upgrade your SDK to a version of at least 3.7.1.2. For more information, see In-app messages are changing.

 

Customize in-app messages with in-app templates

You can implement in-app messages that are displayed in your app as a header or footer. There are four templates you can use to customize your in-app messages. Keep in mind that you only need to implement the templates that you want to support.

  • MCEInAppMediaTemplate is the base class for the MCEInAppImageTemplate and MCEInAppVideoTemplate templates. If you want to use either of these templates, you must include the files from Plugins/InApp/Media Template; however, you do not have to register this template with the template registry, as it cannot be used independently.
  • MCEInAppVideoTemplate shows a video full screen along with an expandable text region below overlaid on top of your app content through a vibrant effect. Clicking the video opens the supplied action, clicking the text expands or collapses it, and swiping down or pressing X button closes it. The template automatically closes if there is no user interaction after the video is complete.
  • MCEInAppImageTemplate shows an image full screen along with an expandable text region below overlaid on top of your app content through a vibrant effect. Clicking the image opens the supplied action, clicking the text expands or collapses it, and swiping down or pressing X closes it. The template automatically closes if there is no user interaction within a default of 5 seconds.
  • MCEInAppBannerTemplate shows a banner either on the top or bottom of the screen. It will automatically close after a default of five seconds. It includes a centered text message, an optional left icon, and an optional background image.

 For informaton about best practices when specifying file sizes for media in in-app messages, see Best practices for images, video, and audio.

 

Step-by-step

  1. Add files to your Xcode project

    Drag in all the files from the Plugins/InApp folder in the SDK package to your Xcode project.

  2. Initialize the template class or classes

     To initialize the template class or classes in the application:didFinishLaunchingWithOptions: method of your app delegate. 

    @implementation AppDelegate
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     [MCEInAppVideoTemplate registerTemplate];
     [MCEInAppImageTemplate registerTemplate];
     [MCEInAppBannerTemplate registerTemplate];
    
  3. Pull pending in-app messages

    To pull pending in-app messages to the device, use the following command:

    [MCEInboxQueueManager.sharedInstance syncInbox];
    
  4. Set specified event call

    When a specified event occurs, call the MCEInAppManager executeRule: method.

    [[MCEInAppManager sharedInstance] executeRule:@[@"launch"]];
    
  5. Optional: Send a video in your in-app message

    If you want to send a video in your in-app message, you must set AllowInlineMediaPlayback to true in the platforms/ios/Sample/config.xml file.

Expected outcome

Example payloads for in-app messages:

  • in-app video template
    { 
     "aps": { "content-available": 1 }, 
     "inApp": 
     { 
     "rules": [ "all", "video" ], 
     "maxViews": 5, 
     "template": "video", 
     "content": { 
     "video": "https://sample-videos.com/video123/mp4/360/big_buck_bunny_360p_1mb.mp4", 
     "action":{ "value": "http://www.widget.com/1234", "type": "url" }, 
     "title":"Test iOS Style Title", 
     "text":"Test iOS Style Body", 
     }, 
     "triggerDate": "2015-06-03T13:21:58Z", 
     "expirationDate": "2017-12-03T13:21:58Z" 
     } 
    }
    
  • in-app image template
     { 
     "aps": { "content-available": 1 }, 
     "inApp": 
     { 
     "rules": [ "all", "image" ], 
     "maxViews": 5, 
     "template": "image", 
     "content": { 
     "image": "https://www.ibm.com/us-en/images/homepage/leadspace/01172016_ls_dynamic-pricing-announcement_bg_14018_2732x1300.jpg", 
     "action":{ "value": "http://www.widget.com/1234", "type": "url" }, 
     "title":"Test iOS Style Title", 
     "text":"Test iOS Style Body", 
     "duration": 10 
     }, 
     "triggerDate": "2015-06-03T13:21:58Z", 
     "expirationDate": "2017-12-03T13:21:58Z" 
     } 
    }
    
  • in-app banner template
     {
     "rules": ["rules", "to", "trigger", "on"],
     "maxViews": 5,
     "template": "default",
     "content": {
     "orientation":"top",
     "action": {"type":"url", "value": "http://ibm.co"},
     "text":"Template Text",
     "duration": 10
     "mainImage": "url of background image", 
     "icon": "note, comment, notification, offer or store",
     "color": "background color in hex format eg #FFFFFF"
     "foreground": "foreground color in hex format eg #000000"
     },
     "triggerDate": "date in ISO8601 format to trigger message"
     "expirationDate": "date in ISO8601 format to expire message"
    }
    

Example – targeting users with different in-app messages by using rules 

By using in-app message rules, you can target users with different in-app messages based on user behavior. Rules filter in-app messages and determine the messages that are displayed to users at different times.

For example, you can create different in-app messages for special offers and billing messages and then use rules to determine when users receive the messages. In this case, some messages are sent as offers and other messages with billing information are sent after users make purchases.

Consider a pizza delivery app. The app might display one set of in-app messages to people who are thinking about buying a pizza and another set of in-app messages to users who already purchased a pizza and are checking status. You don’t want to show an offer when a user is checking status or show a status before a user orders a pizza.

You can use in-app message rules to show appropriate messages at the appropriate times. Rules are strings that your app uses to differentiate types of in-app messages.

This scenario uses three rules:

  • offer – this rule displays offer messages.
  • pizzaready – this rule displays status messages when pizzas are ready for delivery.
  • all – this rule displays both offer and status messages.

To configure this scenario, follow these steps:

  1. Design your app with at least two screens. One screen is for pizza status; another screen is for new offers.
  2. Create an in-app message for offers and assign the corresponding rule. The following code sample shows an in-app message for offers that uses the “offer” and “all” rules. The expiration date is set to the date that the offer expires. In this case, users don’t see the offer after the expiration date.
     "inApp": {
     "content": {
     "action": {"type":"url", "value": "http://ibm.co"},
     "color": "#0aff00",
     "icon": "offer",
     "orientation":"top",
     "mainImage": "http://url/to/image"
     "text":"Buy one pizza, get one free next time you order, %%first_name%%. Use offer code 21582",
     },
     "expirationDate": "2017-09-07T00:00:00.000+00:00",
     "maxViews": 5,
     "rules": ["offer", "all"],
     "template":"default"
    }
    
  3. Create an in-app message for pizza deliveries and assign the corresponding rule. The following code sample shows an in-app message for pizza deliveries that uses the “pizzaready” and “all” rules. The “Your pizza went out for deliver” message uses a different icon and an expiration date that is much closer to today. In this case, users don’t see status messages from last week.
     "inApp": {
     "content": {
     "action": {"type":"url", "value": "http://ibm.co"},
     "color": "#0aff00",
     "icon": "note",
     "orientation":"top",
     "mainImage": "http://url/to/image"
     "text":"Your pizza went out for delivery at %%deliverytime%%",
     },
     "expirationDate": "2017-02-07T20:36:03.995+00:00",
     "maxViews": 1,
     "rules": ["pizzaready", "all"],
     "template":"default"
    }
    
  4. In your app on the pizza status page, call code to show in-app messages that use the “pizzaready” rule.
    [[MCEInAppManager sharedInstance] executeRule:@[@"pizzaready"]];
  5. In your app on the offer page, call code to show in-app messages that use the “offer” rule.
    [[MCEInAppManager sharedInstance] executeRule:@[@"offer"]];
  6. In your app on a page where you want to display all messages, call code to show in-app messages that use the “all” rule.
    [[MCEInAppManager sharedInstance] executeRule:@[@"all"]];

Note: The “all” rule matches both the offers and pizza-ready notices because you add the “all” rule to both messages. In fact, all rules are just strings to match when you call the code that shows the rule – they have only the meaning that your app assigns by determining when they are shown.
Results

Results

Offers are displayed on the offer screen, and pizza-ready messages are displayed on the status screen. It doesn’t matter which message comes in first – your customer sees the most appropriate message based on which part of the app they go into.

For information about other mobile app message features for iOS apps, see the Documentation.

Go Back to the Mobile App Messaging home page.

Join The Discussion

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