If you are migrating from another push provider (or from your existing homegrown solution), you may want to import existing push enabled devices into Sailthru Mobile. This can be done in multiple ways. This guide will help you understand the best path forward based on your app strategy and installed base.

Migrate users over time

If your timeframe for release allows so, you can migrate users over time. In this scenario, you implement Sailthru Mobile alongside your current provider. This way, you can start registering devices into the platform and even message them using both push notifications and in-app messages.

This approach allows you to import only active app users while giving you the advantage of tracking up-to-date information about the user's activity and behaviour. You can start creating audiences based on the attributes Sailthru Mobile tracks out of the box, and you can also track custom events and user attributes.

Since both providers share the same device token and push credentials, you can also use Sailthru Mobile to message these users, or use a combination of both platforms until your cut off date from your legacy provider.

When you're ready to fully migrate to Sailthru Mobile, you can still import device tokens from users who have yet to upgrade to your Sailthru Mobile enabled app. This way, you can still send these users a push notification, for example to invite them to update the app. For more information, see Force Update and Token Migration later on this page.

Force update

If you wish, you can force all the users to update to a new version of the app. This is a common scenario for app developers releasing a new major release of their app. In this case, people opening a previous version of the app will receive a message prompting them to go to the App Store or Google Play to download the most updated version. This app migration is always communicated to the user at least a few weeks in advance.

This approach gives you a clear implementation path while reducing the fragmentation of app versions you will need to maintain. This scenario is ideal when you are releasing a major update, for example in conjunction with a UX refresh or when adding key functionalities to your app.

Token migration

Token migration gives you the continuity to send Sailthru Mobile push notifications to devices registered with another push provider. Push tokens are imported and assigned to temporary, anonymous devices. You can send push notifications to these devices as long as the push token is valid.

We highly recommend to carry over existing tokens as the last step of your Sailthru Mobile integration, in close proximity to the release of your Sailthru Mobile enabled app to the stores.

📘
Push notifications only
Importing tokens will allow you to send push notifications only. You can start sending in-app messages and in-app notifications once your users update to the Sailthru Mobile SDK.

🚧
iOS: Devices with multiple valid push tokens
Apple can issue multiple push tokens for the same devices, and some of all of them can be valid and active at the same time. This means that imported devices can receive multiple push notifications. To mitigate this undesired effect, you should use a collapse_key for all of your push notifications until all the devices are fully installed. For more details, see Updating Pushes.

How does it work

In order to migrate and import push tokens into Sailthru Mobile, you will need to provide us with a list of existing push tokens. We can also import any custom attributes related to this push token, according to our format. As part of the import process, we also add a custom attribute to each device indicating that it was imported. Commonly, developers will pass us a CSV file with tokens and attributes.

Importing these push tokens will create anonymous devices inside Sailthru Mobile. These devices will have a Device ID, but will not report platform, model or location. They will also be reported as installed on the same day as import.

👍
Plan ahead
Our team will need to review your existing token exports, and you will need to review and approve the import. Allow additional time in your project plan to make sure you have plenty of leeway during this process.

Targeting imported devices

You will effectively be able to target imported devices in the usual way through the audience builder, based on the custom attributes that were imported. To proceed, create a new audience using Audience Builder and select the custom attributes that were imported. You can also use the app install date as an attribute, if you provided valid values for it.

If you integrated the Sailthru Mobile SDK and released your app, you can send push notifications and in-app messages. Users who haven't upgraded the app can only receive push notifications.

Generating a new install from an imported device

As soon as the user updates the app to a version with the Sailthru Mobile SDK, we will generate a new install within Sailthru Mobile. Where possible, we attempt to uninstall the imported device, so that it will no longer be targetable and it will not appear in the Device Log.

🚧
Please keep in mind that your app uninstalls will look a bit off for the first month or so that the apps are live, and this shouldn't be a cause of concern. As imported users upgrade to the version of your apps with the Sailthru Mobile SDK, the imported anonymous user will be uninstalled and re-installed as a known Sailthru Mobile device. The customer won't notice any difference, providing that you are carrying over their currently set attributes as they update to the new version.

Migrating attributes from the app

When this happens, you will need to migrate any custom attributes associated with the imported device to the new install. We suggest you add logic to set an attribute map on your new app's first run. Here's a suggested flow:
Before migrating to Sailthru Mobile, create a copy of the attributes you are planning to migrate, and make sure they are mapped to a user or device. You can store a copy of the attributes on the cloud, on your servers, on a database/CRM, on local storage, or on any other location that allows you to effectively map attributes to a device. This needs to happen before you move your app to Sailthru Mobile, and it will require to submit your app to the app store.

