Swrve Inbox API

The Inbox API returns a copy of push notifications sent to the user, so the message can be displayed and interacted with inside the application. This guide describes how the Inbox API is presented for iOS, Android, React Native, and Web.

Accessing the API

To retrieve a list of all messages that the user qualifies for, and are not past their end date:

Objective C

// add #import "SwrveSDK-Swift.h" to your imports
NSArray* pushInboxMessages = [SwrveSDK pushInboxMessages];

The array contains a collection of SwrvePushInboxMessage items. Each of these is an entry in the app’s notification inbox.

Swift

let pushInboxMessages = SwrveSDK.pushInboxMessages()

The array contains a collection of SwrvePushInboxMessage items. Each of these is an entry in the app’s notification inbox.

Android

List<SwrvePushInboxMessage> pushInboxMessages = SwrveSDK.getPushInboxMessages();

The array contains a collection of SwrvePushInboxMessage items. Each of these is an entry in the app’s notification inbox.

React Native

const pushInboxMessages = await SwrveSDK.getPushInboxMessages();

Web

const pushInboxMessages = SwrveSDK.pushInboxMessages();

The array contains a collection of ISwrvePushInboxMessage items. Each of these is an entry in the app's notification inbox. Unlike React Native, the Web API is synchronous — it returns the messages already cached by the SDK.

The array pushInboxMessages contains a collection of SwrvePushInboxMessage items. Each of these is an entry in the app’s notification inbox.

tip

To access Swrve's Inbox APIs, you must upgrade your apps to use Swrve's **iOS 9.1.0+ **and **Android 10.16.0+ **SDKs, Swrve React Native 5.1.0+ SDK, or Swrve Web 3.0.0+ SDK.

Inbox message properties

The SwrvePushInboxMessage object includes the following properties:

Objective C

Parameter	Description
messageId	The unique identifier of the campaign. (Integer)
variantId	The unique identifier of the notification's campaign variant. (Integer)
state	The read/unread state of the campaign. (SwrvePushInboxMessageState)
sentDate	The time the notification was sent to the user. Note: This is the time the corresponding remote notification is sent to the user, not the time the notification is downloaded to the device. (Integer)
endDate	The end date of the campaign. Cached messages that are past their endDate will be filtered out by the API. (Integer)
customerJson	The inbox message's content. (NSDictionary)

Swift

Parameter	Description
messageId	The unique identifier of the campaign. (Integer)
variantId	The unique identifier of the notification's campaign variant. (Integer)
state	The read/unread state of the campaign. (SwrvePushInboxMessageState)
sentDate	The time the notification was sent to the user. Note: This is the time the corresponding remote notification is sent to the user, not the time the notification is downloaded to the device. (Integer)
endDate	The end date of the campaign. Cached messages that are past their endDate will be filtered out by the API. (Integer)
customerJson	The inbox message's content. (NSDictionary)

Android

Parameter	Description
messageId	The unique identifier of the campaign. (Integer)
variantId	The unique identifier of the notification's campaign variant. (Integer)
state	The read/unread state of the campaign. (SwrvePushInboxMessageState)
sentDate	The time the notification was sent to the user. Note: This is the time the corresponding remote notification is sent to the user, not the time the notification is downloaded to the device. (Integer)
endDate	The end date of the campaign. Cached messages that are past their endDate will be filtered out by the API. (Integer)
customerJson	The inbox message's content. (JSONObject)

React Native

Parameter	Description
messageId	The unique identifier of the campaign. (Integer)
variantId	The unique identifier of the notification's campaign variant. (Integer)
state	The read/unread state of the campaign. (SwrvePushInboxMessageState)
sentDate	The time the notification was sent to the user. Note: This is the time the corresponding remote notification is sent to the user, not the time the notification is downloaded to the device. (Integer)
endDate	The end date of the campaign. Cached messages that are past their endDate will be filtered out by the API. (Integer)
customerJson	The inbox message's content, as a JSON string — parse it before use. (String)

Web

Parameter	Description
messageId	The unique identifier of the campaign. (String)
variantId	The unique identifier of the notification's campaign variant. (String)
state	The read/unread state of the campaign. (SwrvePushInboxMessageState)
sentDate	The time the notification was sent to the user. Note: This is the time the corresponding remote notification is sent to the user, not the time the notification is downloaded to the device. (Integer)
endDate	The end date of the campaign. Cached messages that are past their endDate will be filtered out by the API. (Integer)
customerJson	The inbox message's content. (Object)

note

On Web, messageId and variantId are strings rather than integers, so 64-bit identifiers are preserved exactly. Pass the messageId value to the read, engage, and delete APIs exactly as the SDK provides it.

Using the API

Here are examples of how to retrieve and use the message properties:

Objective C

