From version 10.1.0 of the iOS and Android SDKs and version 4.1.0 of the React Native SDK we have implemented a rebranding of our classes. This will remove all references to 'Carnival' in favor of 'SailthruMobile'. This rebranding will help the SDKs to feel more consistent with the rest of the platform and we have also taken this opportunity to do some overdue restructuring of the main classes. This guide is designed to help walk you through the migration process.
iOS
Framework Updates
The frameworks have been renamed from
Carnival.framework
to
SailthruMobile.framework
and
CarnivalExtension.framework
to
SailthruMobileExtension.framework
.
Cocoapods
If you are using Cocoapods you will need to update to the new Pods:
# Previously
pod 'Carnival'
pod 'Carnival/Extension'
# Now
pod 'SailthruMobile'
pod 'SailthruMobile/Extension'
Carthage
If you are using Carthage the Github location will remain the same but you will need to change the linked frameworks to
SailthruMobile.framework
and
SailthruMobileExtension.framework
instead of the old 'Carnival' versions.
Carnival to SailthruMobile
The main class has been renamed from Carnival to SailthruMobile. It has also been restructured so that all the methods are instance methods rather than static methods. So for instance when calling
startEngine
:
iOS (Objective-C)
// Previously
[Carnival startEngine:@"Your_app_key"];
// Now
[[SailthruMobile new] startEngine:@"Your_app_key"];
iOS (Swift)
// Previously
Carnival.startEngine("Your_app_key")
// Now
SailthruMobile().startEngine("Your_app_key")
CarnivalMessageStream to STMMessageStream
The Message Stream class is now using the three letter prefix format recommended by Apple. We have opted to use STM for our prefix. The message stream methods have also been converted to instance methods rather than static methods. For example, to set a delegate:
iOS (Objective-C)
// Previously
[CarnivalMessageStream setDelegate:self];
// Now
[[STMMessageStream new] setDelegate:self];
iOS (Swift)
// Previously
CarnivalMessageStream.setDelegate(self)
// Now
STMMessageStream().setDelegate(self)
Note: You do not need to hold references to instances of the SailthruMobile or STMMessageStream classes; they can be created, used and released as you need them. The SDK will hold any delegates passed through them, so you only need to set them once on an instance of the class and you're good to go!
Carnival -> STM
All other classes have been renamed but will otherwise function in the same way as before:
Before |
After |
Carnival |
SailthruMobile |
CarnivalAttributes |
STMAttributes |
CarnivalContentItem |
STMContentItem |
CarnivalLogger |
STMLogger |
CarnivalMessage |
STMMessage |
CarnivalMessageStream |
STMMessageStream |
CarnivalNotificationCategory |
STMNotificationCategory |
CarnivalPurchase |
STMPurchase |
CarnivalPurchaseItem |
STMPurchaseItem |
Examples:
iOS (Objective-C)
// Previously
CarnivalAttributes *attributes = [[CarnivalAttributes alloc] init];
CarnivalPurchaseItem *item = [[CarnivalPurchaseItem alloc] initWithQuantity:2 title:@"Made Up Object" price:1234 itemId:@"2345" itemUrl:itemUrl];
CarnivalPurchase *purchase = [[CarnivalPurchase alloc] initWithPurchaseItems:@[ item ]];
// Now
STMAttributes *attributes = [[STMAttributes alloc] init];
STMPurchaseItem *item = [[STMPurchaseItem alloc] initWithQuantity:2 title:@"Made Up Object" price:1234 itemId:@"2345" itemUrl:itemUrl];
STMPurchase *purchase = [[STMPurchase alloc] initWithPurchaseItems:@[ item ]];
iOS (Swift)
// Previously
let attributes = CarnivalAttributes()
let item = CarnivalPurchaseItem(quantity: 2, title: "Made Up Object", price: 1234, itemId: "2345", itemUrl: url!)
// create purchase
let purchase = CarnivalPurchase(purchaseItems: [ item ])
// Now
let attributes = STMAttributes()
let item = STMPurchaseItem(quantity: 2, title: "Made Up Object", price: 1234, itemId: "2345", itemUrl: url!)
// create purchase
let purchase = STMPurchase(purchaseItems: [ item ])
Extension SDK
The Extension SDK has followed the same rebranding pattern, the main class has changed from
CarnivalExtension
to
SailthruMobileExtension
. The other classes have changed to the 'STM' prefix. The
SailthruMobileExtension
class has also had the
startEngine
and
getInstance
methods removed. You now only need to initialize an instance directly:
iOS (Objective-C)
// Previously
[CarnivalExtension startEngine:@"Your_app_key"];
CarnivalExtension *extension = [CarnivalExtension getInstanceForGroup:@"your.group.name"];
// Now
SailthruMobileExtension *extension = [[SailthruMobileExtension alloc] initWithAppKey:@"Your_app_key" groupName:@"your.group.name"];
iOS (Swift)
// Previously
CarnivalExtension.startEngine("Your_app_key")
let extension = CarnivalExtension.getInstanceForGroup("your.group.name")
// Now
let extension = SailthruMobileExtension(appKey: "Your_app_key", groupName: "your.group.name")
Android
Package Change
The Android SDK has been repackaged from
com.carnival.sdk
to
com.sailthru.mobile.sdk
. In your
build.gradle
file it will look like this:
// Previously
implementation 'com.carnival.sdk:carnival:10.1.0'
// Now
implementation 'com.sailthru.mobile.sdk:sailthru-mobile:10.1.0'
The Maven url will remain the same. Some of the classes have also been separated out into sub-packages. Below are the mappings for the package changes per class.
Enums:
Before |
After |
com.carnival.sdk.EventSource |
com.sailthru.mobile.sdk.enums.EventSource |
com.carnival.sdk.CarnivalImpressionType |
com.sailthru.mobile.sdk.enums.ImpressionType |
com.carnival.sdk.NotificationActionState |
com.sailthru.mobile.sdk.enums.NotificationActionState |
Interfaces:
Before |
After |
com.carnival.sdk.ContentIntentBuilder |
com.sailthru.mobile.sdk.interfaces.ContentIntentBuilder |
com.carnival.sdk.Logger |
com.sailthru.mobile.sdk.interfaces.Logger |
com.carnival.sdk.NotificationActionTappedListener |
com.sailthru.mobile.sdk.interfaces.NotificationActionTappedListener |
com.carnival.sdk.NotificationReceivedListener |
com.sailthru.mobile.sdk.interfaces.NotificationReceivedListener |
com.carnival.sdk.NotificationSilencer |
com.sailthru.mobile.sdk.interfaces.NotificationSilencer |
com.carnival.sdk.NotificationTappedListener |
com.sailthru.mobile.sdk.interfaces.NotificationTappedListener |
Model:
Before |
After |
com.carnival.sdk.AttributeMap |
com.sailthru.mobile.sdk.model.AttributeMap |
com.carnival.sdk.ContentItem |
com.sailthru.mobile.sdk.model.ContentItem |
com.carnival.sdk.Message |
com.sailthru.mobile.sdk.model.Message |
com.carnival.sdk.Purchase |
com.sailthru.mobile.sdk.model.Purchase |
com.carnival.sdk.PurchaseItem |
com.sailthru.mobile.sdk.model.PurchaseItem |
Main:
Before |
After |
com.carnival.sdk.MessageActivity |
com.sailthru.mobile.sdk.MessageActivity |
(new class) |
com.sailthru.mobile.sdk.MessageStream |
com.carnival.sdk.NotificationBundle |
com.sailthru.mobile.sdk.NotificationBundle |
com.carnival.sdk.CarnivalNotificationCategory |
com.sailthru.mobile.sdk.NotificationCategory |
com.carnival.sdk.NotificationConfig |
com.sailthru.mobile.sdk.NotificationConfig |
com.carnival.sdk.CarnivalNotificationExtender |
com.sailthru.mobile.sdk.NotificationExtender |
com.carnival.sdk.Carnival |
com.sailthru.mobile.sdk.SailthruMobile |
Carnival to SailthruMobile
The main class in the Android SDK has been renamed from
Carnival
to
SailthruMobile
. It has also been converted to using instance methods rather than static methods:
Android (Java)
// Previously
Carnival.startEngine("Your_app_key");
// Now
new SailthruMobile().startEngine("Your_app_key");
Android (Kotlin)
// Previously
Carnival.startEngine("Your_app_key")
// Now
SailthruMobile().startEngine("Your_app_key")
MessageStream
The message stream functionality has been moved out of the Carnival/SailthruMobile class into a new
MessageStream
class. The methods have also been convert from static methods to instance methods:
Android (Java)
// Previously
Carnival.getMessages(new Carnival.MessagesHandler() {
@Override
public void onSuccess(ArrayList messages) {
// Handle messages
}
@Override
public void onFailure(Error error) {
// Handle error
}
});
// Now
new MessageStream().getMessages(new MessageStream.MessagesHandler() {
@Override
public void onSuccess(ArrayList messages) {
// Handle messages
}
@Override
public void onFailure(Error error) {
// Handle error
}
});
Android (Kotlin)
// Previously
Carnival.getMessages(object : Carnival.MessagesHandler {
override fun onSuccess(messages: java.util.ArrayList?) {
// Handle messages
}
override fun onFailure(error: java.lang.Error?) {
// Handle error
}
})
// Now
MessageStream().getMessages(object : MessageStream.MessagesHandler {
override fun onSuccess(messages: ArrayList?) {
// Handle messages
}
override fun onFailure(error: Error?) {
// Handle error
}
})
The following methods, as well as their associated handlers and interfaces, have been moved to the MessageStream class:
Android (Java)
public void getUnreadMessageCount(MessageStream.MessageStreamHandler handler);
public void getMessages(MessageStream.MessagesHandler messagesHandler);
public void getMessage(String messageId, MessageStream.MessageStreamHandler messageHandler);
public void registerMessageImpression(ImpressionType type, Message message);
public void setMessageRead(Message message, MessageStream.MessagesReadHandler handler);
public void setMessagesRead(List messages, MessageStream.MessagesReadHandler handler);
public void deleteMessage(Message message, MessageStream.MessageDeletedHandler handler);
public void setOnInAppNotificationDisplayListener(MessageStream.OnInAppNotificationDisplayListener listener);
Android (Kotlin)
fun getUnreadMessageCount(handler: MessageStreamHandler<Int?>?)
fun getMessages(messagesHandler: MessagesHandler?)
fun getMessage(messageId: String?, messageHandler: MessageStreamHandler?)
fun registerMessageImpression(type: ImpressionType, message: Message?)
fun setMessageRead(message: Message?, handler: MessagesReadHandler?)
fun setMessagesRead(messages: List<Message?>?, handler: MessagesReadHandler?)
fun deleteMessage(message: Message?, handler: MessageDeletedHandler?)
fun setOnInAppNotificationDisplayListener(listener: OnInAppNotificationDisplayListener)
Note: As with the iOS SDK, you do not need to hold references to instances of the SailthruMobile or MessageStream classes; you can create, use and release them as you need them. The SDK will persist any interface implementations passed in via instances of these classes.
Resources
Any resources named 'carnival_*' have been renamed to 'st_*'.
Nullability
We have taken the opportunity to tighten up the nullability in several of the exposed classes and interfaces as part of the migration. If you experience any build issues as a result of interface methods not being implemented, you should double check that the nullability of the parameters in your implementation matches that of the new SDK interfaces.
React Native
Package
The package name has been changed from 'react-native-carnival' to 'react-native-sailthru-mobile', you can update this in your project's package.json:
// Previously
"dependencies": {
//...
"react-native-carnival": "^4.1.0",
//...
},
// Now
"dependencies": {
//...
"react-native-sailthru-mobile": "^4.1.0",
//...
},
Carnival to SailthruMobile
The native React Native classes have been renamed:
Android
RNCarnivalModule.java -> RNSailthruMobileModule.java
RNCarnivalPackage.java -> RNSailthruMobilePackage.java
iOS
RNCarnival.h -> RNSailthruMobile.h
RNCarnival.m -> RNSailthruMobile.m
RNCarnivalBridge.h -> RNSailthruMobileBridge.h
RNCarnivalBridge.m -> RNSailthruMobileBridge.m
You will need to copy the new rebranded classes into your project from
node_modules/react-native-sailthru-mobile
. Once you have done this you will need to change your Podfile to point to the new
SailthruMobile
pod rather than
Carnival
in order for your app to compile. See the iOS
Cocoapods section for details. You should either use the SailthruMobile bridge/module or the Carnival bridge/module in your app. The
index.js
file will pick up whichever bridge you are exporting and populate it accordingly.
Note: You should have
either RNCarnival and RNCarnivalBridge
or RNSailthruMobile and RNSailthruMobileBridge in your app. If you are using the RNCarnival classes you will need to use the Carnival pod in your Podfile. If you are using the RNSailthruMobile classes you will need to use the SailthruMobile pod.