Build a Message Stream

Retrieving Messages for a User

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 MessageStream 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.

iOS (Objective-C)

//On iOS, using Objective-C

[[STMMessageStream new] messages:^(NSArray *messages, NSError *error) {
  //Do something with the array of messages
}];

iOS (Swift)

STMMessageStream().messages { (theMessages, anError) -> Void in
  //Do something with the array of messages
}

Android (Java)

new MessageStream().getMessages(new MessageStream.MessagesHandler() {
  @Override
  public void onSuccess(ArrayList messages) {
    //Do something with the array of messages
  }

  @Override
  public void onFailure(Error error) {
  }
});

Android (Kotlin)

MessageStream().getMessages(object : MessageStream.MessagesHandler {
    override fun onSuccess(messages: ArrayList?) {
      //Do something with the array of messages
    }

    override fun onFailure(error: Error?) {
    }
})

React Native (JavaScript)

SailthruMobile.getMessages().then(messages => {
  //Do something with the array of messages
}).catch(e => {
  //Handle error
});

Show Full Screen Content

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

iOS (Objective-C)

[[STMMessageStream new] presentMessageDetailForMessage:self.latestMessage];

iOS (Swift)

STMMessageStream().presentDetailForMessage(message)

Android (Java)

Intent intent = MessageActivity.intentForMessage(context, bundle, message);
startActivity(intent);

Android (Kotlin)

val intent = MessageActivity.intentForMessage(context, bundle, message)
startActivity(intent)

React Native (JavaScript)

SailthruMobile.presentMessageDetail(message);

Support 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.

iOS (Objective-C)

[[STMMessageStream new] registerImpressionWithType:
    STMImpressionTypeInAppNotificationView forMessage:message];

[[STMMessageStream new] registerImpressionWithType:
    STMImpressionTypeStreamView forMessage:message];

[[STMMessageStream new] registerImpressionWithType:
    STMImpressionTypeDetailView forMessage:message];

iOS (Swift)

STMMessageStream().registerImpressionWithType(.inAppNotificationView, forMessage: message)
    
STMMessageStream().registerImpressionWithType(.streamView, forMessage: message)        
    
STMMessageStream().registerImpressionWithType(.detailView, forMessage: message)

Android (Java)

new MessageStream().registerMessageImpression(ImpressionType.IMPRESSION_TYPE_IN_APP_VIEW, message);

new MessageStream().registerMessageImpression(ImpressionType.IMPRESSION_TYPE_STREAM_VIEW, message);

new MessageStream().registerMessageImpression(ImpressionType.IMPRESSION_TYPE_DETAIL_VIEW, message);

Android (Kotlin)

MessageStream().registerMessageImpression(ImpressionType.IMPRESSION_TYPE_IN_APP_VIEW, message)

       MessageStream().registerMessageImpression(ImpressionType.IMPRESSION_TYPE_STREAM_VIEW, message)

       MessageStream().registerMessageImpression(ImpressionType.IMPRESSION_TYPE_DETAIL_VIEW, message)

React Native (JavaScript)

SailthruMobile.registerMessageImpression(SailthruMobile.MessageImpressionType.InAppView, message);

SailthruMobile.registerMessageImpression(SailthruMobile.MessageImpressionType.StreamView, message);

SailthruMobile.registerMessageImpression(SailthruMobile.MessageImpressionType.DetailView, message);

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.

iOS (Objective-C)

[[STMMessageStream new] markMessageAsRead:message withResponse:NULL];
// or
[[STMMessageStream new] markMessagesAsRead:@[message1, message2, message3] withResponse:NULL];

iOS (Swift)

STMMessageStream().markMessageAsRead(message, withResponse: nil)
//or 
STMMessageStream().markMessagesAsRead(messages, withResponse: nil)

Android (Java)

new MessageStream().setMessageRead(message, messageReadHandler);
// or 
new MessageStream().setMessagesRead(messageList, messageReadHandler);

Android (Kotlin)

MessageStream().setMessageRead(message, messageReadHandler)
// or 
MessageStream().setMessagesRead(messageList, messageReadHandler)

React Native (JavaScript)

SailthruMobile.markMessageAsRead(message).then(result => {
  // Handle success
}).catch(e => {
  // Handle error
});

Delete Messages

Messages can be deleted from a user's stream.

iOS (Objective-C)

[[STMMessageStream new] removeMessage:message withResonse:^(NSError *error) {
  //Do something with any errors
}];

iOS (Swift)

STMMessageStream().removeMessage(message, withResponse: nil)

Android (Java)

new MessageStream().deleteMessage(message, messageDeletedHandler);

Android (Kotlin)

MessageStream().deleteMessage(message, messageDeletedHandler)

React Native (JavaScript)

SailthruMobile.removeMessage(message).then(result => {
  // Handle success
}).catch(e => {
  // Handle error
});

Custom In-App Notifications

You can customize the look and feel of In-App Message Notifications by following the instructions here. Note: 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.

iOS (Objective-C)

bodyLabel.attributedText = [[NSAttributedString alloc] initWithData:[message.htmlText dataUsingEncoding:NSUTF8StringEncoding]
                            options:@{NSDocumentTypeDocumentAttribute: NSHTMLTextDocumentType,
                                 NSCharacterEncodingDocumentAttribute: @(NSUTF8StringEncoding)}
                 documentAttributes:nil error:nil];

iOS (Swift)

do {
    try bodyLabel.attributedText = NSAttributedString.init(
        data: message.htmlText.dataUsingEncoding(NSUnicodeStringEncoding)!,
        options: [
            NSDocumentTypeDocumentAttribute: NSHTMLTextDocumentType,
            NSCharacterEncodingDocumentAttribute: NSUTF8StringEncoding
        ],
        documentAttributes: nil);
} catch {
    
}

Android (Java)

TextView textView = ...;
textView.setText(Html.fromHtml(message.getHtmlText()));

Android (Kotlin)

val textView = ...
textView.text = Html.fromHtml(message.htmlText, Html.FROM_HTML_MODE_COMPACT)

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.

iOS (Objective-C)

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    [[STMMessageStream new] unreadCount:^(NSUInteger unreadCount, NSError * _Nullable error) {
        // Add your logic here
    }];
}

iOS (Swift)

func applicationDidBecomeActive(_ application: UIApplication) {
    STMMessageStream().unreadCount { (count, error) in
        // Add your logic here
    }
}

Android (Java)

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onResume() {
        super.onResume();
        new MessageStream().getUnreadMessageCount(new MessageStream.MessageStreamHandler() {
            @Override
            public void onSuccess(Integer value) {
                // Handle count
            }

            @Override
            public void onFailure(@Nullable Error error) {
                // Handle error
            }
        });

        // Add your logic here
    }
}

Android (Kotlin)

class MainActivity : AppCompatActivity() {
    override fun onResume() {
        super.onResume()
        MessageStream().getUnreadMessageCount(object: MessageStream.MessageStreamHandler<Int?> {
            override fun onSuccess(count: Int?) {
                // Handle count
            }

            override fun onFailure(error: Error?) {
               // Handle error 
            }
        })

        // Add your logic here
    }
}

React Native (JavaScript)

SailthruMobile.getUnreadCount().then(function(count) {
  // Handle unread message count
}, function(e){
  // Handle error
});