DocumentationDeveloper PortalAPI EndpointsProduct Updates
Developer Portal
Contact Us

Set up mobile inbox

This article provides steps for setting up the mobile inbox for in-app messages in your Android app.

Suggest Edits

A mobile inbox contains the in-app messages that are directly delivered to the inbox in a non-intrusive way or displayed in the app and delivered to the inbox. Users will see the messages in their inbox until the message expires or until they delete them after reading them.

Blueshift’s SDK automatically syncs the mobile inbox, along with the message status (read/unread), across all the devices on which a user has installed your app and has logged in.

The SDK provides a default user interface for the mobile inbox. You can customize the UI to match your brand style and colors.

Your app must use Blueshift’s Android SDK version 3.4.0 and above to save in-app messages to the inbox.

For more information about sending in-app messages to the mobile inbox, see the In-app Studio documentation.

Prerequisites

To ensure the proper functioning of the inbox and retrieval of the correct messages, you must complete the following prerequisites.

Set user information

You must set the email ID or the customer ID or both at the time of login to Blueshift SDK. These user identifiers help the SDK to fetch messages from the server and show them in the Inbox after a customer logs in. If you don't set this customer information to the SDK, then showing existing inbox messages might fail for new app installs.

On logging out, ensure that you remove the saved user information, so that you can set new user information on the next log-in.

For more information, see Set user information.

Set Device ID source and reset device ID

We recommend that you use the device id source “GUID” during the SDK initialization. This device ID type supports device ID reset functionality.

We recommend resetting the device ID when the user logs out from the app. This forces the SDK to create a new device ID which will be used for the activity after logging out and the subsequent login activity, if any. Resetting the device ID ensures that the inbox history is maintained properly per device.

For more information, see Reset GUID.

Enable the mobile inbox in your app

To use the mobile inbox feature, you must first enable it in the SDK configuration during initialization.

val config = Configuration()
config.apply {
   apiKey = BuildConfig.API_KEY
   isInboxEnabled = true
}
Blueshift.getInstance(this).initialize(config)

Configuration configuration = new Configuration();
configuration.setApiKey(BuildConfig.API_KEY);
configuration.setInboxEnabled(true);
Blueshift.getInstance(this).initialize(configuration);

📘

Note

In-app messages are automatically enabled when you enable the mobile inbox.

Display the mobile inbox in your app

📘

Note

We recommend that you show the inbox only in the logged-in mode and not in the guest mode.

The mobile inbox can be displayed in the following two ways:

Using BlueshiftInboxActivity

startActivity(Intent(context, BlueshiftInboxActivity::class.java))

startActivity(Intent(context, BlueshiftInboxActivity.class));

Using BlueshiftInboxFragment

When using a Navigation component, add the BlueshiftInboxFragment to the navigation graph XML:

<androidx.fragment.app.FragmentContainerView  
   android:id="@+id/inboxFragment"  
   android:name="com.blueshift.inbox.BlueshiftInboxFragment"  
   android:layout_width="match_parent"  
   android:layout_height="match_parent" />

When using fragment instance in code, use the following code:

val fragment = BlueshiftInboxFragment.newInstance()  
supportFragmentManager  
   .beginTransaction()  
   .replace(R.id.fragmentContainerView, fragment)  
   .commit()

BlueshiftInboxFragment fragment = BlueshiftInboxFragment.newInstance();
getSupportFragmentManager()
        .beginTransaction()
        .replace(R.id.fragmentContainerView, fragment)
        .commit();

Get unread message count

The SDK provides a function that you can use to get the count of unread messages in the inbox. You can then display this count on the badge.

BlueshiftInboxManager.getUnreadMessagesCount(this) {
   updateInboxCountUi(it)
}

BlueshiftInboxManager.getUnreadMessagesCount(this, integer -> {
   updateInboxCountUi(integer);
});

Blueshift's SDK broadcasts a notification when the unread messages count changes. The unread message count changes when:

  • A new unread message is received.
  • A message is read by the user.
  • A message is deleted by the user or by the SDK (when the SDK syncs the messages with the server).

To register for these broadcasts, use the following helper method (if you want to use context-based receivers).

BlueshiftInboxManager.registerForInboxBroadcasts(this, object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        // inbox data has changed, please make the UI updates
    }
})

BlueshiftInboxManager.registerForInboxBroadcasts(this, new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
         // inbox data has changed, please make the UI updates
    }
});

Handle deep links

