Mobile inbox (Android)

This guide explains how to set up and customize the mobile inbox for in-app messages in your Android app.

Prerequisites

Before setting up the mobile inbox, ensure you have completed:

Your app must use Blueshift's Android SDK version 3.4.0 or above.

Set user information

Set the email ID or customer ID (or both) when the user logs in. This helps the SDK fetch and display the correct inbox messages.

Add this where you handle user login in your app (e.g., after successful sign-in):

import com.blueshift.model.UserInfo

val userInfo = UserInfo.getInstance(this)
userInfo.setEmail("[email protected]")
userInfo.setRetailerCustomerId("customer123")
userInfo.save(this)

import com.blueshift.model.UserInfo;

UserInfo userInfo = UserInfo.getInstance(this);
userInfo.setEmail("[email protected]");
userInfo.setRetailerCustomerId("customer123");
userInfo.save(this);

Add this where you handle user logout in your app:

val userInfo = UserInfo.getInstance(this)
userInfo.clear(this)

UserInfo userInfo = UserInfo.getInstance(this);
userInfo.clear(this);

Set device ID source

Use the GUID as the device ID source during SDK initialization.

In your Application class (e.g., MyApplication.kt), update your SDK initialization:

val configuration = Configuration()
configuration.setApiKey("YOUR_API_KEY")
configuration.setAppIcon(R.mipmap.ic_launcher)
configuration.setDeviceIdSource(Blueshift.DeviceIdSource.GUID)
// ... other configuration

Blueshift.getInstance(this).initialize(configuration)

Configuration configuration = new Configuration();
configuration.setApiKey("YOUR_API_KEY");
configuration.setAppIcon(R.mipmap.ic_launcher);
configuration.setDeviceIdSource(Blueshift.DeviceIdSource.GUID);
// ... other configuration

Blueshift.getInstance(this).initialize(configuration);

Reset the device ID where you handle user logout:

// Add this when user logs out
Blueshift.resetDeviceId(this)

// Add this when user logs out
Blueshift.resetDeviceId(this);

Set up mobile inbox

Enable mobile inbox

In your Application class's onCreate() method, add this line to your Configuration object:

val configuration = Configuration()
configuration.setApiKey("YOUR_API_KEY")
configuration.setAppIcon(R.mipmap.ic_launcher)
configuration.isInboxEnabled = true

Blueshift.getInstance(this).initialize(configuration)

Configuration configuration = new Configuration();
configuration.setApiKey("YOUR_API_KEY");
configuration.setAppIcon(R.mipmap.ic_launcher);
configuration.setInboxEnabled(true);

Blueshift.getInstance(this).initialize(configuration);

When you enable mobile inbox, in-app messaging is automatically enabled.

Display the mobile inbox

Show the inbox only when users are logged in, not in guest mode.

Method 1: Using BlueshiftInboxActivity

Step 1: Add a button to your layout (e.g., in activity_main.xml):

<Button
    android:id="@+id/openInboxButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Inbox" />

Step 2: In your activity (e.g., MainActivity), add this in onCreate() after setContentView():

import com.blueshift.inbox.BlueshiftInboxActivity
import android.content.Intent
import android.widget.Button

val inboxButton = findViewById<Button>(R.id.openInboxButton)
inboxButton.setOnClickListener {
    startActivity(Intent(this, BlueshiftInboxActivity::class.java))
}

import com.blueshift.inbox.BlueshiftInboxActivity;
import android.content.Intent;
import android.widget.Button;

Button inboxButton = findViewById(R.id.openInboxButton);
inboxButton.setOnClickListener(v -> {
    startActivity(new Intent(this, BlueshiftInboxActivity.class));
});

Method 2: Using BlueshiftInboxFragment

For the Navigation component, add to your 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" />

Or use the Fragment programmatically:

import com.blueshift.inbox.BlueshiftInboxFragment

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

import com.blueshift.inbox.BlueshiftInboxFragment;

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

Get unread message count

Add this where you want to display the badge count (e.g., in your main activity or navigation drawer):

import com.blueshift.inbox.BlueshiftInboxManager

BlueshiftInboxManager.getUnreadMessagesCount(this) { count ->
    // Update your UI with the count
    updateBadge(count)
}

import com.blueshift.inbox.BlueshiftInboxManager;

BlueshiftInboxManager.getUnreadMessagesCount(this, count -> {
    // Update your UI with the count
    updateBadge(count);
});

Register for inbox updates

Listen for changes to unread count (new messages, reads, deletes):

import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent

BlueshiftInboxManager.registerForInboxBroadcasts(this, object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        // Inbox data changed, update UI
        refreshInboxBadge()
    }
})

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

BlueshiftInboxManager.registerForInboxBroadcasts(this, new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        // Inbox data changed, update UI
        refreshInboxBadge();
    }
});

Handle deep links

When users tap links in inbox messages, the app navigates to the mapped page. Deep link handling for inbox messages is the same as for in-app messages.

