Last modified September 5, 2022 by Shelly Wolfe

Swrve Message Center API

The Swrve Message Center is an API for campaigns that have been downloaded from Swrve and are intended to be accessible in a way where the app user is in control of the message lifecycle. This guide describes how the Message Center API is presented for iOS, Android, and Unity.

Accessing the API

iOS

Once the Swrve instance is created in the AppDelegate as per the iOS Integration guide, retrieve a list all of the campaigns that the user qualifies for, and that are currently available, via NSArray* campaigns:

NSArray* campaigns = [SwrveSDK messageCenterCampaigns];

The array contains a collection of SwrveBaseCampaign objects. Each of these is an entry in the app’s message center.

Android

SwrveSDK.createInstance(this, <app_id>, "<api_key>");

The shared instance contains methods to list all of the campaigns that this user qualifies for, and that are available right now:

List<SwrveBaseCampaign> campaigns = SwrveSDK.getMessageCenterCampaigns();

The list contains a collection of SwrveBaseCampaign objects. Each of these is an entry in the app’s message center.

Unity

The Swrve shared instance object contains a reference that you can use to list all of the campaigns that this user qualifies for, and that are available right now:

List<SwrveBaseCampaign> campaigns = SwrveComponent.Instance.SDK.GetMessageCenterCampaigns();

The array contains a collection of SwrveBaseCampaign objects. Each of these is an entry in the app’s message center.

Web

The Swrve shared instance object contains a reference that you can use to list all of the campaigns that this user qualifies for, and that are available right now:

var campaigns = SwrveSDK.getMessageCenterCampaigns();

The array contains a collection of ISwrveBaseCampaign objects. Each of these is an entry in the app’s message center.


Campaign properties

Here are some examples of the campaign properties that are available in the Swrve Message Center API:

iOS

NSArray *campaigns = [SwrveSDK messageCenterCampaigns];

// get campaign at some position in a table list 
SwrveCampaign *campaign  = [campaigns objectAtIndex:[indexPath row]]; 

NSUInteger ID = campaign.ID;
NSString *name = campaign.name;
NSString *subject = campaign.subject; // (this is deprecated, use new messageCenterSubject)
NSDate *dateStart = campaign.dateStart;
NSDate *dateEnd = campaign.dateEnd;
NSNumber *priority = campaign.priority;
NSDate *downloadDate = [campaign downloadDate];
NSString *messageCenterSubject =  campaign.messageCenterDetails.subject;
NSString *messageCenterDescription = campaign.messageCenterDetails.description;
NSString *accessibilityText = campaign.messageCenterDetails.imageAccessibilityText;
UIImage *messageCenterIconImage = campaign.messageCenterDetails.image;

Android

List campaigns = SwrveSDK.getMessageCenterCampaigns();

// get campaign at some position in a table list 
SwrveBaseCampaign campaign = campaigns.get(adapter.getItem(getSelectedItemPosition()));

int ID = campaign.getId();
String name = campaign.getName();
String subject = campaign.subject; // (this is deprecated, use new messageCenterSubject)
Date dateStart = campaign.getStartDate();
Date dateEnd = campaign.getEndDate();
SwrveInAppCampaign inAppCampaign = (SwrveInAppCampaign)campaign;
int priority = inAppCampaign.getMessage().getPriority();
Date downloadDate = campaign.getDownloadDate();
String messageCenterSubject =  campaign.getMessageCenterDetails().getSubject();
String messageCenterDescription = campaign.getMessageCenterDetails().getDescription();
String accessibilityText =campaign.getMessageCenterDetails().getImageAccessibilityText();
Bitmap messageCenterIconImage = campaign.getMessageCenterDetails().getImage();

The following parameters are supported for in-app message, embedded, and Conversation campaign creation. Swrve’s Message Center API returns these properties regardless of the SDK version:

Parameter Description
ID A unique identifier.
name The name of the campaign, which defaults to Empty.
state The state of the campaign.
minDelayBetweenMsgs The minimum interval between different campaign messages.
messageCenter A flag that indicates a message center campaign is sent from the message center.
subject The message center campaign subject. This should match the campaign description.

The Message Center API returns the below properties in the following SDKs: iOS SDK 8.1.0, Android SDK 10.2.0, Unity SDK 9.0.0, and React Native SDK 4.0.0.

The following parameters are not supported by Swrve’s Web SDK and are currently only available for in-app message campaigns.

They are exposed in the new SwrveMessageCenterDetails object and the values are configurable through the in-app message campaign Content page, on the Message center details tab:

