Retrieving messages for a user

Sailthru Mobile Messages have several properties which you should familiarize yourself with before building a stream or displaying messages.

Property name

Can be blank

Description

Plugin SDK name

title

No

The title of the message

title

text

Yes

The body of the message

text

htmlText

Yes

The body of the message rendered into an HTML string

html_text

imageURL

Yes

A URL pointing to an image

card_image_url

videoURL (iOS)
mediaURL (Android)

Yes

A URL pointing to a video

card_media_url

URL (iOS)
contentURL (Android)

Yes

A URL pointing to a generic page or resource

url

read

No

Whether or not the message has been read

is_read

createdAt

No

The date and time when the message was created

created_at

messageID

No

An alphanumeric unique ID for the message

id

attributes

Yes

A dictionary of string keys and values set on the message

attributes

You can use the CarnivalMessageStream interface to asynchronously request an array of messages for that device. Once returned you can use these objects to construct your own Message Stream interface.

//On iOS, using Objective-C

[CarnivalMessageStream messages:^(NSArray *messages, NSError *error) {
    //Do something with the array of messages
}];
CarnivalMessageStream.messages { (theMessages, anError) -> Void in
    //Do something with the array of messages
}
Carnival.getMessages(new Carnival.MessagesHandler() {
  @Override
  public void onSuccess(ArrayList<Message> messages) {
    //Do something with the array of messages
  }

  @Override
  public void onFailure(Error error) {
  }
});
Carnival.messages( function callback(data) {
    //Do something with the array of messages
  }, function errorHandler(err) {
    //Do something with the error
  }
);
Carnival.OnMessagesReceivedEvent += (object sender, CarnivalMessagesReceivedEvent e) => {
    //Do something with e.messages 
};
Carnival.GetMessages();

Showing full screen content

After a user taps on message, you can can show the full screen content with the following method.

[CarnivalMessageStream presentMessageDetailForMessage:self.latestMessage];
CarnivalMessageStream.presentDetailForMessage(message)
Intent i = new Intent(this, MessageActivity.class);
i.putExtra(Carnival.EXTRA_PARCELABLE_MESSAGE, message);
startActivity(i);
Carnival.presentMessageDetail(message)
Carnival.ShowMessageDetail (message);

Supporting Impressions

In order to support impression analytics from your Message Stream you will need to ensure you register an impression event for relevant messages when your Message Stream is shown to the user.

Sailthru Mobile supports tracking three types of impressions:

  • In App Notification Impression
  • Message Viewed in Stream Impression
  • Message Viewed in Detail Impression

If you didn't customize Sailthru Mobile's default in-app notification or full-screen detail user interface, there is no need to register an impression event as these will be captured automatically.

[CarnivalMessageStream registerImpressionWithType:
    CarnivalImpressionTypeInAppNotificationView forMessage:message];

[CarnivalMessageStream registerImpressionWithType:
    CarnivalImpressionTypeStreamView forMessage:message];

[CarnivalMessageStream registerImpressionWithType:
    CarnivalImpressionTypeDetailView forMessage:message];
CarnivalMessageStream.registerImpressionWithType(
    CarnivalImpressionType.InAppNotificationView, forMessage: message)
    
CarnivalMessageStream.registerImpressionWithType(
    CarnivalImpressionType.StreamView, forMessage: message)        
    
CarnivalMessageStream.registerImpressionWithType(
    CarnivalImpressionType.DetailView, forMessage: message)
Carnival.registerMessageImpression(CarnivalImpressionType.IMPRESSION_TYPE_IN_APP_VIEW, message);
Carnival.registerMessageImpression(CarnivalImpressionType.IMPRESSION_TYPE_STREAM_VIEW, message);
Carnival.registerMessageImpression(CarnivalImpressionType.IMPRESSION_TYPE_DETAIL_VIEW, message);
Carnival.registerImpression(Carnival.MessageImpressionType.InAppView, message);
Carnival.registerImpression(Carnival.MessageImpressionType.StreamView, message);
Carnival.registerImpression(Carnival.MessageImpressionType.DetailView, message);
Carnival.RegisterImpression(message, CarnivalImpressionType.InAppNotificationView); 
Carnival.RegisterImpression(message, CarnivalImpressionType.StreamView); 
Carnival.RegisterImpression(message, CarnivalImpressionType.DetailView);

Marking As Read

You might also want to track which messages have been read or not with your Message Stream, so you could show a number badge or unread indicator. You can mark a collection or single message as read.

