Skip to content

App Inbox API (SDK) Docs

This section is dedicated to the various functions available within the OpenBack App Inbox API.

To start using the App Inbox feature, first make sure you have followed the integration guide. App inbox is publicly available since version 1.8.5.

Then add the following import to the file(s) where you plan to use the App Inbox:

@import OpenBack;

The App Inbox is a great feature to keep all the messages in one place, allowing users to read messages even after they dismissed a notification. Your application is in charge of managing and displaying the messages.

An App Inbox message is a simple class proxy that only exposes the required information like the title, content, and the message read status. An App Inbox message can be actionable, meaning it can perform an action when selected, like opening a deep link or display an image. Executing a message action will mark the message as read.

The App Inbox provides a simple API for accessing the messages, removing them or change their status. For example, calling the getUnreadMessageCount: can be used to display a badge with the number of messages that require the users's attention.

To display the App Inbox messages, you could for example use a UITableViewController with a basic cell showing the title and subtitle. Set the text font weight to bold when unread. When user selects a row that is actionable, just call the [inbox executeMessage:message completion:nil]. The App Inbox can also notify the application that a message was added, read or expired by using a delegate.

The sample application available on Github here shows a simple UITableViewController implementation.

Getting the App Inbox

+ appInbox:

+ (nullable OpenBackAppInbox *)appInbox;

If your OpenBack application supports App Inbox, get the App Inbox associated to your application App Code from the main OpenBack class.

OpenBackAppInbox *inbox = [OpenBack appInbox];

App Inbox API

Class OpenBackAppInbox

- getMessageCount:

- (void)getMessageCount:(void (^)(NSUInteger messageCount))completion;

Get the total number of messages in inbox.

Example:

OpenBackAppInbox *inbox = [OpenBack appInbox];
[inbox getMessageCount:^(NSUInteger messageCount) {
    ...
}];

- getUnreadMessageCount

- (void)getUnreadMessageCount:(void (^)(NSUInteger unreadMessageCount))completion;

Get the number of unread messages in inbox.

Example:

OpenBackAppInbox *inbox = [OpenBack appInbox];
[inbox getUnreadMessageCount:^(NSUInteger unreadMessageCount) {
    ...
}];

- getAllMessages:

- (void)getAllMessages:(void (^)(NSArray<OpenBackAppInboxMessage *> *messages))completion;

Retrieve all Inbox messages. Messages are sorted by display time, from newest to oldest.

Example:

OpenBackAppInbox *inbox = [OpenBack appInbox];
[inbox getAllMessages:^(NSArray<OpenBackAppInboxMessage *> * _Nonnull messages) {
    ...
}];

- getReadMessages:

- (void)getReadMessages:(void (^)(NSArray<OpenBackAppInboxMessage *> *messages))completion;

Retrieve read Inbox messages. Messages are sorted by display time, from newest to oldest.

Example:

OpenBackAppInbox *inbox = [OpenBack appInbox];
[inbox getReadMessages:^(NSArray<OpenBackAppInboxMessage *> * _Nonnull messages) {
    ...
}];

- getUnreadMessages:

- (void)getUnreadMessages:(void (^)(NSArray<OpenBackAppInboxMessage *> *messages))completion;

Retrieve unread Inbox messages. Messages are sorted by display time, from newest to oldest.

Example:

OpenBackAppInbox *inbox = [OpenBack appInbox];
[inbox getUnreadMessages:^(NSArray<OpenBackAppInboxMessage *> * _Nonnull messages) {
    ...
}];

- markMessageAsRead:completion:

- (void)markMessageAsRead:(OpenBackAppInboxMessage *)message 
               completion:(nullable void (^)(NSError * _Nullable))completion;

Mark an Inbox message as read.

Example:

[inbox markMessageAsRead:message completion:^(NSError * _Nullable) {
    ...
}];

- markMessagesAsRead:completion:

- (void)markMessagesAsRead:(NSArray<OpenBackAppInboxMessage *> *)messages 
                completion:(nullable void (^)(NSError * _Nullable))completion;

Mark multiple Inbox messages as read.

Example:

[inbox markMessagesAsRead:@[ message1, message2 ] completion:^(NSError * _Nullable) {
    ...
}];

- markAllMessagesAsRead:

- (void)markAllMessagesAsRead:(nullable void (^)(NSError * _Nullable))completion;

Mark multiple Inbox messages as read.

Example:

[inbox markAllMessagesAsRead:^(NSError * _Nullable) {
    ...
}];

- removeMessage:completion:

- (void)removeMessage:(OpenBackAppInboxMessage *)message 
               completion:(nullable void (^)(NSError * _Nullable))completion;

Remove a message from the App Inbox.

Example:

[inbox removeMessage:message completion:^(NSError * _Nullable) {
    ...
}];

- removeMessages:completion:

- (void)removeMessages:(NSArray<OpenBackAppInboxMessage *> *)messages 
            completion:(nullable void (^)(NSError * _Nullable))completion;

Remove multiple messages from the App Inbox.

Example:

[inbox removeMessages:@[ message1, message2 ] completion:^(NSError * _Nullable) {
    ...
}];

- removeAllMessages:

- (void)removeAllMessages:(nullable void (^)(NSError * _Nullable))completion;

Remove all Inbox messages.

Example:

[inbox removeAllMessages:^(NSError * _Nullable) {
    ...
}];

- executeMessage:completion:

- (void)executeMessage:(OpenBackAppInboxMessage *)message 
            completion:(nullable void (^)(NSError * _Nullable))completion;

If a message is actionable, call this method to execute the associated action. Messages can have an actionable URL, deep-link, video, image, custom HTML.

Example:

[inbox executeMessage:message completion:^(NSError * _Nullable) {
    ...
}];

 delegate

@property (weak) id<OpenBackAppInboxDelegate> delegate;

App Inbox delegate.

App Inbox Message

Class OpenBackAppInboxMessage

 isRead

@property (nonatomic, readonly, getter=isRead) BOOL read;

Inbox message read status.

 isActionable

@property (nonatomic, readonly, getter=isActionable) BOOL actionable;

Inbox message is can open a url, deep-link, image, etc...

 deliveryTime

@property (nonatomic, readonly) uint64_t deliveryTime;

Inbox message display/delivery time in seconds from UNIX epoch.

 title

@property (nonatomic, readonly, copy) NSString *title;

Inbox message title.

 content

@property (nonatomic, readonly, copy) NSString *content;

Inbox message content.

 payload

@property (nonatomic, readonly, copy) NSString *payload;

Inbox message custom payload.

App Inbox Message Delegate

You can register your app to receive events when a message is added, marked as read or expired from the inbox.

Protocol OpenBackAppInboxDelegate

- appInboxMessageAdded:

@optional
- (void)appInboxMessageAdded:(OpenBackAppInboxMessage *)message;

Called when a message is added to the App Inbox.

- appInboxMessageRead:

@optional
- (void)appInboxMessageRead:(OpenBackAppInboxMessage *)message;

Called when a message is marked as read when a notification is selected.

- appInboxMessageExpired:

@optional
- (void)appInboxMessageExpired:(OpenBackAppInboxMessage *)message;

Called when a message has expired and was removed from the inbox.