Skip to main content

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, Unity, and Web.

Accessing the API​

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 let campaigns: [SwrveCampaign]:

let campaigns = SwrveSDK.messageCenterCampaigns()

The array contains a collection of SwrveCampaign objects. Each of these is an entry in the app's message center, and includes both in-app message and embedded campaigns.

To retrieve only the in-app message campaigns, use inAppMessageCenterCampaignsWith(_:withPersonalization:). To retrieve only the embedded campaigns, use embeddedMessageCenterCampaigns(personalization:):

let inAppCampaigns = SwrveSDK.inAppMessageCenterCampaignsWith(.portrait, withPersonalization: ["user_name": "Sam"])
let embeddedCampaigns = SwrveSDK.embeddedMessageCenterCampaigns(personalization: ["user_name": "Sam"])

To retrieve a single campaign by its ID, use messageCenterCampaign(withID:andPersonalization:), which returns nil if the campaign isn't currently eligible for the user:

if let campaign = SwrveSDK.messageCenterCampaign(withID: campaignID, andPersonalization: ["user_name": "Sam"]) {
SwrveSDK.showMessageCenter(campaign)
}

Checking for updates​

The Message Center list is a snapshot. To keep your UI in step with it, register a campaigns update listener and re-read the campaigns each time the listener is invoked. This API requires Swrve Android SDK 12.3.0 or later, or Swrve iOS SDK 10.11.0 or later.

The listener is invoked once after the SDK's initial content load attempt, whether or not anything changed, and again whenever content the SDK has fetched may have changed the campaigns. Invocations arrive in no guaranteed order, and the SDK does not compare the campaigns against what you last read, so let your own comparison decide whether to redraw.

Register the listener where you create the SDK instance. The first invocation is sent once and is never replayed, so a listener registered later may miss it.

SwrveSDK.campaignsUpdateListener(self) // where self conforms to SwrveCampaignsUpdateDelegate
...
func campaignsUpdated() {
let campaigns = SwrveSDK.messageCenterCampaigns()
// redraw your message center
}

Both SDKs hold the listener with a weak reference, so keep your own strong reference to it for as long as you want updates. A listener the SDK is the only holder of is released, after which callbacks stop arriving and nothing is reported. On Android, pass null to stop updates.

The listener reports SDK-driven changes only. Your own calls to markMessageCenterCampaignAsSeen and removeMessageCenterCampaign change what the getters return without invoking it, so re-read the campaigns after those calls as well.

One of the invocations follows the SDK's attempt to download campaign assets, which is when new campaigns normally become readable. A campaign is not listed until its assets are on the device, and an individual download can fail, so the invocation is not a guarantee that every campaign is present.


Campaign properties​

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

let campaigns = SwrveSDK.messageCenterCampaigns()
// Get campaign at some position in a table list
let campaign = campaigns[indexPath.row]
let id = campaign.ID
let name = campaign.name
let subject = campaign.messageCenterDetails?.subject
let dateStart = campaign.dateStart
let dateEnd = campaign.dateEnd
let priority = campaign.priority
let downloadDate = campaign.downloadDate()
// New message center details
let messageCenterSubject = campaign.messageCenterDetails?.subject
let messageCenterDescription = campaign.messageCenterDetails?.description
let accessibilityText = campaign.messageCenterDetails?.imageAccessibilityText
let messageCenterIconImage = campaign.messageCenterDetails?.image

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

ParameterDescription
IDA unique identifier.
nameThe name of the campaign, which defaults to Empty.
stateThe state of the campaign.
minDelayBetweenMsgsThe minimum interval between different campaign messages.
messageCenterA flag that indicates a message center campaign is sent from the message center.
subjectThe 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, React Native SDK 4.0.0, and Web SDK 3.0.0. The values are configurable through the campaign Content page, on the Message center details tab.

These parameters are exposed in the SwrveMessageCenterDetails object, and are currently only available for in-app message campaigns.

ParameterDescription
subjectThe variant-specific subject of the campaign that corresponds to the Subject value set in the campaign's Content page.
descriptionThe 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.
imageUrlThe personalized image URL. This is used for reference as the image is downloadable from the cache.
imageShaThe imageSha is available if the thumbnail image has been uploaded into the dashboard.
accessibilityTextThe alt text value provided for the image.

Note: If a campaign's message center details contain personalization that cannot be resolved for the current user — for example, a realtime user property with no value and no fallback — the SDK excludes that campaign from the results, rather than returning it with unresolved content. Set a fallback value for any personalization you use in message center details so the campaign is still returned when the property is unavailable.

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

ParameterDescription
dateEndThe end date of the campaign.
priorityThe priority of the campaign in relation to other message center campaigns.
downloadDateThe 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.
nameThe 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 detailsMessage Center API parameter
Subjectsubject
Descriptiondescription
Thumbnailimage - 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 textaccessibilityText

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:

let item = campaigns[0]
let subject = item?.messageCenterDetails?.subject

Campaign status​

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

let status = item.state.status

Possible values are:

ValueDescription
unseen = 1Campaign hasn't been seen by the user.
seen = 2Campaign has been seen at least once by the user.
deleted = 3Campaign has been deleted and won't appear again in the inbox.

Show campaign​

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

SwrveSDK.showMessageCenter(item)

Remove campaign​

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

SwrveSDK.removeMessageCenter(item)

General use case​

Use the let array: [SwrveCampaign] that the SwrveSDK.messageCenterCampaigns() call returns as a data provider to a table view, or custom view, for presentation in the app proper.

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.