Swrve Message Center API
Accessing the API
iOS - Swift
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.
iOS - Objective-C
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 SwrveCampaign
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 - Swift
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
iOS - Objective-C
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.messageCenterDetails.subject; 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();
Unity
// Example get message center campaign and properties. List<SwrveBaseCampaign> campaigns = SwrveComponent.Instance.SDK.GetMessageCenterCampaigns(); SwrveBaseCampaign campaign = campaigns[0]; int ID = campaign.Id; String name = campaign.Name; String subject = campaign.Subject; // (this is deprecated, use new MessageCenterSubject) Date dateStart = campaign.StartDate; Date dateEnd = campaign.EndDate; int priority = campaign.getPriority; Date downloadDate = campaign.DownloadDate; String messageCenterSubject = campaign.MessageCenterDetails.Subject; String messageCenterDescription = campaign.MessageCenterDetails.Description; String accessibilityText = campaign.MessageCenterDetails.ImageAccessibilityText; Texture2d 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:
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.
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 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 - Swift
let item = campaigns[0] let subject = item?.messageCenterDetails?.subject
iOS - Objective-C
SwrveCampaign *item = (SwrveCampaign*)[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 - Swift
let status = item.state.status
Possible values are:
Value | Description |
---|---|
unseen = 1 | Campaign hasn’t been seen by the user. |
seen = 2 | Campaign has been seen at least once by the user. |
deleted = 3 | Campaign has been deleted and won’t appear again in the inbox. |
iOS - Objective-C
SwrveCampaignStatus status = item.state.status;
Possible values are:
Value | Description |
---|---|
SwrveCampaignStatusUnseen = 1 | Campaign hasn’t been seen by the user. |
SwrveCampaignStatusSeen = 2 | Campaign has been seen at least once by the user. |
SwrveCampaignStatusDeleted = 3 | 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 - Swift
SwrveSDK.showMessageCenter(item)
iOS - Objective-C
[SwrveSDK 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 - Swift
SwrveSDK.removeMessageCenter(item)
iOS - Objective-C
[SwrveSDK removeMessageCenterCampaign:item];
Android
SwrveSDK.removeMessageCenterCampaign(item);
Unity
SwrveComponent.Instance.SDK.RemoveMessageCenterCampaign(item);
General use case
iOS - Swift
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.
iOS - Objective-C
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.