Messaging

Getting the inbox message count

The getInboxMessageCount() instance method of the BitplacesSDK class will send a request to the server in order to get the count of total and unread messages in the user's inbox, and notify your callback of the result:

EXAMPLE:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
BitplacesSDK bpSDK = BitplacesSDK.getInstance();

bpSDK.getInboxMessageCount(
    new BitplacesOperationCompletionHandler<InboxMessageCount>() {
        @Override
        public void onOperationComplete(int resultCode, InboxMessageCount mc) {
            if (BitplacesSDK.ResultCode.fromCode(resultCode).isSuccessful()) {
                // InboxMessageCount is a simple value class wrapping two integers,
                // the total message count and the unread message count.
                int totalMessages = mc.getTotalMessageCount();
                int unreadMessages = mc.getUnreadMessageCount();
                // ...
            } else {
                // Handle error according to your application logic
            }
        }
    }
);

Getting messages from the inbox

There are two different methods to retrieve messages from the user's inbox.

The first one will retrieve the first n messages from the inbox, where n is a default value determined by the Bitplaces platform (currently 50):

1
getInboxMessages(BitplacesOperationCompletionHandler<ArrayList<BitplacesMessage>> resultHandler)

Upon successful completion of the process your resultHandler will be passed an ArrayList of BitplacesMessage instances, each one containing among others a creation date, a type and status, content, title and body.

it is also possible to specify explicitly the first message to retrieve and the amount of messages to fetch, useful to perform incremental updates to a messages list as the user scrolls through it:

1
getInboxMessages(int pageOrigin,int pageSize, MessageSortType sortType, BitplacesOperationCompletionHandler<ArrayList<BitplacesMessage>> resultHandler)

This method expects as well an explicit message sort type. You can specify MessageSortType.DATE or MessageSortType.DISTANCE.

Note: each message has a visibility property whose value you can access with getVisibility() and can be MessageVisibility.Visible or MessageVisibility.Hidden. You can use this property to avoid displaying messages that shouldn't be visible on the user's message list.

Showing the number of unread message as message badge on your app icon

The Bitplaces SDK can show the number of unread Inbox messages as a badge on your app icon. For this, use the setUseMessagesBadgeCounter(boolean useBadgeCounter) method on an instance of the BitplacesSDK. By default this functionality is turned off. If you also integrate another SDK with similar message functionality, you might want to disable feature and implement it yourself, as otherwise the total amount of messages for a given user may not be correct.

Note: Not all launchers support the message badge. For an overview look at ShortcutBadger.

Getting a single message by ID

To retrieve a single message with a known message ID, use the following method:

1
getMessageById(long messageId, BitplacesOperationCompletionHandler<BitplacesMessage> resultHandler)

EXAMPLE:

1
2
3
4
5
6
7
8
BitplacesSDK.getInstance().getMessageById(messageId,
new BitplacesOperationCompletionHandler<BitplacesMessage>() {
    @Override
    public void onOperationComplete(int resultCode, BitplacesMessage message) {
        if (ResultCode.fromCode(resultCode) == ResultCode.RESULT_SUCCESS)
        Log.i(TAG, "Retrieved message: " + message.toString());
    }
});

Note: Fetching a message by ID will change its status automatically to Read.

The BitplacesMessage class exposes the following getters to access its values:

Getter Return value type Description
getId() long ID of this message on the Bitplaces platform
getForeignId() String Corresponding foreign ID in your platform
getLatitude() double Geographical latitude associated with this message
getLongitude() double Geographical longitude associated with this message
getCreationDate() java.util.Date Message creation date
getStatus() String Message status as reported by the platform
getType() String Message type as reported by the platform. E.g.: "NEW"
getContent() String Content of the push message. Can contain up to 107 characters.
setTitle() String Message title
getBody() String Body of the message. Can contain HTML and it can be up to 1024 characters long.
getEventType() BitplaceEvent.EventType The type of event that generated this message
getBitplaceId() long ID of the bitplace associated with this message
getImageId() long ID of the image associated with this message
getVisibility() MessageVisibility.Visible or MessageVisibility.Hidden Whether a message in the user's inbox should be "visible" or "hidden". Hidden messages will not be included in the count of unread messages in the inbox.
getMetadata() Map<String,String> Map of arbitrary key-value pairs assigned to this message

Changing the status of one message

Use the setInboxMessageStatus() instance method of the BitplacesSDK class, passing to it the ID of the message whose status is to be modified as well as the desired new status, which has to be one of the constants defined in the BitplacesMessage.MessageStatus enum (currently Unread, Read and Deleted).

Note: Fetching a message by ID, as described in the Getting a single message by ID section, will change its status automatically to Read, so there is no need to do it explicitly through this method.

EXAMPLE: SETTING A MESSAGE AS UNREAD

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
bpSDK.setInboxMessageStatus(messageId,
    BitplacesMessage.MessageStatus.Unread,
    new BitplacesOperationCompletionHandler<Long>() {
        @Override
        public void onOperationComplete(int resultCode, Long messageId) {
            if (!ResultCode.fromCode(resultCode).isSuccessful()) {
                // Handle error accordingly with your application logic
            }        
        }
    });

Marking all of the messages in the Inbox as READ

Use the markAllInboxMessagesRead() instance method of the BitplacesSDK class, which expects only your callback object that would be notified of the success status of the request.

EXAMPLE:

1
2
3
4
5
6
7
8
9
bpSDK.markAllInboxMessagesRead(new BitplacesOperationCompletionHandler<Void>() {
    @Override
    public void onOperationComplete(int resultCode, Void resultData) {
        // resultData must be ignored for this request. Only resultCode is useful
        if (!ResultCode.fromCode(resultCode).isSuccessful()) {
            // Handle error accordingly with your application logic
        }        
    }
});

Deleting all messages from the Inbox

Use the clearInbox() instance method of the BitplacesSDK class, which expects only your callback object that would be notified of the success status of the request.

EXAMPLE:

1
2
3
4
5
6
7
8
9
bpSDK.clearInbox(new BitplacesOperationCompletionHandler<Void>() {
    @Override
    public void onOperationComplete(int resultCode, Void resultData) {
        // resultData must be ignored for this request. Only resultCode is useful
        if (!ResultCode.fromCode(resultCode).isSuccessful()) {
            // Handle error accordingly with your application logic
        }        
    }
});