Inbox notifications are messages that get pulled by the app when the app is opened. A full-page message is displayed in the app, and it can also include an inbox display, which can be customized based on a template. An inbox message is similar to an email. Messages are stored in cloud storage, and the library syncs this message to local storage, which is similar to an email sync. Tapping an item in the inbox opens the corresponding full inbox message.

Getting started

The inbox plugin is enabled in the Campaign library by default. For details, see Add notification action plugins to a Cordova project.

Here is how to start using the plugin:

1. Run the following code in the command line to copy the JavaScript and CSS to the project and allow the JavaScript to be auto included in the project:

cordova plugin add <path to download directory>/plugins/co.acoustic.mobile.push.plugin.inbox
cordova prepare

2. Add the global inbox stylesheet to the page.

<link rel="stylesheet" type="text/css" href="css/inbox.css" />

3. Add the template stylesheet to the page.

<link rel="stylesheet" type="text/css" href="css/inbox_default.css" />

<link rel="stylesheet" type="text/css" href="css/inbox_post.css" />

4. Add inbox list

<div id='inboxMessages' class="ui-body"></div>
<div data-role="header">
  <a href="#sample" data-direction="reverse" data-transition="slide">Sample</a>
  <h1>Inbox</h1>
  <a id="refresh_button">
    <img width='22' height='22' src="images/inbox/refresh.png">
  </a>
</div>
</div>

5. Add the inbox message to the page.

<div data-role="page" id="inboxMessage">
  <div id='inboxMessageContent' class="ui-body"></div>
  <div data-role="header">
    <div id='buttons'>
      <a id="delete_button">
        <img width='22' height='22' src="images/inbox/trash.png">
      </a>
      <a id="down_button">
        <img width='22' height='11' src="images/inbox/chevron-down.png">
      </a>
      <a id="up_button">
        <img width='22' height='11' src="images/inbox/chevron-up.png">
      </a>
    </div>
    <a href="#inbox" data-direction="reverse" data-transition="slide">Inbox</a>
    <h1></h1>
  </div>
</div>

Customizing inbox notifications

Managing expired messages

By default, the Campaign library does not remove expired messages. This means you will see expired messages until 30 days after the expire date, then they will automatically be purged by the server. This is useful for showing something that may be missed, perhaps by dimming the message or marking it as "expired". Under other circumstances, though, you may want to delete all expired messages and prevent them from being presented at all. Cordova does not have a clear expired messages method exposed to javascript developers, however this method can be added, if desired. If you do not wish to show expired messages, modify the code in MCEInbox.js in the MCEInboxPlugin.setInboxMessagesUpdateCallback method.

Customizing the look and feel of the inbox notifications UI

The inbox that Acoustic Campaign ships is configurable so that you can have it display the way you want it. For example, if all of your other UI has a font of Times Roman with a foreground color of white and a background color of red, you may want your inbox messages to show up in the list with similar styling.

• Default Template: Edit the inbox_default.css file to match the desired style using Cascading Style Sheets.
• Post Template: Edit the inbox_post.css file to match the desired style using Cascading Style Sheets.

Displaying a background image

• Default Template: Edit the inbox_default.css file to match the desired style using Cascading Style Sheets.
• Post Template: Edit the inbox_post.css file to match the desired style using Cascading Style Sheets.

Sorting inbox messages

Other than by default, you may want to sort the inbox in a different order. For instance, you might want to sort using a custom field rather than by sendDate.

The simplest way to change the sort order would be to use the standard array sort function.

allMessages.sort(function (a, b) {
    return a.content.customKey - b.content.customKey;
});

Customizing behavior

To take different behaviors based on the kinds of inbox messages received (e.g., play a sound when special offers are opened but not regular messages), you can override onCreate of InboxMessageDisplayActivity.

exports.openInboxMessage = function(inboxMessage) {
        if (inboxMessage.content.sound) {
            var name = inboxMessage.content.sound;
            var audio = new Audio(name);
            audio.play();
        }

Adding a custom field

The inbox can have custom fields associated with each message. You can use these fields to include information that is useful to your app but not presented in the inbox itself.

Any custom fields will simply show up in the content key of the InboxMessage object. All fields, subject, body, preview etc., are "custom" fields. For instance, the subject field is contained within an embedded object in the InboxMessage's content dictionary.

inboxMessage['content']['messagePreview']['subject']

The HTML content itself is within a separate embedded object within the content object.

inboxMessage['content']['messageDetails']["richContent"]

But you can put the custom data anywhere you like, even in the root of the content object.

inboxMessage['content']['foo']

Methods

(static) clearExpiredMessages()

Allows Cordova Inbox Plugin to immediately remove expired messages from the inbox database

(static) deleteMessageId(inboxMessageId)

Allows Cordova Inbox Plugin to delete a message from the database cache and server.

(static) executeInboxAction(action)

Allows Cordova Inbox Plugin to call out to action registry to handle rich message actions.

(static) fetchInboxMessageId(inboxMessageId, callback)

Allows Cordova Inbox Plugin to get the inbox message by providing the inbox message ID.

(static) fetchInboxMessageViaRichContentId(richContentId, callback)

Allows Cordova Inbox Plugin to retrieve an inbox message by providing a richContentId.

(static) readMessageId(inboxMessageId)

Allows Cordova Inbox Plugin to set the read status of a message in the database cache and server.

(static) setInboxMessagesUpdateCallback(callback)

Allow Cordova Inbox Plugin to respond to changes in the inbox list.

(static) syncInboxMessages()

Allows Cordova Inbox Plugin to initiate a sync with the server. Will execute function registered with setInboxMessagesUpdateCallback when complete.

Type Definitions

inboxListCallback(messages)

InboxMessage

inboxMessageCallback(messages)