Here's an example on how to store user preferences into the app's local storage:

UserDefaults.standard.set("Daniele", forKey: "first_name")
UserDefaults.standard.set("gold", forKey: "loyalty_tier")
UserDefaults.standard.set(1337, forKey: "points")

NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
[defaults setObject:@"Daniele" forKey:@"first_name"];
[defaults setObject:@"gold" forKey:@"loyalty_tier"];
[defaults setInteger:1337 forKey:@"points"];
[defaults synchronize];

SharedPreferences preferences = getSharedPreferences("LocalAttributes", Context.MODE_PRIVATE);
SharedPreferences.Editor editor = preferences.edit();
editor.putString("first_name", "Daniele");
editor.putString("loyalty_tier", "gold");
editor.putInt("points", 1337);
editor.commit();

val preferences = getSharedPreferences("LocalAttributes", Context.MODE_PRIVATE)
val editor = preferences.edit()
editor.putString("first_name", "Daniele")
editor.putString("loyalty_tier", "gold")
editor.putInt("points", 1337)
editor.commit()

After this, start importing your tokens and attributes into Sailthru Mobile. This will give you the ability to target users with push notifications from Sailthru Mobile while still retaining the ability to use the platform you're migrating from. You will not be able to use in-app messages or in-app notifications just yet.

In the meantime, integrate the Sailthru Mobile SDK in your app. Add logic so that when the app start, it will retrieve your previously stored attributes, then create an attribute map to send attributes back to the Sailthru Mobile platform.

let attributes = STMAttributes();
attributes.setString(UserDefaults.standard.string(forKey: "first_name"), forKey: "first_name")
attributes.setString(UserDefaults.standard.string(forKey: "loyalty_tier"), forKey: "loyalty_tier")
attributes.setInteger(UserDefaults.standard.integer(forKey: "points"), forKey: "loyalty_tier")

SailthruMobile().setAttributes(attributes) { (error) in
	if (error != nil) {
		print("An error occurred: \(error)")
	}
}

STMAttributes *attributes = [[STMAttributes alloc] init];
[attributes setString:[defaults objectForKey:@"first_name"] forKey:@"first_name"];
[attributes setString:[defaults objectForKey:@"loyalty_tier"] forKey:@"loyalty_tier"];
[attributes setInteger:[defaults integerForKey:@"points"] forKey:@"points"];
[[SailthruMobile new] setAttributes:attributes withResponse:^(NSError * _Nullable error) {
    if (error) {
        NSLog(@"Error - %@", [error debugDescription]);
        // Add retry logic (optional)
    }
}];

SharedPreferences preferences = getSharedPreferences("LocalAttributes", Context.MODE_PRIVATE);
AttributeMap attributes = new AttributeMap();
attributes.putString("first_name", preferences.getString("first_name", ""));
attributes.putString("loyalty_tier", preferences.getString("loyalty_tier", ""));
attributes.putInt("points", preferences.getInt("points", 0));
new SailthruMobile().setAttributes(attributes, new SailthruMobile.AttributesHandler() {
    @Override
    public void onSuccess() {
        // Add your confirmation logic, or clean up your SharedPreferences
    }

    @Override
    public void onFailure(Error error) {
        // Add your error handling logic, such as a retry interval.
    }
});

val preferences = getSharedPreferences("LocalAttributes", Context.MODE_PRIVATE)
val attributes = AttributeMap()
attributes.putString("first_name", preferences.getString("first_name", ""))
attributes.putString("loyalty_tier", preferences.getString("loyalty_tier", ""))
attributes.putInt("points", preferences.getInt("points", 0))
SailthruMobile().setAttributes(attributes, object : SailthruMobile.AttributesHandler {
  override fun onSuccess() { // Add your confirmation logic, or clean up your SharedPreferences
  }

  override fun onFailure(error: Error?) { // Add your error handling logic, such as a retry interval.
  }
})

This will generate a new device with the previously set attributes, along with automatically tracked attributes such as device platform and model. It will also enable the user to also receive in-app messages and in-app notifications.

You can also choose to integrate Sailthru Mobile ahead of time without registering for push notifications. This way, you can start registering devices and sending attributes while still using your current push provider. When you're ready, you can have your app register for push notifications with Sailthru Mobile.