Import tokens
If you are coming from another push provider, Batch provides a way to import your existing iOS or Android tokens from any other push provider.
Here is why you need to import your tokens after a migration:
Token collection: Batch needs to collect all your users' tokens again if you don't import them. Part of your userbase will be unreachable during this period.
App updates: Some users may not update your app. As a consequence, you won't be able to push them after the migration.
Inactive users: In case the OS automatically updates your app, your users will still have to open your app to get a new token.
Batch can import all your existing tokens instantly with basic and custom data (e.g. attributes and arrays). This ensures you won't lose any tokens during the migration and you will still be able to send push messages to 100% of your audience.
What is a token
A push token is an anonymous ID generated by Apple (iOS) or Google (Android) for your installation. Batch's SDK collects automatically that token each time you open the app and sends it to our servers. If your users were offline the first time they opened your app, Batch will collect the token the next time they open it with a working Internet connection.
Each time you schedule a push message sending from the Dashboard, Batch will:
Select the installs associated to profiles matching your targeting;
Find the tokens attached to these installs;
Send the list of targeted tokens to Apple/Google with the message you want to deliver to these users.
Apple and Google automatically invalidate push tokens when users uninstall the app. They will generate a new token if the same users reinstall the app later.
Batch automatically takes care of updating/cleaning your users’ tokens. Please note we do not receive that kind of feedback in real time. We receive information on the validity of your users' tokens each time you try to send them a push notification.
Please note that test push notifications do not trigger a token invalidation feedback by Apple or Google even if the device is no longer reachable, only push orchestrations in production will trigger a token invalidation feedback by Apple or Google if the device is no longer reachable. The response time from Apple or Google is very variable, the push token can be considered valid by Apple for several days or even weeks after their invalidation in some cases.
Also, note that Google invalidates push tokens after 9 months (270 days) of device inactivity (= no activity on the entire device, not only on a specific app). Targeting an inactive user will generate an "invalid token" feedback in this case.
Token import format
The format of your devices' tokens export must be a valid CSV file (comma or semicolon delimited). Android/iOS devices tokens must be exported separately.
Before sending us your export, please review the format of each field in your import file. The CSV file must contain the following fields, in this order: push_token
, custom_id
, region
, language
, timezone
. Optional columns mean that their value can be empty, but they still must be present.
Id
Description
push_token
Required A device's push token
custom_id
Optional The custom ID of a user if you have one (email address, integer, etc).
region
Optional
Country of the user. If you do not specify a region, the user will automatically be put in the XX (no country) category. This should be written in ISO 3166-1 alpha-2 format. See here for all valid region codes.
E.g. "US"
language
Required
Language of the user in ISO 639-1 format. See here for all valid language codes.
E.g. "en"
timezone
Optional
User's timezone name in TZ database format. If you do not specify a timezone, it will be "GMT"
. See here for all valid timezones.
E.g. "Europe/Paris"
custom_data
Optional Custom attributes and tag collections. See Importing custom data for more information.
Once you're done, please rename your CSV file as EXPORT_APPNAME_OS_APIKEY.csv
(e.g. EXPORT_MYAPP_ANDROID_5BAB93CA7BD1A40183C959DA00CC0F
). The "APIKEY" must be the Live API key of the app you will find in the dashboard settings. Then send the CSV files to [email protected]. Our team will notify you once the import is complete.
Importing custom data
Attributes can be attached to imported tokens. All types of attributes supported on profiles can be imported.
They should be represented as a JSON object of tags and attributes and then encoded as Base64.
Attribute rules
Attribute names are strings. They should be made of lowercase letters, numbers or underscores ([a-z0-9_]
) and can't be longer than 30 characters (e.g. has_premium
).
Their values must be any of the following types:
String
Must not be longer than 200 characters and can be empty. For better results, you should make them upper/lowercase and trim the whitespaces.
Numbers
Dates
Must be sent as UNIX timestamps in seconds, and their key wrapped in
date()
. E.g."date(birthday)": 1512640800
Array rules
Array names are strings. They should be made of lowercase letters, numbers or underscores ([a-z0-9_]
) and can't be longer than 30 characters.
They must be represented as an array of strings. Individual values must be lowercased strings, and not longer than 64 characters.
Example
JSON Representation of profile attributes.
Which, encoded in Base64 for the CSV ends up being:
Data lifecycle when importing tokens & their data
Glossary
Anonymous Profile: a Profile without a Custom ID
Identified Profile: a Profile with a Custom ID, shared to Batch after sign-in or login
Trying to import a push token that is already collected by Batch
When your end user starts your app that implements Batch SDK, Batch automatically collects the push token, even if it was previously collected by your former push notification tool.
So, when going through the CSV import file, we first check if the push token doesn't already exist in the Batch Profile base.
In that case, we simply skip the import of the push token and its data.
Import of anonymous push tokens & their data
When processing your import file, Batch creates new profiles for previously unknown push tokens. Here's how it works:
Batch checks if the push token exists in its system.
If not found, a new profile is generated to store the token and its associated data.
When the user launches the app, Batch creates another profile with the new installation's push token, marked as "collected."
The profile with the imported token becomes orphaned.
Import of push tokens & their data when they're linked to a Custom ID
For push tokens associated with Custom IDs, the import process is as follows:
Batch verifies if the push token exists in its system.
If not found, Batch attempts to match the Custom ID from the import file with existing profiles.
Scenario 1: Matching Profile Found
We will merge the imported data with the existing profile according to these rules.
Push token: Added to the existing profile.
Custom attributes:
If the attribute already exists on the target profile or has been previously deleted (with a null value), the imported attribute will be skipped and the attribute value in the existing profile will be kept.
If the attribute doesn't exist on the target profile, the imported attribute will be merged into the profile.
No profile exists with this Custom ID
If no profile exists with the Custom ID:
A new identified profile is created.
All data associated with the imported token is linked to this new profile.
Specific behaviors of native attributes
Native attributes (language, region, timezone) can be imported alongside tokens.
Important considerations:
These imported native attributes have the lowest priority for targeting or personalization.
Other methods of setting these attributes (e.g., via API) all take precedence.
Export steps by provider
Importing from Airship
If you're coming from Airship, you will only need to request an export of your devices' tokens to your account manager.
Before sending us the export at [email protected], make sure the data is in the format described above and rename the files as follows to make sure our team can import it as quickly as possible: EXPORT_APPNAME_OS_APIKEY.csv. We will notify you once the import is complete.
Importing from PushWoosh
You can request an export of your devices' tokens at [email protected], mentioning your username.
Before sending us the export at [email protected], make sure the data is in the format described above and rename the files as follows to make sure our team can import it as quickly as possible: EXPORT_APPNAME_OS_APIKEY.csv. We will notify you once the import is complete.
Importing from OneSignal
If you're coming from OneSignal, you will need to request an export of your devices' tokens through an API export. You can find here how to request your raw token export. This can be done from One Signal's dashboard too.
Then, make sure the data is in the format described above and rename the files as follows to make sure our team can import it as quickly as possible: EXPORT_APPNAME_OS_APIKEY.csv
All you have to do now is send us your exports at [email protected]. Our team will notify you once the import is complete.
What's next
Once your push tokens have been successfully imported to Batch, your whole userbase is reachable and you can migrate your campaigns.
Note that this page is related to token imports for Push v2. Push v1 works in a slightly similar way, but by Platform (iOS, Android).
Last updated
Was this helpful?