If you have already been send push messages via another provider, you can import your app users to Emarsys.
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.
Recommended fields
The following fields are not required, but are highly recommended.
timezone
This is the timezone based on GMT offset. For more information, see: https://www.ietf.org/rfc/rfc0822.txt.
| Column name | Data source | Sample |
|---|---|---|
| timezone | Customer | +0100 |
If it is not present, the default value will be +0000.
language
This is the two-letter ISO 639-1 language code. The multi-language editor is based on this value.
| Column name | Data source | Sample |
|---|---|---|
| language | Customer | en for English de for German hu for Hungarian etc... |
If it is not present in the import, all messages will be sent in the default app language to every device.
app_version
The format is #.#.# (major.minor.patch).
| Column name | Data source | Sample |
|---|---|---|
| app_version | Customer | 4.7.1 |
If it is not present, it will be left blank or it will default to 0.0.0.
os_version
The format is #.#.# (major.minor.patch).
| Column name | Data source | Sample |
|---|---|---|
| os_version | Customer | 10.2.1 |
If it is not present, it will be left blank or it will default to 0.0.0.
last_app_activity
Auto-fill this field with a datetime or a timestamp value, ideally one week in the past. This will help you identify all the anonymous users that you imported and let you target them with engagement campaigns designed to get them to open their app (thereby identifying themselves).
| Column name | Data source | Sample |
|---|---|---|
| last_app_activity | Customer | 2015-10-26 |
See below for an example of such an identifier program.
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 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:
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.
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.
In this case an anonymous contact will be created and used for messaging.
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.
In this case, the import cannot be carried out.
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.