Refer to the In-app messages deep link section for complete setup instructions.

Advanced

Customize inbox appearance

Modify cell layout, colors, and fonts

Copy bsft_inbox_list_item.xml from the SDK
Rename it (e.g., custom_inbox_item.xml)
Modify layout, colors, and fonts

Using Activity:

val intent = Intent(this, 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);

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

Create a subclass of BlueshiftInboxFragment and set a custom date formatter:

import java.text.SimpleDateFormat
import java.util.Locale

class InboxWithCustomDateFormat : BlueshiftInboxFragment() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        setInboxDateFormatter { date ->
            SimpleDateFormat("dd MMMM yyyy - hh:mm aa", Locale.getDefault()).format(date)
        }
    }
}

import java.text.SimpleDateFormat;
import java.util.Locale;

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

Show only specific messages (e.g., only unread):

import com.blueshift.inbox.BlueshiftInboxMessage

class InboxWithCustomFilter : BlueshiftInboxFragment() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        setInboxFilter { message ->
            message.status == BlueshiftInboxMessage.Status.UNREAD
        }
    }
}

import com.blueshift.inbox.BlueshiftInboxMessage;

public class InboxWithCustomFilter extends BlueshiftInboxFragment {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        setInboxFilter(message -> 
            message.status == BlueshiftInboxMessage.Status.UNREAD
        );
    }
}

Sort messages

Default sorting is newest first. Customize sorting (e.g., unread messages first):

class InboxWithCustomSorting : BlueshiftInboxFragment() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        setInboxComparator { message1, message2 ->
            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)
        );
    }
}

Customize colors

Unread indicator color:

import androidx.core.content.ContextCompat

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

import androidx.core.content.ContextCompat;

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

Refresh indicator colors:

import android.graphics.Color

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

import android.graphics.Color;

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

Empty inbox message

Set custom text for empty inbox:

val intent = Intent(this, BlueshiftInboxActivity::class.java)
intent.putExtra(BlueshiftConstants.INBOX_EMPTY_MESSAGE, "No messages yet")
startActivity(intent)

Intent intent = new Intent(this, BlueshiftInboxActivity.class);
intent.putExtra(BlueshiftConstants.INBOX_EMPTY_MESSAGE, "No messages yet");
startActivity(intent);

Set navigation title

When using BlueshiftInboxActivity, customize the title (requires ActionBar support):

val intent = Intent(this, BlueshiftInboxActivity::class.java)
intent.putExtra(BlueshiftConstants.INBOX_ACTIVITY_TITLE, "Messages")
startActivity(intent)

Intent intent = new Intent(this, BlueshiftInboxActivity.class);
intent.putExtra(BlueshiftConstants.INBOX_ACTIVITY_TITLE, "Messages");
startActivity(intent);

Test mobile inbox

Get device ID

In MainActivity, add this code inside the onCreate() method:

import android.util.Log
import com.blueshift.util.DeviceUtils

val deviceId = DeviceUtils.getDeviceId(this)
Log.d("InboxTest", "Device ID: $deviceId")

import android.util.Log;
import com.blueshift.util.DeviceUtils;

String deviceId = DeviceUtils.getDeviceId(this);
Log.d("InboxTest", "Device ID: " + deviceId);

Run your app and search for InboxTest in Logcat. You'll see something like the following:

D/InboxTest: Device ID: 6ca4a79a-ee53-4372-bb81-165ade978e1f

Copy the Device ID.

Send a test inbox message from Blueshift

Go to In-App Studio in the Blueshift dashboard
Create a new in-app notification or open an existing one
Choose display in mobile inbox in the Properties tab
Click the Test Send tab
Enter the Device ID in the Device ID field
Select the adapter from the App dropdown
Click Send

View the message

Open your app and tap the Inbox button.
Pull down to refresh the inbox list.
You should see the test message appearing in the list.
Pull down to refresh the inbox list and click the message. When you open the message, check Logcat for InAppTest:

D/InAppTest: In-app opened: {message data}

Check unread message count

Add this code where you want to display the unread count (e.g., in a fragment, or on your main activity's toolbar).

import com.blueshift.inbox.BlueshiftInboxManager

BlueshiftInboxManager.getUnreadMessagesCount(this) { count ->
    // Use `count` to update your UI (e.g., a badge)
    Log.d("InboxTest", "Unread count: $count")
}

import com.blueshift.inbox.BlueshiftInboxManager;

BlueshiftInboxManager.getUnreadMessagesCount(this, count -> {
    // Use `count` to update your UI (e.g., a badge)
    Log.d("InboxTest", "Unread count: " + count);
});

When you have unread messages, the unread count updates in Logcat.

D/InboxTest: Unread count: 1

If you have clicked the above (one) unread message, the count should reflect accordingly

D/InboxTest: Unread count: 0

Test deep links

The same in-app deep link logic handles deep links for inbox messages. For a detailed guide on testing deep links, refer to the Test deep links section of the In-app messages documentation.

Reference documentation

For more information about in-app messages: