Contents:
Purpose of the import
Creating an audience for an app is a tough job; mobile businesses can invest tens of thousands of dollars or euros to be there on their contacts' smartphone screens The purpose of this import process is to enable you to import your previous device database with valid push tokens to the Mobile Engage device database and associate the devices with existing Emarsys contacts.
Our goal is to provide self-service import in the future. However, we are quite a long way from that at this point. For now, our process is mostly manual, and takes time and requires active collaboration from 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.
Requirements for the import
The import is always made through a *.csv file. We will describe two scenarios here, an ideal one and a worst case one.
1. Ideal case scenario
In this case we are provided with all the data we need, so that we can associate the devices with existing Emarsys contacts.
The required metadata is: which custom contact field is used for linking up Emarsys contacts to the devices.
application_code
The application_code is the same for every row. This is generated by our delivery partner.
| Column name |
Data source |
Sample |
|---|---|---|
application_code |
Emarsys/Delivery partner |
ABCD1-9876E |
If the column is not present in the import file, it can be added to the *.csv during the import to Emarsys.
emarsys_customer_id
This is the Emarsys account ID. This should be included if the customer wants to use the app with more than one Emarsys account.
| Column name |
Data source |
Sample |
|---|---|---|
emarsys_customer_id |
Emarsys/Customer |
210268110 |
If the column is not present in the import file, and the customer has only one account, this can be added during the import process.
platform
The platform data should be provided in lower case.
| Column name |
Data source |
Sample |
|---|---|---|
platform |
Customer |
ios android |
This field is mandatory; without it, the import cannot be carried out. Since there is no default value available, it must be provided.
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 |
A unique hardware_id is mandatory for the import process.
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.
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 we will need one default language from the customer, and the messages will be sent in the default 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.
contact_field_id
This is the first half of the dataset that links the device to an Emarsys contact.
All Emarsys contact fields have a numeric ID; for more information, see the Field Editor.
| Column name |
Data source |
Sample |
|---|---|---|
contact_field_id |
Customer |
<id> |
If no contact information can be included in the import file, Emarsys will create new "anonymous" contacts in the your contact database and associate the devices with those. This slows down the import significantly.
Creating anonymous users is only useful when you want to send to not-logged in or non-member users.
When no contact data is available, and anonymous contacts must be used, messages cannot contain personalization.
contact_field_value
This is the second half of the dataset that links the device to an Emarsys contact.
This is the value of the Emarsys contact field mentioned in the contact_field_id.
This data is crucial for a fast and successful import. The data can be anything that is unique for every contact. It will be used to associate the device with an existing contact in Emarsys. We suggest using the your internal user ID, or a hashed version of the user ID.
As a last resort, email address can be used, if there are no duplications in the import file and in your contact database.
| Column name |
Data source |
Sample |
|---|---|---|
contact_field_value |
Customer |
<string> or <id> |
If no contact information can be included in the import file, Emarsys will create new "anonymous" contacts in your contact database and associate the devices with those. This slows down the import significantly.
Creating anonymous users is only useful when you want to send to not-logged in or non-member users.
When no contact data is available, and anonymous contacts must be used, messages cannot contain personalization.
2. Worst case scenario
In this case, no information is available, only the push_token and the hardware_id.
The application_code will be added to the import by Emarsys.
Please note that platform is a mandatory field; without this the import process cannot be carried out.
If any information is missing, the behavior is as follows:
-
timezone- +0000 will be used to fill the gaps, or the customer can choose a default value. This can later impact sending.. -
language- You should specify a default language. This will affect the language of the message when sending. -
app_version- We will leave it blank or use 0.0.0. It has no impact on sending. -
os_version- We will leave it blank or use 0.0.0. It has no impact on sending. -
contact_data- If no contact information can be included in the import file, Emarsys will create new "anonymous" contacts in your contact database and associate the devices with those. This slows down the import significantly.
Creating anonymous users is only useful when you want to send to not-logged in or non-member users. This also impacts sending, because only unpersonalised messages can be sent.
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.
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 |
If it is not present, the push_token will be used as a hardware_id in order to send unpersonalized messages. This has to be cleaned up by Emarsys later.
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.
There is no hardware_id and no contact_field_value, but we have a push_token
In this case, creating an anonymous contact may be reasonable, but it requires very much effort.
Carrying out the import is not recommended.