Swrve Inbox API
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();
The array pushInboxMessages
contains a collection of SwrvePushInboxMessage
items. Each of these is an entry in the app’s notification inbox.
Inbox message properties
The SwrvePushInboxMessage
object includes the following properties:
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/JSON) |
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 });
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. |
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.
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; }
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; }
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; }
The deletePushInboxMessage
API will send a delete event, used internally for reporting.
Checking for Updates
Configure the pushInboxUpdateListener
(iOS) 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:
SwrveSDK.setPushInboxUpdateListener(new SwrvePushInboxUpdateListener() { @Override public void onMessagesUpdated() { // new message content } });
React Native
Here’s an example of how to configure the callback:
SwrveSDK.setPushInboxUpdateListener( {pushInboxUpdateListener: async () => { // refresh UI }} );
The refreshCampaignsAndResources
API can also be used to force a refresh from the server.
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.
The message.customerJson (iOS and React Native) 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.