When the user clicks any of the links in an in-app notification displayed in the inbox, the app takes the user to the page mapped to the link.

For more information about how to integrate Blueshift's deep links for Android (called Android App Links), see Integrate Blueshift deep links on Android.

📘

Note

The basic configuration for the mobile inbox is now completed. Using this basic configuration, you will be able to see the inbox screen and see the messages inside it, if any were received.

Customize the mobile inbox

You can customize the user interface of the mobile inbox to match your app design.

Modify cell layout, colors, and font

You can modify the font, color, and layout of the inbox list cells to match the design of your app.

To modify the look of the inbox, complete the following steps:

  1. Copy the bsft_inbox_list_item.xml layout file from android-sdk and rename the file. For example, custom_inbox_item.xml.
  2. In the new file, change the layout, colors, and font as required.

Use the following code when using Activity:

val intent = Intent(context, BlueshiftInboxActivity::class.java)  
intent.putExtra(BlueshiftConstants.INBOX_LIST_ITEM_LAYOUT, R.layout.custom_inbox_item)
startActivity(intent)

Intent intent = new Intent(this, BlueshiftInboxActivity.class);
intent.putExtra(BlueshiftConstants.INBOX_LIST_ITEM_LAYOUT, R.layout.custom_inbox_item);
startActivity(intent);

Use the following code when using Fragment:

class InboxWithCustomLayout : BlueshiftInboxFragment() {  
	override fun onCreate(savedInstanceState: Bundle?) {  
		super.onCreate(savedInstanceState)
				
		setInboxListItemLayout(R.layout.custom_inbox_item)
  }
}  

public class InboxWithCustomLayout extends BlueshiftInboxFragment {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setInboxListItemLayout(R.layout.custom_inbox_item);
    }
}

Set date format and visibility

Create a subclass for BlueshiftInboxFragment and set a date mapper using the method setInboxDateFormatter in onCreate to change the date format for the message or to hide the date. The date mapper takes a Date object and returns a string.

class InboxWithCustomDateFormat : BlueshiftInboxFragment() {
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       setInboxDateFormatter { date ->
           SimpleDateFormat("dd MMMM yyyy - hh:mm aa", Locale.getDefault()).format(date)
       }
   }
}

public class InboxWithCustomDateFormat extends BlueshiftInboxFragment {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setInboxDateFormatter(date -> new SimpleDateFormat("dd MMM yyyy - hh:mm aa", Locale.getDefault()).format(date));
    }
}

Filter messages

To decide which messages are displayed in the mobile inbox, create a subclass for BlueshiftInboxFragment and call setInboxFilter in the onCreate method. The filter takes a BlueshiftInboxMessage and returns a boolean.

  • Return true to display the message.
  • Return false if the message should not be displayed.

The following example shows how a filter can be used to show only unread in-app messages inside the inbox:

class InboxWithCustomFilter : BlueshiftInboxFragment() {
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       setInboxFilter { message ->
           message.status == BlueshiftInboxMessage.Status.UNREAD
       }
   }
}

class InboxWithCustomFilter : BlueshiftInboxFragment() , BlueshiftInboxFilter{
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)


       setInboxFilter(this)
   }


   override fun filter(message: BlueshiftInboxMessage?): Boolean {
       return message?.status == BlueshiftInboxMessage.Status.UNREAD
   }
}

public class InboxWithCustomFilter extends BlueshiftInboxFragment {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setInboxFilter(message -> message.status == BlueshiftInboxMessage.Status.UNREAD);
    }
}

Sort messages in the inbox

By default, the messages in the mobile inbox are sorted in descending order based on the date, with the newest message at the top. You can also sort messages in other ways. For example, in ascending order based on the message title or based on the read status of the message to show unread messages on the top.

To sort the messages in the mobile inbox, create a subclass for BlueshiftInboxFragment and set a comparator in onCreate. BlueshiftInboxComparator is a standard Java Comparator interface.

  • Return a negative integer when the first message is less than the second.
  • Return a zero when the first message is equal to the second.
  • Return a positive integer when the first message is greater than the second.

The following example shows how to sort messages to show unread messages at the top followed by read messages:

class InboxWithCustomSorting : BlueshiftInboxFragment() {
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       setInboxComparator { message1, message2 ->
           message2.status.compareTo(message1.status)
       }
   }
}

