In this section:

Importing Previous Push Audiences to Mobile Engage

Contents:

Before you start

The purpose of this import process is to upload your existing mobile app users as anonymous Emarsys contacts. We do not associate them with any device at this stage - they are all treat as logged-out (anonymous) Mobile Engage contacts.

As soon as an app user opens the app (provided you have implement the appLogin function each time the app opens, as recommended during setup), or logs in, we will automatically identify that contact with the device they use.

This is currently not a self-service import; it can only be made with the help of an Emarsys Implementation Consultant.

Why are my app users imported anonymously?

At Emarsys we take data privacy very seriously, and do our best to prevent our customers from ending up in a situation where they might be vulnerable to litigation. We therefore do not let you send personalized content to app users before we have confirmed their identity ourselves.

All new contacts who download or log in to the app after the import will of course be identified immediately.

What if I want to engage with these contacts immediately?

You can, but you can't personalize your content for contacts who have not yet been identified. All the imported contacts are immediately available for mobile Engage segments and you can launch your first campaign straight away.

How can I speed up the identification process?

We recommend that you create a segment out of your imported contacts and target them with campaigns aimed specifically at opening the app. An update notification of your new version is a good example of such a campaign. At the bottom of this article you can find some easy instructions on how to set up an automated program that will take care of this for you.

Where do we store device data in Mobile Engage?

Mobile Engage does not store device data in Emarsys contact fields, because an Emarsys database contact can have multiple devices, so we created a separate database for that. We call it the Mobile Engage database. This database stores "application installs", in other words, which contact installed which application, on which device - and the details of the device such as device language, timezone, platform, operating system version and the app version.

It is this database that is segmented when you create a Mobile Engage segment.

Requirements for the import

The import is always made through a *.csv file. There are required fields which the import must contain in order to succeed, and recommended fields that will help you integrated your mobile app strategy with the other channels offered by Emarsys.

Required fields

The following fields are required for the import to be successful.

platform

The platform data should be provided in lower case.

Column name
 Data source
 Sample
platform Customer ios
android

hardware_id

This is a unique string to identify the device. This is IDFA/IDFV on iOS and ANDROID_ID on Android. We use IDFA as default, but when ad tracking is limited and IDFA is not available, we fall back to IDFV.

The format is hexadecimal characters:

  • ios: 8-4-4-4-12 characters
  • android: 16 characters
Column name
 Data source
 Sample
hardware_id Customer ios: 8E3FD635-7D9C-497E-AB84-1D61BED61F4B
android: cc008ce8c7ab4a4b

push_token

This is a unique token, often referred to as "device token", generated by Google or Apple. It is linked to an application where push notifications have been accepted. Use getPushToken on both iOS and Android.

The format is hexadecimal characters:

  • ios: 64 characters
  • android: 152 characters
Column name
 Data source
 Sample
push_token Customer
 ios: 3675aae260c8b9523858339c14a55503dd1a6074e13e8d4a0b7934146edcc59d
android: ekWsQJonuhI:APA91bF-eL7ZB_uxCoFv11jjnChaEDduH0PBR3uV_
7zjVnVnTjlwLAuOzx2FaV_JHXFtdpGQ44KjNUg_
Yb96spCtNewYbMRdj7gvv8pqdr4v3HsIqnT3vx_
RTBs1DIB1X62TDRt5bThS

Sending is not possible without a push_token. If a customer cannot include either a valid hardware_id or a valid push_token, the device data will not be imported.

Please make the effort to clean your data and remove and invalid tokens before importing this data into Emarsys. Invalid tokens will also lower your delivery rates and removing then in Emarsys will delay completion of your Mobile Engage onboarding.

application_code

This is a code generated by Emarsys for each of your apps. You can find it in your Emarsys account on the Mobile Engage, Apps tab, in the App ID column.

The application_code is the same for every row.

Column name
 Data source
 Sample
application_code Emarsys
 ABCD1-9876E

If this is not included in the import file, it can be added by Emarsys during the import, but including it in the import file will speed up the process.

Making the import

Once you have prepared your .csv file as per the instructions above, send this to your Emarsys Implementation Consultant and they will perform the import for you. 

They will also open a Zendesk support ticket to Technical Client Services where you can follow the progress of the import.

Troubleshooting

The relationship between push_token, hardware_id and the contact_field_value

The importance of the relationship between the push_token, the hardware_id and the contact_field_value lies in the different possible scenarios for import:

There is no push_token, but we have a hardware_id OR contact_field_value

In this case, import can be carried out, since we know the user, we know the device and we can contact the users by other means to make them accept push messages.

There is no hardware_id, but we have a push_token and the contact_field_value

In this case, import can be carried out, since when the device later appears, we can fill in the hardware_id based on the push_token, making the contact data fully functional.

There is no contact_field_value, but we have a push_token and a hardware_id

In this case an anonymous contact will be created and used for messaging.

There is no push_token and no contact_field_value, but we have a hardware_id

In this case, we cannot send messages since we do not know who the device belongs to. An anonymous contact may be created but it is of no use, since we cannot guarantee that sending would be ever possible. 

Carrying out the import is not recommended.

Identifying your anonymous app users

Once you have successfully imported your previous audience, you should immediately try to get those contacts to open or log in to your app so that we can confirm their identity. The easiest way to do this is via an Automation Center program, for example one that sends a notification informing the user of a new version of the app. The instructions below walk you through one example of such a program.

1. Create the target segment

Create a Mobile Engage segment using the last_app_activity field and enter a value that will clearly identify the imported users. For example, if your import file contained a value one week (=168 hours) before the import took place, you will be able to filter for contacts whose last activity was more than 150 hours in the past.

You will then need to create a combined segment out of this Mobile Engage segment, in order for it to be available in the Automation Center.

2. Create your in-app message

Follow the instructions for Creating a new message and make sure your call to action is optimized for opens.

3. Create the program in the Automation Center

In the example below, an ad hoc batch program will target all your imported app users with an engagement push message.

The Wait node is configured to give these users enough time to open the app before they could be confused with new app users who registered after the import (in this case, 150 hours).

The second segment will filter for all those app users who still did not respond, and saves those as a contact list so that you can target them again with a follow up campaign if you so wish.