NSArray *pushInboxMessages = [SwrveSDK pushInboxMessages];
for (SwrvePushInboxMessage *message in pushInboxMessages) {
long sentDate = message.sentDate; // when the notification was sent
SwrvePushInboxMessageState state = message.state; // current read or unread state
if (state == SwrvePushInboxMessageStateUNREAD ){
// show message UI as unread
}
NSDictionary *json = message.customerJson;  // your notification content should be here
// do something with each message such as building a UI list of messages to display
}

Swift

let pushInboxMessages = SwrveSDK.pushInboxMessages()
for message in pushInboxMessages {
if let message = message as? SwrvePushInboxMessage {
let sentDate = message.sentDate  // when the notification was sent
let state = message.state  // current read or unread state
if state == SwrvePushInboxMessageState.READ {
// show message UI as unread
}
if let json = message.customerJson {
// do something with each message such as building a UI list of messages to display
}
}
}

Android

List<SwrvePushInboxMessage> pushInboxMessages = SwrveSDK.getPushInboxMessages(); // get inbox messages
for (SwrvePushInboxMessage message : pushInboxMessages) {
long sentDate = message.getSentDate(); // when the notification was sent
SwrvePushInboxMessageState state = message.getState(); // current read or unread state
if (state == SwrvePushInboxMessageState.UNREAD) {
// show message UI as unread
}
JSONObject json = message.getCustomerJson(); // your notification content should be here
// do something with each message such as building a UI list of messages to display
}

React Native

const pushInboxMessages = await SwrveSDK.getPushInboxMessages(); // get inbox messages
inboxMessages.forEach((message) => {
const sentDate = message.sentDate; // when the notification was sent
const state =  message.state; // current read or unread state
if(state == "UNREAD") {
// show message UI as unread
}
const jsonObject = message.customerJson; // your notification content should be here
// do something with each message such as building a UI list of messages to display
});

Web

const pushInboxMessages = SwrveSDK.pushInboxMessages(); // get inbox messages
pushInboxMessages.forEach((message) => {
const sentDate = message.sentDate; // when the notification was sent
const state = message.state; // current read or unread state
if (state === "UNREAD") {
// show message UI as unread
}
const jsonObject = message.customerJson; // your notification content should be here
// do something with each message such as building a UI list of messages to display
});

Inbox message lifecycle examples

The following examples illustrate how to use the Inbox API to manage the message lifecycle in your app.

Message state

To retrieve the state associated with each inbox message entry, use the following:

Objective C

SwrvePushInboxMessageState state = message.state

Possible values are:

Value	Description
SwrvePushInboxMessageStateUNREAD	Message has not been marked as read by the user.
SwrvePushInboxMessageStateREAD	Message has been marked as read by the user.

Swift

let state = message.state

Possible values are:

Value	Description
SwrvePushInboxMessageState.UNREAD	Message has not been marked as read by the user.
SwrvePushInboxMessageState.READ	Message has been marked as read by the user.

Android

SwrvePushInboxMessageState state = message.getState();

Possible values are:

Value	Description
SwrvePushInboxMessageState.UNREAD	Message has not been marked as read by the user.
SwrvePushInboxMessageState.READ	Message has been marked as read by the user.

React Native

const state = message.state;

Possible values are:

Value	Description
"UNREAD"	Message has not been marked as read by the user.
"READ"	Message has been marked as read by the user.

Web

const state = message.state;

Possible values are:

Value	Description
"UNREAD"	Message has not been marked as read by the user.
"READ"	Message has been marked as read by the user.

The SwrvePushInboxMessageState enum is also exported if you prefer to compare against SwrvePushInboxMessageState.UNREAD and SwrvePushInboxMessageState.READ.

Tracking user interactions & managing message state

There are two API's available to change the state of a message from *"*unread" to *"*read", and another API to delete the message. All API's generate events, which are used by Swrve to calculate the inbox metrics in the corresponding campaign report.

The APIs take a messageId, found in the SwrvePushInboxMessage object, and a SwrvePushInboxDelegate callback (iOS) or SwrvePushInboxListener callback (Android).

React Native takes only a messageId and returns a Promise. The Promise resolves with a map containing SwrvePushInboxListener property values.

Web takes a messageId and an optional listener callback, and returns a Promise that resolves with an ISwrvePushInboxResult. The Promise resolves with an error result code rather than rejecting, so you can check the outcome from either the returned result or the listener.

Check the SUCCESS result code in the callback for successful updates. If there is an ERROR result code, then use the httpResponseCode to determine if it should be retried.

Mark message as "Read"

Here's an example of how to mark a message as read using the readPushInboxMessage API:

Objective C