class InboxWithCustomSorting : BlueshiftInboxFragment(), BlueshiftInboxComparator {
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)


       setInboxComparator(this)
   }


   override fun compare(message1: BlueshiftInboxMessage?, message2: BlueshiftInboxMessage?): Int {
       return message2?.status?.compareTo(message1?.status)!!
   }
}

public class InboxWithCustomSorting extends BlueshiftInboxFragment {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setInboxComparator((message1, message2) -> message2.status.compareTo(message1.status));
    }
}

Unread badge color

You can change the default color of the unread indicator for a message in the inbox based on your app theme.

Use the following code when using Activity:

val color = ContextCompat.getColor(context, R.color.custom_color)
val intent = Intent(context, BlueshiftInboxActivity::class.java)
intent.putExtra(BlueshiftConstants.INBOX_UNREAD_INDICATOR_COLOR, color)
startActivity(intent)

int color = ContextCompat.getColor(context, R.color.custom_color);
Intent intent = Intent(context, BlueshiftInboxActivity.class);
intent.putExtra(BlueshiftConstants.INBOX_UNREAD_INDICATOR_COLOR, color);
startActivity(intent);

Use the following code when using Fragment:

class InboxWithCustomUnreadIndicatorColor : BlueshiftInboxFragment() {
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       val color = ContextCompat.getColor(context, R.color.custom_color)
       setInboxUnreadIndicatorColor(color)
   }
}

public class InboxWithCustomUnreadIndicatorColor extends BlueshiftInboxFragment {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        int color = ContextCompat.getColor(getContext(), R.color.custom_color);
        setInboxUnreadIndicatorColor(color);
    }
}

Refresh indicator color

By default, the SDK adds the pull to refresh to sync messages on the SDK’s Inbox screen. You can change the refresh indicator color based on your app theme.

Use the following code when using Activity:

val colors = intArrayOf(Color.RED, Color.CYAN, Color.BLUE)
val intent = Intent(context, BlueshiftInboxActivity::class.java)
intent.putExtra(BlueshiftConstants.INBOX_REFRESH_INDICATOR_COLORS, colors)
startActivity(intent)

int[] colors = new int[]{Color.RED, Color.CYAN, Color.BLUE};
Intent intent = Intent(context, BlueshiftInboxActivity.class);
intent.putExtra(BlueshiftConstants.INBOX_REFRESH_INDICATOR_COLORS, colors);
startActivity(intent);

Use the following code when using Fragment:

class InboxWithCustomRefreshIndicatorColors : BlueshiftInboxFragment() {
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       setInboxRefreshIndicatorColors(Color.RED, Color.CYAN, Color.BLUE)
   }
}

public class InboxWithCustomRefreshIndicatorColors extends BlueshiftInboxFragment {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setInboxRefreshIndicatorColors(Color.RED, Color.CYAN, Color.BLUE);
    }
}

No messages text

You can set a custom message that will be displayed in the mobile inbox when it is empty. By default, no message is displayed for an empty inbox. Setting this text can help your users to understand the purpose of the mobile inbox.

The message text can wrap into multiple lines as required.

To add the custom text when using the mobile inbox fragment, use the following code:

Use the following code when using Activity:

val intent = Intent(context, BlueshiftInboxActivity::class.java)
intent.putExtra(BlueshiftConstants.INBOX_EMPTY_MESSAGE, "The inbox is empty")
startActivity(intent)

Intent intent = new Intent(context, BlueshiftInboxActivity.class);
intent.putExtra(BlueshiftConstants.INBOX_EMPTY_MESSAGE, "The inbox is empty");
startActivity(intent);

Use the following code when using Fragment:

class InboxWithCustomMessageForEmptyInbox : BlueshiftInboxFragment() {
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       setInboxEmptyMessage("The inbox is empty")
   }
}

public class Fragment extends BlueshiftInboxFragment {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setInboxEmptyMessage("The inbox is empty");
    }
}

Set navigation title

When you launch the mobile inbox as an activity, you can change the title by passing an INBOX_ACTIVITY_TITLE argument in the intent.

📘

Note

The navigation title is displayed only if the app has support for ActionBar.

val intent = Intent(context, BlueshiftInboxActivity::class.java)
intent.putExtra(
   BlueshiftConstants.INBOX_ACTIVITY_TITLE,
   "Mobile Inbox"
)
startActivity(intent)

Intent intent = new Intent(context, BlueshiftInboxActivity.class);
intent.putExtra(BlueshiftConstants.INBOX_ACTIVITY_TITLE, "Mobile Inbox");
startActivity(intent);

Updated over 1 year ago