Overview

Skill Level: Intermediate

Inbox notifications are messages that get pulled by the app when the inbox 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 SDK 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.

Prerequisites

To get started, you need:

  • The Android inbox plug-in zip file or aar file that contains inbox plug-in files
    Starting in Release 3.6.5.0 of the IBM Mobile App Messaging Android SDK, plug-in files are delivered in aar as well as zip file formats. If you are using zip files to implement inbox plug-ins, follow Step 1 through Step 8 in this tutorial.

    If you are using the aar files to implement inbox plug-ins, add the aar files to your project and to the build.gradle file, and then follow steps Step 6 through Step 8. You can find the aar plug-in files in ibm-mobile-push-android-sdk-3.6.5.0/plugins.

  • Android 4.4 and higher (API level 19)

Server limits on inbox sync API calls

The server limits the frequency of inbox sync API calls. This limit can vary per customer. For the exact value for your organization, contact IBM Support.

SDK limits on inbox sync API calls

  • The inbox sync rules are enforced by the server. Additional limits are enforced on inbox sync API calls by the SDK. If you use the inbox sync API to sync inbox messages, the minimum interval between calls is 5 minutes for a regular sync. For example, if you use the SDK API to sync inbox messages every time the mobile user opens the inbox, the SDK allows only one call to the server every 5 minutes, regardless of the number of times the API is called.
  • If you call the inbox sync too often, the SDK returns the following error:

    SYNC_TOO_SOON_STATUS_CODE

  • There are no limits for notifications with an openInboxMessage action that contains a message that is not in the SDK database.

For information about other mobile app messages features in iOS apps, see the Documentation.

Step-by-step

  1. Extract the contents of Android inbox plug-in zip file from the plugins folder.

    The ibm-mobile-push-android-sdk-plugin-inbox-<version number >.zip contains the following files and sources:

    • ibm-mobile-push-android-sdk-plugin-displayweb-<version number>.jar under the bin directory
    • inbox.json under assets/mce/plugins
    • Plug-in sources under the src folder
    • Plug-in Javadoc under the docs folder
    • Plug-in resources under the res folder

     

    Note: Starting in Release 3.6.5.0 of the IBM Mobile App Messaging Android SDK, plug-in files are delivered in the aar as well as zip file formats. You can find the aar plug-in files in ibm-mobile-push-android-sdk-3.6.5.0/plugins.

  2. Copy inbox.json, located under assets/mce/plugins, to your project assets directory.

    It is under the same path: mce/plugins.

  3. Copy resources to your project.

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

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

    Add the add_message, delete_message, set_message_unread, next_message, and prev_message strings from the res/values/strings.xml file.

  5. Add Android Inbox plug-in jar file to your project as an Android library.

    Add ibm-mobile-push-android-sdk-plugin-inbox-<version number>.jar to your project as an Android library.

    The ibm-mobile-push-android-sdk-plugin-inbox-<version number>.jar file is located in the plugins folder in the SDK package.

  6. Add the inbox activities to AndroidManifest.xml:

    Add the following code to AndroidManifest.xml:

    <activity
    android:name="com.ibm.mce.sdk.plugin.inbox.RichInboxActivity" android:configChanges="orientation" >
    </activity>

    <activity
    android:name="com.ibm.mce.sdk.plugin.inbox.InboxMessageDisplayActivity" android:configChanges="orientation" >
    </activity>
  7. Add the inbox service to AndroidManifest.xml:

    Add the following code to AndroidManifest.xml.

    <service android:name="com.ibm.mce.sdk.plugin.inbox.InboxUpdateService" />
  8. You can remove expired messages from the inbox or restrict expired messages from being displayed.

    To control expired messages, go to MainSampleMenuActivity.java in the Android sample app and after

    else if (position == INBOX_INDEX) {

     

    and before

    InboxMessagesClient.showInbox(getApplicationContext()); 

     

    add the following code:

    List expiredMessages = new LinkedList();
    RichContentDatabaseHelper.MessageCursor cursor = RichContentDatabaseHelper.getRichContentDatabaseHelper(getApplicationContext()).getMessages();
    Date now = new Date(System.currentTimeMillis());
    while (cursor.moveToNext()) {
    RichContent rc = cursor.getRichContent();
    if(rc.getExpirationDate().before(now)) {
    expiredMessages.add(rc);
    }
    }
    for(RichContent expiredMessage : expiredMessages) {
    InboxMessagesClient.deleteMessage(getApplicationContext(), expiredMessage);
    }
    InboxMessagesClient.showInbox(getApplicationContext());
    
    
    

     

     

  9. (Optional) Specify inbox messages that you want displayed.

    You can specify which inbox messages that you want to display by implementing the InboxPlugin.InboxControl interface. By default, all messages are displayed.

    Register the interface. For example,

    InboxPlugin.setInboxControl(new InboxPlugin.InboxControl() {
        @Override
        public boolean shouldDisplayInboxMessage(RichContent richContent) {
            // add code here to check if inbox message (richContent) should be displayed;
            return true; // answer true if you want the message to appear in the inbox, false if it should not appear
        }
    });
  10. (Optional) Sort inbox messages.

    You can sort inbox messages by using the following method in the InboxControl API.

    public boolean isMessagesSortAscending()

    Messages are displayed in either ascending or descending order. If the method returns true, inbox messages are returned in ascending order, where the oldest message is displayed first. If the method returns false, the inbox messages are returned in descending order, where the the newest message is displayed first. The default is true.

    Update the inbox sample code, as shown:

    import com.ibm.mce.sdk.plugin.inbox.InboxPlugin; 
    
    @Override
        public void onCreate() {
            super.onCreate();
            InboxPlugin.InboxControl inboxControl = new InboxPlugin.InboxControl() { 
                @Override 
                public boolean shouldDisplayInboxMessage(RichContent richContent) { 
                    // check the rich content and decide whether to display it in the inbox (return true) or not (return false)
                    return true; 
                } 
    
                @Override 
                public boolean isMessagesSortAscending() { 
                    // decide if you want inbox messages sort to be oldest first (return true) or newest first (return false)
                    return false; 
                } 
            }; 
            InboxPlugin.setInboxControl(inboxControl); 
    

     

Expected outcome

For information about other types of mobile app messages, see the Documentation.

Go Back to the Mobile App Messaging home page.

4 comments on"Implementing inbox notifications in your Android app"

  1. Cristhopper Armenta May 03, 2017

    Is it possible to get the tutorial for version 3.6.4.0? That’s the version that my project has currently and I don’t know if it’s possible to upgrade to the version on this tutorial.

    • JoanGriffin May 04, 2017

      References to 3.6.5.0 are only for the the aar files. You should be able to use “Implement inbox notifications in your Android app” for 3.6.4.0.

  2. JoanGriffin May 11, 2017

    Hello

  3. […] Added shouldDisplayInboxMessage to match iOS implementation. developer.ibm.com/customer-engagement/tutorials/implementing-inbox-notifications-in-your-android-app… […]

Join The Discussion

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