In-app content

Overview

In-app messages are sent to the users from Acoustic’s web service and are synced down to the device. In-app messages get pushed to an app but are only displayed when a specific event occurs. For instance, you might have in-app messages that target product pages in the app, when a user adds an item to a cart, or that come up when the app is first opened.

They 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.

The messages can be personalized and are rendered on the device at appropriate places in your application flow. The In-app message content is customized by templates. Messages can have various visual styles based on the template used and how the app handles that template.

In-app templates

The SDK includes four templates in the plugin.

  • 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 text message, an optional left icon (note, notification, store, offer, comment), and an optional background image.
  • 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.
  • 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.
  • 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.
  • MiniTemplate 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 and a selectable left icon (note, notification, store, offer, comment). Unlike iOS, the Android inapp plugin does not currently support the background image option.
  • BaseInAppTemplate is the base class for the MiniTemplate, ImageTemplate and VideoTemplate templates. If you want to use any of these templates, you must include all of the files from Plugin/InApp/* in the SDK zip; however, you do not have to register this template with the template registry, as it cannot be used independently.
  • ImageTemplate 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.
  • VideoTemplate 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.

In-app banner template

The banner 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:


{ "rules": [ "rules", "to", "trigger", "on" ], "maxViews": 5, "template": "default", "content": { "orientation": "top", "action": { "type": "url", "value": "https://acoustic.com" }, "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" }

{ "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 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", }

In-app image template

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:


{ "aps": { "content-available": 1 }, "inApp": { "rules": [ "all", "image" ], "maxViews": 5, "template": "image", "content": { "image": "https://picsum.photos/400/300.jpg", "action": { "value": "https://acoustic.com", "type": "url" }, "title": "Test iOS Style Title", "text": "Test iOS Style Body", "duration": 10 }, "triggerDate": "2019-06-03T13:21:58Z", "expirationDate": "2020-12-03T13:21:58Z" } }

{ "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 video template

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:


{ "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": "https://acoustic.com", "type": "url" }, "title": "Test iOS Style Title", "text": "Test iOS Style Body", }, "triggerDate": "2019-06-03T13:21:58Z", "expirationDate": "2020-12-03T13:21:58Z" } }

{ "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" }

Install the in-app plugin

  1. 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 in the application:didfinishlaunchingwithoptions: method of your app delegate.
    
    
    @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [MCEInAppVideoTemplate registerTemplate]; [MCEInAppImageTemplate registerTemplate]; [MCEInAppBannerTemplate registerTemplate]; // rest of method } @end
    class AppDelegate: NSObject, NSApplicationDelegate { func applicationDidFinishLaunching(_ aNotification: Notification) { // MCE InApp Templates Plugins MCEInAppVideoTemplate.register() MCEInAppImageTemplate.register() MCEInAppBannerTemplate.register() // rest of method } }
  3. Pull pending in-app messages to the device using the following command.
    
    
    [MCEInboxQueueManager.sharedInstance syncInbox];
    
    
    MCEInboxQueueManager.shared.syncInbox()
  4. Set a specified event call. When a specified event occurs, call the MCEInAppManager executeRule: method.
    
    
    [[MCEInAppManager sharedInstance] executeRule:@[@"launch"]];
    
    
    MCEInAppManager.shared.executeRule(["launch"])
  1. Extract the contents of mobile-push-android-sdk-plugin-inapp-<version number>.zip from the plugins folder.
  2. Copy the acoustic-mobile-push-android-sdk-plugin-inapp-<version number>.aar file and add it to your project's lib directory.
  3. Copy the resources that are located under source/main/(all layout folders), res/menu, and drawable (all the drawable folders) to your project.
  4. Copy the plugin-inapp.json file from source/main/assets/mce.plugins into assets/mce.plugins in your project.
  5. Add strings from the source/main/res/values/strings.xml file to your project strings.xml file.
  6. Pull pending in-app messages to the device using the following command.
    
    
    MessageSync.syncMessages(getApplicationContext(), new OperationCallback<MessageSync.SyncReport>() { @Override public void onSuccess(MessageSync.SyncReport syncReport, OperationResult result) { // sync successful code here } @Override public void onFailure(final MessageSync.SyncReport syncReport, final OperationResult result) { // sync failure code here }
  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. Send an in-app message by adding the following code 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> }
  1. Install the plugin
    
    
    npm install <sdk folder>/plugins/react-native-acoustic-mobile-push-inapp
  2. Link the plugin
    
    
    react-native link react-native-acoustic-mobile-push-inapp
  3. Copy files in <sdk folder>/plugins/react-native-acoustic-mobile-push-inapp/javascript into your project.
  4. Import the templates in your App.js
    
    
    import {InAppBanner} from './in-app/in-app-banner'; import {inAppMedia} from './in-app/in-app-media';
  5. Place executeInApp calls on appropriate pages of your application or in response to user actions.
  1. Copy files in the directories in the in-app folder to your project.
  2. Add the default in-app template stylesheet to the page. This includes support for additional plug-ins, such as videos and images.
    
    
    <link rel="stylesheet" type="text/css" href="css/inapp_media.css" /> <link rel="stylesheet" type="text/css" href="css/inapp_banner.css" /> <link rel="stylesheet" type="text/css" href="css/inapp_image.css" /> <link rel="stylesheet" type="text/css" href="css/inapp_video.css" />

    📘

    Note:

    You must have, at a minimum, version 4.2.0 of Apache Cordova to include videos in your in-app messages.

  3. Run in-app rules in the appropriate points in your application.
    
    
    MCEInAppPlugin.executeInAppRule(['test']);

Implement in-app message banners

  1. Add {package}/plugins/InApp Plugins/Banner InApp Template/BannerInAppTemplate.cs to the Forms project in Xamarin.
  2. Add SDK.Instance.RegisterInAppTemplate ("default", new BannerInAppTemplate ()) to the project's App Constructor.
  3. Add the cancel.png by following these steps.
    1. Add {package}/plugins/InApp Plugins/Banner InApp Template/cancel.png to the Android project's resources/drawable directory.
    2. Create cancel.imageset in the iOS projects's Resources/Images.xcassets folder.
    3. Add {package}/plugins/InApp Plugins/Banner InApp Template/[email protected] to cancel.imageset for Universal 1x image.
    4. Add {package}/plugins/InApp Plugins/Banner InApp Template/[email protected] to cancel.imageset for Universal 2x image.
    5. Add {package}/plugins/InApp Plugins/Banner InApp Template/[email protected] to cancel.imageset for Universal 3x image.

    Similarly, add the comment.png, note.png, notification.png, offer.png, and store.png to the project.

Implement in-app media

  1. Add {package}/plugins/InApp Plugins/Media InApp Template/MediaInAppTemplate.cs to the Forms project in Xamarin.
  2. Add SDK.Instance.RegisterInAppTemplate ("image", new ImageInAppTemplate ()) to the project's App Constructor.
  3. Add the dismiss.png by following these steps.
    1. Add {package}/plugins/InApp Plugins/Media InApp Template/dismiss.png to the Android's project's Resources/drawable directory.
    2. Create dismiss.imageset in iOS project's Resources/Images.xcassets folder.
    3. Add {package}/plugins/InApp Plugins/Media InApp Template/[email protected] to dismiss.imageset for Universal 1x image.
    4. Add {package}/plugins/InApp Plugins/Media InApp Template/[email protected] to dismiss.imageset for Universal 2x image.
    5. Add {package}/plugins/InApp Plugins/Media InApp Template/[email protected] to dismiss.imageset for Universal 3x image.

    Similarly, add the handle.png to the project.

Implement images in your in-app messages

  1. Add {package}/plugins/InApp Plugins/Media InApp Template/ImageInAppTemplate.cs to the Forms project in Xamarin.
  2. Set up the Media InApp Template.

Implement in-app videos in your in-app messages

  1. Add {package}/plugins/InApp Plugins/Media InApp Template/VideoInAppTemplate.cs to the Forms project in Xamarin.
  2. Add SDK.Instance.RegisterInAppTemplate ("video", new VideoInAppTemplate ()) to the project's App Constructor.
  3. Set up the Media InApp Template.
  4. Set up VideoPlayer.

Add node property if sending video in in-app messages

If you plan on sending video in inapp messages, you will also need to add the <application> node property android:usesCleartextTraffic with the value of "true" in your AndroidManifest.xml file of your Android subproject. For example:


<application android:label="Sample" android:name="co.acoustic.mobile.push.sdk.api.MceApplication" android:usesCleartextTraffic="true">

Flutter SDK retrieves the in-app data sent from Campaign and the simulation for canned in-app and sends them to the same list. The in-app data is then presented in the order they were sent and received.

  1. Install the flutter_acoustic_mobile_push_inapp plug-in through your project's pubspec.yaml file.
flutter_acoustic_mobile_push_inapp: path: ../../plugins/flutter_acoustic_mobile_push_inapp

📘

Note:

Depending on the dev tools you use in your environment, you may need to explicitly run pub get to pull the plug-in into the project. If you use VScode, the pub get command automatically runs when you save the pubspec.yaml file.

  1. Add the necessary imports:
import 'package:flutter/material.dart'; import 'dart:async'; import 'package:flutter_acoustic_mobile_push_inapp/flutter_acoustic_mobile_push_inapp.dart'; import 'package:flutter_acoustic_mobile_push_inapp/flutter_in_app_pay_load.dart'
  1. Create the following variables.
var inApp = InAppMessageValue();

The following variable stores the data pulled from the SDK:

var _templatesInAppData;
  1. Run the data pull and data updates upon page entry. The inApp.getInAppList() function provides the sync necessary to pull the data.
@override void initState() { super.initState(); inApp.getInAppList(); getUpdatedInAppMesssageList(); }

Display an in-app message using rules

You can display a banner app based on a specific rule assigned to that in-app message when it was created.

In the following example, we'll use offer, pizza ready, and all rules.
We'll also assume that both the offer and pizza-ready in-app messages will have the all rule. Therefore, you'll have in-app messages with the rule all, pizzaready and all, offer.

To display the oldest in-app message, call messages with the rule all
When you specify all, the oldest in-app message is displayed.

Future<void> getInAppMessages(List<String> rules) async { for (String ruleName in rules) { inApp.getInAppMessage([ruleName]); } } getInAppMessages(["all"]);

If there are ten in-app messages on the device that can be displayed when you use the rule all, the API call returns only the oldest in-app message with the rule all present.

For example, if a message was sent yesterday and a message is sent today with the rule all are on the device, the API call returns the oldest message - the message sent yesterday.

To display an offer in-app message, call the message with the offer rule:

inApp.getInAppMessages(["offer"]);

To display pizza ready in-app message, call the message with the pizzaready rule

inApp.getInAppMessages(["pizzaready"]);

For more information, see

Target 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": "https://acoustic.com"
            },
            "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": "2020-09-07T00:00:00.000+00:00",
        "maxViews": 5,
        "rules": [
            "offer",
            "all"
        ],
        "template": "default"
    }
}
  1. 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": "https://acoustic.com"
            },
            "color": "#0aff00",
            "icon": "note",
            "orientation": "top",
            "mainImage": "https://picsum.photos/300/200.jpg",
            "text": "Your pizza went out for delivery at %%deliverytime%%",
        },
        "expirationDate": "2020-02-07T20:36:03.995+00:00",
        "maxViews": 1,
        "rules": [
            "pizzaready",
            "all"
        ],
        "template": "default"
    }
}
  1. In your app on the pizza status page, call code to show in-app messages that use the pizzaready rule.

[[MCEInAppManager sharedInstance] executeRule:@[@"pizzaready"]];

MCEInAppManager.shared.executeRule(["pizzaready"])

List<String> values = new ArrayList<String>(1); values.add("pizzaready"); InAppManager.show(getApplicationContext(), InAppStorage.KeyName.RULE, values, getSupportFragmentManager(), inAppFragmentId);
  1. In your app on the offer page, call code to show in-app messages that use the "offer" rule.

[[MCEInAppManager sharedInstance] executeRule:@[@"offer"]];

MCEInAppManager.shared.executeRule(["offer"])

List<String> values = new ArrayList<String>(1); values.add("offer"); InAppManager.show(getApplicationContext(), InAppStorage.KeyName.RULE, values, getSupportFragmentManager(), inAppFragmentId);
  1. 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"]];

MCEInAppManager.shared.executeRule(["all"])

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 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.

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.