Migrating to Marigold

If you are migrating from another push provider (or from your existing homegrown solution), you may want to import existing push enabled devices into Marigold. 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 Marigold 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 Marigold 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 Marigold 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 Marigold, you can still import device tokens from users who have yet to upgrade to your Marigold 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 Marigold 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 Marigold integration, in close proximity to the release of your Marigold 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 Marigold 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 Marigold, 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 Marigold. 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 Marigold 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 Marigold SDK, we will generate a new install within Marigold. 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 Marigold SDK, the imported anonymous user will be uninstalled and re-installed as a known Marigold 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 Marigold, 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 Marigold, 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 Marigold. This will give you the ability to target users with push notifications from Marigold 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 Marigold 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 Marigold platform.

let attributes = MARAttributes();
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")

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

MARAttributes *attributes = [[MARAttributes 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"];
[[Marigold 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 EngageBySailthru().setAttributes(attributes, new EngageBySailthru.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))
EngageBySailthru().setAttributes(attributes, object : EngageBySailthru.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 Marigold 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 Marigold.