[CarnivalMessageStream markMessageAsRead:message withResponse:NULL];
// or
[CarnivalMessageStream markMessagesAsRead:@[message1, message2, message3] withResponse:NULL];
CarnivalMessageStream.markMessageAsRead(message, withResponse: nil)
//or 
CarnivalMessageStream.markMessagesAsRead(messages, withResponse: nil)
Carnival.setMessageRead(message, messageReadHandler);
// or 
Carnival.setMessagesRead(messageList, messageReadHandler);
Carnival.markMessageAsRead(
  function callback(data) {
    console.log('markMessageAsRead successfully returned');
  },
  function errorHandler(err) {
    console.log('markMessageAsRead error: ' + err);
  },
  messageJSON
);
// or
Carnival.markMessagesAsRead(
  function callback(data) {
    console.log('markMessagesAsRead successfully returned');
  },
  function errorHandler(err) {
    console.log('markMessagesAsRead error: ' + err);
  },
  data
);
Carnival.OnErrorEvent += (object sender, CarnivalErrorEventArgs e) => {
  Debug.Log (e.ErrorDescription);
};
Carnival.MarkMessageAsRead(message);

Deleting Messages

Messages can be deleted from a user's stream.

[CarnivalMessageStream removeMessage:message withResonse:^(NSError *error) {
    //Do something with any errors
}];
CarnivalMessageStream.removeMessage(message, withResponse: nil)
Carnival.deleteMessage(message, messageDeletedHandler);
Carnival.removeMessage(
  function callback(data) {
    console.log('removeMessage successfully returned');
  },
  function errorHandler(err) {
    console.log('removeMessage returned error: ' + err);
  },
  messageJSON
);
Carnival.OnErrorEvent += (object sender, CarnivalErrorEventArgs e) => {
  Debug.Log (e.ErrorDescription);
};
Carnival.RemoveMessage (message)

Custom In-App Message Notifications

You can customize the look and feel of In-App Message Notifications by following the instructions here.

📘

While testing, you can reinstall the app to get a fresh set of messages, as impressions and deletions do not persist between same-device installs.

Custom Message Attributes

You can use a dictionary or hash of custom attributes to further customize the display of your message stream and messages. These may include:

  • Pinned messages
  • Categories on the Stream
  • Custom CTAs or card design

HTML Support

Since you can include markdown in messages sent via Sailthru Mobile, we expose this markdown rendered into HTML with the htmlText property.

bodyLabel.attributedText = [[NSAttributedString alloc] initWithData:[message.htmlText dataUsingEncoding:NSUTF8StringEncoding]
                            options:@{NSDocumentTypeDocumentAttribute: NSHTMLTextDocumentType,
                                 NSCharacterEncodingDocumentAttribute: @(NSUTF8StringEncoding)}
                 documentAttributes:nil error:nil];
do {
    try bodyLabel.attributedText = NSAttributedString.init(
        data: message.htmlText.dataUsingEncoding(NSUnicodeStringEncoding)!,
        options: [
            NSDocumentTypeDocumentAttribute: NSHTMLTextDocumentType,
            NSCharacterEncodingDocumentAttribute: NSUTF8StringEncoding
        ],
        documentAttributes: nil);
} catch {
    
}
TextView textView = ...;
textView.setText(Html.fromHtml(message.getHtmlText()));

HTML Text will always be populated, even if no markdown was used in the original message.

Unread messages count

You can get the number of unread messages from the SDK, without the need to request a message stream and iterate over each individual message.

Sailthru Mobile will deliver an in-app message in two occasions: after launch with app is in foreground or if the user has the app open and the device has a valid push token. Therefore, you may want to obtain the unread message count when the user opens the app, or when it becomes active after being backgrounded.

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    [CarnivalMessageStream unreadCount:^(NSUInteger unreadCount, NSError * _Nullable error) {
        // Add your logic here
    }];
}
func applicationDidBecomeActive(_ application: UIApplication) {
    CarnivalMessageStream.unreadCount { (count, error) in
        // Add your logic here
    }
}
public class MainActivity extends AppCompatActivity {
    @Override
    protected void onResume() {
        super.onResume();
        int unreadCount = Carnival.getUnreadMessageCount();

        // Add your logic here
    }
}
Carnival.unreadCount(
  function callback(unreadCount) {
    console.log('unreadCount succesfully returned: ' + unreadCount);
  },
  function errorHandler(err) {
    console.log('unreadCount error: ' + err);
  }
);

// Additionally, we expose an event named 'unreadcountdidchange'. You can attach a listener to perform an action every time the unread count changes.

document.addEventListener('unreadcountdidchange', function(event) {
  console.log('unreadCountChanged: ' + event.detail.unreadCount);
});