Overview

Skill Level: Intermediate

In-app messages are messages that get pushed to an app, but are only displayed when a specific event occurs. In-app messages are similar to ads in mobile apps. The payload sent to the device contains the message and array of strings called rules. You can decide at which points in the app to show the in-app message and which rule is matched. Messages are displayed once by default, and are defined by maxView. Allowing the maxView value gives you more power behind your message so that you can show it more than one time. Messages can have various visual styles based on the template used and how the app handles that template.

Prerequisites

You can implement in-app messages that are displayed in your app as a header or footer for your Android app.

Notes:
  • 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 that supports the new in-app message delivery mechanism by early summer (exact date to be determined). For more information, see In-app messages are changing.
  • In Release 3.6.5.0 of the IBM Mobile App Messaging Android SDK, plug-in files are delivered in aar and zip file formats. If you want to use the zip files to implement in-app messages, follow steps 1 through 9. If you are using the aar files to implement in-app messages, add the aar files to your project and to the build.gradle file, and then follow steps 5 through 9. You can find the aar plug-in files in ibm-mobile-push-android-sdk-3.6.5.0/plugins.

 

 

Step-by-step

  1. Extract the contents of the Android SDK zip file from the plugins folder.

    Extract the contents of ibm-mobile-push-android-sdk-plugin-inapp-<version number>.zip from the plugins folder.

    The file contains the following information:

    • ibm-mobile-push-android-sdk-plugin-inapp-<version number>.jar under the bin directory
    • Plug-in sources under plugin-inapp/src/main/ava
    • Plug-in resources under plugin-inapp/src/ main/res
  2. Add the Android SDK jar file to your project.

    The ibm-mobile-push-android-sdk-plugin-inapp-<version number>.zip file is located in the plugins folder in the SDK package. Extract the jar file and add it to your libs directory.

  3. Copy resources to your project.

    Copy the resources that are located under layout (all layout folders), res/menu, and drawable (all the drawable folders).

  4. Add strings from the res/values/strings.xml file to your project strings.xml file.

    Add the hello_world and action_settings strings from the res/values/strings.xml file.

  5. Optional. If you are upgrading in-app messages from an earlier release to 3.6.5.0, you might want to add dependencies for the Realm database to your build.gradle file.

  6. To pull pending in-app messages to the device, use the following code:

    InboxMessagesClient.loadInboxMessages(getApplicationContext(), new OperationCallback<List<RichContent>>() {
    @Override
    public void onSuccess(List<RichContent> richContents, OperationResult result)
    { InAppManager.show(getApplicationContext(), getSupportFragmentManager(), resourcesHelper.getId("con")); }
    
    @Override
    public void onFailure(List<RichContent> richContents, OperationResult result) { InAppManager.show(getApplicationContext(), getSupportFragmentManager(), resourcesHelper.getId("con")); }
    
    });
    
  7. To show the in-app call, use the following code:

    InAppManager.show(this, getSupportFragmentManager(), R.id.container_layout);
    

    Note: Only RelativeLayout is supported as a container for in-app notifications.

  8. To send an in-app message, the following code must be added to the notification payload:

    "inApp": { 
     "actions": [
     {"name":"<action name>", "value":"<action value>"},
     ...
     ], 
     "rules": ["<rule 1 name>", "rule 2 name", ...], 
     "maxViews": <maximum number of time the message will be displayed>, 
     "template": "<template name", 
     "content": <content json element - see content below> 
    }
    
  9. You can choose between default, image, and video templates.

    The default template shows a banner either at the top or bottom of the screen. The banner contains text and the option for an icon. Clicking the banner performs a single action. The following code is a payload example:

    { 
     "text": "<banner text>", 
     "color": "<background color>", [optional - default is "#ff5886fa"] 
     "foreground": "<foreground color>", [optional - default is black] 
     "icon": "<banner icon resource name>", [optional] 
     "duration": <how many seconds the message will be displayed before being automatically closed - 0 for unlimited time>, [optional - default is 20 seconds]
     "orientation": <where the banner will appear - either "top" or "bottom">, [optional - default is "bottom"] 
     "action": <the action the will occur when clicking the banner - use the notification payload action content> [optional] 
    }
    

    The image template shows a full screen view with an image and the option for a text description. Clicking the image performs a single action. The following code is a payload example:

    { 
     "title" - "<the title of the description text>", [optional]
     "text": "<description text>", [optional] 
     "image": "<image url>",
     "duration": <how many seconds the message will be displayed before being automatically closed - 0 for unlimited time>, [optional - default is 20 second
     "action": <the action the will occur when clicking the image - use the notification payload action content> [optional]}
    

    The video template shows a full screen view with a video stream and possibly text description. Clicking the video stream performs a single action. The message disappears when the video ends. The following code is a payload example:

    { 
     "title" - "<the title of the description text>", [optional] 
     "text": "<description text>", [optional] 
     "video": "<video stream url>",
     
     "action": <the action the will occur when clicking the image - use the notification payload action content> [optional]}
    

Expected outcome

The following Android JSON template examples show you how to add different types of content to your in-app messages.

In-app video template

The following payload example shows you how to include a video in your in-app message.

{
"rules": ["rules", "to", "trigger", "on"],
"maxViews": 5,
"template": "video",
"content": {
"title" - "<the title of the description text>", [optional] "text": "<description text>", [optional]
"video": "<video stream url>",
"action": <the action the will occur when clicking the image - use the notification payload action content> [optional] },
"triggerDate": "date in ISO8601 format to trigger message"
"expirationDate": "date in ISO8601 format to expire message"
}

In-app image template

The following payload example shows you how to include an image in your in-app message.

{
"rules": ["rules", "to", "trigger", "on"],
"maxViews": 5,
"template": "image",
"content": {
"title" - "<the title of the description text>", [optional] "text": "<description text>", [optional]
"image": "<image url>",
"duration": <how many seconds the message will be displayed before being automatically closed - 0 for unlimited time>, [optional - default is 20 seconds]
"action": <the action the will occur when clicking the image - use the notification payload action content> [optional] },
"triggerDate": "date in ISO8601 format to trigger message"
"expirationDate": "date in ISO8601 format to expire message"
}

In-app default template

The following payload example shows you how to include a banner in your in-app message.

{
"rules": ["rules", "to", "trigger", "on"],
"maxViews": 5,
"template": "default",
"content": {
"text": "<banner text>",
"color": "<background color>", [optional - default is "#ff5886fa"]
"foreground": "<foreground color>", [optional - default is black]
"icon": "<banner icon resource name>", [optional] "duration": <how many seconds the message will be displayed before being automatically closed - 0 for unlimited time>, [optional - default is 20 seconds] "orientation": <where the banner will appear - either "top" or "bottom">, [optional - default is "bottom"]
"action": <the action the will occur when clicking the banner - use the notification payload action content> [optional] },
"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",
    "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 delivery” 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",
    "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.
     List<String> values = new ArrayList<String>(1);
    values.add("pizzaready");
    InAppManager.show(getApplicationContext(), InAppStorage.KeyName.RULE, values, getSupportFragmentManager(), inAppFragmentId);
  5. In your app on the offer page, call code to show in-app messages that use the “offer” rule.
     List<String> values = new ArrayList<String>(1);
    values.add("offer");
    InAppManager.show(getApplicationContext(), InAppStorage.KeyName.RULE, values, getSupportFragmentManager(), inAppFragmentId);
  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.
     List<String> values = new ArrayList<String>(1);
    values.add("all");
    InAppManager.show(getApplicationContext(), InAppStorage.KeyName.RULE, values, getSupportFragmentManager(), inAppFragmentId);

Note: The “all” rule matches both the offers and pizza-ready notices because you add the “all” rule to both message. 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

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 more information about mobile app messages, 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 *