[SwrveSDK readPushInboxMessage:message.messageId listener:self]; // where self conforms to protocol SwrvePushInboxDelegate
...
- (void)onComplete:(UInt64)messageId result:(SwrvePushInboxResult *)result {
if (result.resultCode == SwrvePushInboxResultCodeSUCCESS) {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
NSInteger httpResponseCode = result.httpResponseCode;
}
}

Swift

SwrveSDK.readPushInboxMessage(message.messageId, listener:self) // where self conforms to protocol SwrvePushInboxDelegate
...
public func onComplete(_ messageId: UInt64, result: SwrvePushInboxResult) {
if result.resultCode != SwrvePushInboxResultCode.SUCCESS {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
let httpResponseCode = result.httpResponseCode
}
}

Android

SwrveSDK.readPushInboxMessage(message.messageId, new SwrvePushInboxListener() {
@Override
public void onComplete(long messageId, @NonNull SwrvePushInboxListenerResult result) {
if (result.getResultCode() == SwrvePushInboxListenerResult.ResultCode.SUCCESS) {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
int httpResponseCode = result.getHttpResponseCode();
}
}
});
(item);

React Native

const result = await SwrveSDK.readPushInboxMessage(message.messageId);
if(result.resultCode == "SUCCESS") {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
const httpResponseCode = result.httpResponseCode;
}

Web

const result = await SwrveSDK.readPushInboxMessage(message.messageId);
if (result.resultCode === "SUCCESS") {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
const httpResponseCode = result.httpResponseCode;
}

Alternatively, pass a listener as the second argument instead of awaiting the promise:

SwrveSDK.readPushInboxMessage(message.messageId, (messageId, result) => {
if (result.resultCode === "SUCCESS") {
// operation was successful
} else {
// operation was not successful. Check result.httpResponseCode and result.errorMessage
}
});

The readPushInboxMessage may send a read event, used internally for reporting.

Track engagements

The engagePushInboxMessage API is intended to track a user’s direct engagement with the message. Use of the API implies that the user has read the message, so calling the API changes the message’s state from *"*unread" to "read".

Objective C

[SwrveSDK engagePushInboxMessage:message.messageId listener:self]; // where self conforms to protocol SwrvePushInboxDelegate
...
- (void)onComplete:(UInt64)messageId result:(SwrvePushInboxResult *)result {
if (result.resultCode == SwrvePushInboxResultCodeSUCCESS) {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
NSInteger httpResponseCode = result.httpResponseCode;
}
}

Swift

SwrveSDK.engagePushInboxMessage(message.messageId, listener:self) // where self conforms to protocol SwrvePushInboxDelegate
...
public func onComplete(_ messageId: UInt64, result: SwrvePushInboxResult) {
if result.resultCode != SwrvePushInboxResultCode.SUCCESS {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
let httpResponseCode = result.httpResponseCode
}
}

Android

SwrveSDK.engagePushInboxMessage(message.messageId, new SwrvePushInboxListener() {
@Override
public void onComplete(long messageId, @NonNull SwrvePushInboxListenerResult result) {
if (result.getResultCode() == SwrvePushInboxListenerResult.ResultCode.SUCCESS) {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
int httpResponseCode = result.getHttpResponseCode();
}
}
});

React Native

const result = await SwrveSDK.engagePushInboxMessage(message.messageId);
if(result.resultCode == "SUCCESS") {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
const httpResponseCode = result.httpResponseCode;
}

Web

const result = await SwrveSDK.engagePushInboxMessage(message.messageId);
if (result.resultCode === "SUCCESS") {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
const httpResponseCode = result.httpResponseCode;
}

A listener can also be passed as the second argument in place of awaiting the promise.

The engagePushInboxMessage will send an engagement event and may send a read event, used internally for reporting.

Delete message

Finally, to delete the message from visibility so it doesn’t appear in the inbox again, call the deletePushInboxMessage API.

Objective C

[SwrveSDK deletePushInboxMessage:message.messageId listener:self]; // where self conforms to protocol SwrvePushInboxDelegate
...
- (void)onComplete:(UInt64)messageId result:(SwrvePushInboxResult *)result {
if (result.resultCode == SwrvePushInboxResultCodeSUCCESS) {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
NSInteger httpResponseCode = result.httpResponseCode;
}
}

Swift

SwrveSDK.deletePushInboxMessage(message.messageId, listener:self) // where self conforms to protocol SwrvePushInboxDelegate
...
public func onComplete(_ messageId: UInt64, result: SwrvePushInboxResult) {
if result.resultCode != SwrvePushInboxResultCode.SUCCESS {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
let httpResponseCode = result.httpResponseCode
}
}

Android