Parameter Description
subject The variant-specific subject of the campaign that corresponds to the Subject value set in the campaign’s Content page.
description The description of the campaign that corresponds to the Description value set in the campaign’s Content page.
image
Types:
iOS: UIImage
Android: Bitmap
Unity: Texture2d
The message center image that corresponds to the thumbnail image set in the campaign’s content page. This property includes the image type data, ready to load into the image component.
imageUrl The personalized image URL. This is used for reference as the image is downloadable from the cache.
imageSha The imageSha is available if the thumbnail image has been uploaded into the dashboard.
accessibilityText The alt text value provided for the image.

The following properties have been added to the existing SwrveCampaign object.

Parameter Description
dateEnd The end date of the campaign.
priority The priority of the campaign in relation to other message center campaigns.
downloadDate The date and time the campaign is downloaded to the user’s device. If the campaign is downloaded to the device multiple times, this value reflects the first time the campaign was downloaded.
name The name of the campaign.
Note: This property returned an empty value in previous versions of the Swrve SDKs.

Parameter mapping to message center details

The Message Center API parameters relate to the following options in the Message center details tab:

Message center details Message Center API parameter
Subject subject
Description description
Thumbnail image – The actual image, whether downloaded from the specified URL or uploaded to the dashboard. In the event the SDK cannot download the image from the URL, this represents the fallback image (if provided).
Upload file – If a thumbnail image was uploaded to the dashboard. imageSha – If a URL was provided as the thumbnail image, then this represents the uploaded fallback image.
URL – If a thumbnail image was provided as a URL. imageUrl
Alt text accessibilityText

Campaign lifecycle examples

The following examples illustrate how to use the Message Center API to manage the message lifecycle in your app, from displaying the campaign subject line and getting its status, to displaying a message or removing it from visibility.

Subject line

To get the subject line of the campaign to display in the app’s message center, use the following:

iOS

SwrveBaseCampaign *item = (SwrveBaseCampaign*)[campaigns objectAtIndex:0];
NSString* subject = item.subject;

Android

SwrveBaseCampaign item = campaigns.get(0);
String subject = item.getSubject();

Unity

SwrveBaseCampaign item = campaigns[0];
string subject = item.Subject;

Web

var item = campaigns[0];
var subject = item.subject;

Campaign status

To retrieve the status associated with each message center entry, use the following:

iOS

SwrveCampaignStatus status = item.state.status;

Possible values are:

Value Description
SWRVE_CAMPAIGN_STATUS_UNSEEN  = 0x1 Campaign hasn’t been seen by the user.
SWRVE_CAMPAIGN_STATUS_SEEN    = 0x2 Campaign has been seen at least once by the user.
SWRVE_CAMPAIGN_STATUS_DELETED = 0x3 Campaign has been deleted and won’t appear again in the inbox.

Android

SwrveCampaignState.Status status = item.getStatus();

Possible values are:

Value Description
SwrveCampaignState.Status.Unseen Campaign hasn’t been seen by the user.
SwrveCampaignState.Status.Seen Campaign has been seen at least once by the user.
SwrveCampaignState.Status.Deleted Campaign has been deleted and won’t appear again in the inbox.

Unity

SwrveCampaignState.Status status = item.Status;

Possible values are:

Value Description
SwrveCampaignState.Status.Unseen Campaign hasn’t been seen by the user.
SwrveCampaignState.Status.Seen Campaign has been seen at least once by the user.
SwrveCampaignState.Status.Deleted Campaign has been deleted and won’t appear again in the inbox.

Web

var status = item.status;

Possible values are:

Value Description
“unseen” Campaign hasn’t been seen by the user.
“seen” Campaign has been seen at least once by the user.

Show campaign

The SDK is responsible for rendering and reacting to the campaign, so this capability is provided by a single API call:

iOS

[[SwrveSDK messaging] showMessageCenterCampaign:item];

Android

SwrveSDK.showMessageCenterCampaign(item);

Unity

SwrveComponent.Instance.SDK.ShowMessageCenterCampaign(item);

Web

SwrveSDK.showMessageCenterCampaign(item);

Remove campaign

Finally, to remove the campaign from visibility so it doesn’t appear in the message center again, use the following:

iOS

[SwrveSDK removeMessageCenterCampaign:item];

Android

SwrveSDK.removeMessageCenterCampaign(item);

Unity

SwrveComponent.Instance.SDK.RemoveMessageCenterCampaign(item);

General use case

iOS

Use the NSArray* that the [Swrve messageCenterCampaigns] call returns as a data provider to a table view, or custom view, for presentation in the app proper.

Android

Use the list that the SwrveSDK.getMessageCenterCampaigns() call returns as the source of an ArrayAdapter<SwrveBaseCampaign> used in a ListView, or custom view, for presentation in the app proper.

Unity

Use the list that the SDK returns to populate a ListLayout inside a Canvas and ScrollRect to display the items.

When the app user selects a campaign in the message center view, the app should call the showMessageCenterCampaign API call to present it to the user.

When the user deletes the entry in the message center view, then the app should call removeMessageCenterCampaign for the selected campaign.