Implementing Custom Inbox on your Website

You can implement any custom look for the inbox on your website using API provided by xtremepush SDK.

 

1. You can use message.list API call to retrieve the list of messages for the current user:

xtremepush('inbox', 'message.list', params, success, error);

The result object passed to success function contains:

{
items: array, // Array of messages
more: boolean, // Shows if there is more messages for this user
badge: integer // Updated inbox badge
}

The message object contains:

{
id: integer, // Message id
opened: 0/1, // Whether the message is marked as opened or not
clicked: 0/1, // Whether a click event was tracked on this message
create_time: integer, // Unix timestamp of when message was created
expiration_time: integer, // Unix timestamp of when message is expiring. Could be null.
message: { // Data to render the message
title: string,
alert: string,
icon: string,
style: array
}
}

Available params:

{
limit: integer, // Maximum number of messages to return
offset: integer, // Offset that can be used for pagination or show more functionality.
opened: 0/1, // Return opened or not opened messages. Skip to return all.
clicked: 0/1, // Return clicked or not clicked messages. Skip to return all.
expired: 0/1, // Return expired or not expired messages. 0 by default.
min_time: integer, // Return messages after certain date (using unix timestamp).
max_time: integer, // Return messages before certain date (using unix timestamp).
}

 

2. You can use message.count API call to count number of messages for the current user

xtremepush('inbox', 'message.count', params, success, error);

The list of parameters is the same as for message.list (see above).

The result object passed to success function contains:

{
count: integer // Number of messages matching criteria
}

Please don't use message.count method on page load in order to display inbox badge. You should use badge API call instead which is described in the section below. 

 

3. You can use message.action API call to mark message as opened or track click event.

xtremepush('inbox', 'message.action', action, success, error);

The action object should contain:

{
id: integer, // Message id retrieved from message.list API call. Required.
open: 0/1, // Whether you want to mark message as 'opened'
click: 0/1, // Whether you want to track click event
button: string // Can be used if you want to track click with the specific button ID.
}

The result object passed to success function contains:

{
badge: integer // Updated inbox badge
}

 

You can also use message.actions API call to mark multiple messages as opened:

xtremepush('inbox', 'message.actions', actions, success, error);

The actions object should contain an array of action objects (described above in message.action section). 

 

4. You can use badge API call to retrieve a number to display as inbox icon badge

xtremepush('inbox', 'badge', params, success, error);

The result object passed to success function contains:

{
badge: integer // Up to date inbox badge
}

There are two different types of badges you could use for your inbox:

 - Number of messages that are not seen by user yet.

 - Number of messages that are not opened by user yet.

You can choose required type of badge for your project on the 'inbox settings' page. To understand which type you want to use read following:

 - The message is marked as seen at the moment when it's returned in a response to the message.list API call. So the inbox badge is incrementing when a new message is created for a user. And the badge is reset when user opens the inbox.

 - The message is marked as opened at the moment when you call message.action API call for this message. So the inbox badge is incrementing when a new message is created for a user. And the badge is decremented when user interacts with the message (such as clicks on it).

Feel free to call badge API call on page load. But note that badge could be changed during message.list or message.action API call. Both of these methods return the updated badge so you need to consider updating your badge using these values.

 

Example:

On page load:
xtremepush('ready', function() {
// make sure to retrieve inbox badge inside ready callback to ensure that user is registered
xtremepush('inbox', 'badge', {}, function(result) {
updateMyBadge(result.badge);
}, function(err) {
console.log(err);
});
});

When user clicks to open inbox:
myInboxButton.addEventListender('click', function() {
xtremepush('inbox', 'message.list', {
limit: 10,
offset: 0
}, function (result) {
if (result.badge !== undefined) {
updateMyBadge(result.badge);
}

for (var i = 0; i < result.items.length; i++) {
var item = result.items[i];
var element = createMyInboxMessageElement(item);

// Handle click and track open event
element.addEventListener('click', function () {
xtremepush('inbox', 'message.action', {
id: id,
open: 1
}, function(result) {
if (result.badge !== undefined) {
updateMyBadge(result.badge);
}
}, function(err) {
console.log(err);
})
});
}

if (result.more) {
showMyLoadMoreButton();
}
}, function (err) {
console.log(err);
});
});

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.