Last modified August 28, 2024 by John Mcgrath

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 and Android.

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.

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, or Swrve React Native 5.1.0+ SDK.

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.

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.

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.