SwrveSDK.deletePushInboxMessage(message.messageId, new SwrvePushInboxListener() {
@Override
public void onComplete(long messageId, @NonNull SwrvePushInboxListenerResult result) {
if (result.getResultCode() == SwrvePushInboxListenerResult.ResultCode.SUCCESS) {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
int httpResponseCode = result.getHttpResponseCode();
}
}
});

React Native

const result = await SwrveSDK.deletePushInboxMessage(message.messageId);
if(result.resultCode == "SUCCESS") {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
const httpResponseCode = result.httpResponseCode;
}

Web

const result = await SwrveSDK.deletePushInboxMessage(message.messageId);
if (result.resultCode === "SUCCESS") {
// operation was successful
} else {
// operation was not successful. Check the http code in the result object
const httpResponseCode = result.httpResponseCode;
}

On success the message is removed from the list returned by pushInboxMessages, so refresh your inbox UI after the call resolves. A listener can also be passed as the second argument in place of awaiting the promise.

The deletePushInboxMessage API will send a delete event, used internally for reporting.

Checking for Updates

Configure the pushInboxUpdateListener (iOS and Web) and setPushInboxUpdateListener (Android and React Native) callback APIs to receive updates when the Push Inbox Messages content has changed.

Objective C

The SwrvePushInboxUpdateDelegate, set via pushInboxUpdateListener API, is a delegate callback. Here's an example of how to configure the callback:

// add #import "SwrvePushInboxUpdateDelegate.h" to your imports
[SwrveSDK pushInboxUpdateListener:self]; // where self conforms to protocol SwrvePushInboxUpdateDelegate
...
- (void) messagesUpdated {
// refresh UI
}

Swift

The SwrvePushInboxUpdateDelegate, set via pushInboxUpdateListener API, is a delegate callback. Here's an example of how to configure the callback:

SwrveSDK.pushInboxUpdateListener(self) // where self conforms to protocol SwrvePushInboxUpdateDelegate
...
public func messagesUpdated() {
// refresh UI
}

Android

Here's an example of how to configure the callback:

// Hold the listener in a field of your activity, fragment, or repository.
private SwrvePushInboxUpdateListener inboxListener;

inboxListener = new SwrvePushInboxUpdateListener() {
    @Override
    public void onMessagesUpdated() {
        // new message content
    }
};
SwrveSDK.setPushInboxUpdateListener(inboxListener);

From Android SDK version 12.3.0, the SDK holds this listener with a weak reference, so that registering it does not leak the component that registered it. Keep your own strong reference to the listener for as long as you want updates. A listener the SDK is the only holder of is garbage collected, after which callbacks stop arriving and nothing is reported. To stop updates, pass null.

React Native

Here's an example of how to configure the callback:

SwrveSDK.setPushInboxUpdateListener(
{pushInboxUpdateListener: async () => {
// refresh UI
}}
);

Web

Here's an example of how to configure the callback:

SwrveSDK.pushInboxUpdateListener(() => {
const pushInboxMessages = SwrveSDK.pushInboxMessages(); // fetch the updated list
// refresh UI
});

The callback takes no arguments, so call pushInboxMessages inside it to read the new content. Only one listener is stored — calling the API again replaces the previous callback.

The refreshCampaignsAndResources API can also be used to force a refresh from the server. Maintaining message state across devices The SDK informs Swrve of message state changes, which are stored to the user's Swrve ID. When the SDK requests a new list of campaigns (e.g. on app launch), Swrve returns the latest state value for each message. This ensures that the the message's state is consistently reflected across all of the user's devices.

---

General use case

Objective C

Use the NSArray of SwrvePushInboxMessage items that the [SwrveSDK pushInboxMessages] call returns and present them in an inbox or other custom view.

Swift

Use the list of SwrvePushInboxMessage items that the SwrveSDK.pushInboxMessages() call returns and present them in an inbox or other custom view.

Android

Use the list of SwrvePushInboxMessage items that the SwrveSDK.getPushInboxMessages() call returns and present them in an inbox or other custom view.

React Native

Use the list of SwrvePushInboxMessage items that the SwrveSDK.getPushInboxMessages() call returns and present them in an inbox or other custom React component.

Web

Use the list of ISwrvePushInboxMessage items that the SwrveSDK.pushInboxMessages() call returns and present them in an inbox or other custom view in your web app.

The message.customerJson (iOS, React Native, and Web) or message.getCustomerJson() (Android) returns a json object with the inbox content defined in the campaign (see Notification inbox). Build a UI to present this content to the user, and execute custom actions when the user interacts with it.

When the user indicates they’ve read a specific message, use the readPushInboxMessage API to update the message’s state to “read”.

When the user engages directly with the message's content, call the engagePushInboxMessage API to capture the engagement and update the message’s state to “read”.

When the user deletes a message, call the deletePushInboxMessage API to permanently remove the message from the user's inbox.