Importing your 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 tag collections). This ensures you won't lose any tokens during the migration and you will still be able to push inactive users or outdated users.

Prerequisites

Here are the three steps you need to follow before exporting your tokens:

Upgrade your plan: The token import feature is only available on the Developer plan and higher.
Update your app: Make sure Batch is already integrated in your app. This ensures no users are omitted between the moment you export your tokens and the moment Batch starts collecting your new users' tokens.
Send us your export: You can send us your export at support@batch.com.

Now let's see how to generate your tokens export from your old push provider.

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, install_date ,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
`install_date`	- Optional Install date of the app on the user’s device. The date should be written in ISO 8601 format: YYYY-MM-DDTHH:mm . E.g.`"2007-04-30T14:30"`
`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 support@batch.com. Our team will notify you once the import is complete.

Importing custom data

Custom installation data can be attached to imported tokens. Attributes and Tag Collections are supported.

They should be represented as a JSON object of tags and attributes and then encoded as Base64.

Note: As soon as the imported token is migrated to a Batch SDK-enabled installation, this data will be deleted. It is very important that this import format matches the tagging plan implemented using the SDK's custom data API. (Android / iOS)

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).

They should then be prefixed by c.

Their values must be any of the following types:

String
- Must not be longer than 64 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(c.birthday)": 1512640800

Tag collection rules

Tag collection 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 should then be prefixed by t.

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 installation data

{
  "c.age": 26,
  "c.finished_onboarding": true,
  "c.first_name": "John",
  "date(c.became_premium)": 1512640800,
  "t.interests": ["sports", "finance"]
}

Which, encoded in Base64 for the CSV ends up being:

eyJjLmFnZSI6MjYsImMuZmluaXNoZWRfb25ib2FyZGluZyI6dHJ1ZSwiYy5maXJzdF9uYW1lIjoiSm9obiIsImRhdGUoYy5iZWNhbWVfcHJlbWl1bSkiOjE1MTI2NDA4MDAsInQuaW50ZXJlc3RzIjpbInNwb3J0cyIsImZpbmFuY2UiXX0=

PHP Example

Here is a PHP example, which converts an array containing the data to the expected format:

<?php

// Generate some example installation data
$installation_data = [];

// -- Atributes. Their key MUST start with c. and follow the same rules as custom data sent using the SDKs --
// Strings, numbers and booleans can be added as such
$installation_data["c.age"] = 26;
$installation_data["c.finished_onboarding"] = true;
$installation_data["c.first_name"] = "John";

// Dates have to be converted to timestamps, and their keys must be wrapped in "date()"
$became_premium = new DateTime(); // Example value, where your fetched date is a DateTime
$installation_data["date(c.became_premium)"] = $became_premium->getTimestamp();

// -- Tag Collections. Their key MUST start with t. and follow the same rules as custom data sent using the SDKs --

$installation_data["t.interests"] = [
    "sports",
    "finance"
];

function encodeInstallationData(array $data)
{
    $json = json_encode($data);
    if (json_last_error() !== JSON_ERROR_NONE) {
        throw new Exception("Could not encode JSON data: " . json_last_error_msg());
    }
    return base64_encode($json);
}

// Convert our example data, and print it
echo(encodeInstallationData($installation_data));

?>

Export steps by provider

Importing from Airship

If you're coming from Accengage, you will only need to request an export of your devices' tokens to your account manager.

Before sending us the export at support@batch.com, 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 help@pushwoosh.com, mentioning your username.

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 support@batch.com. 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.

Next stepPush campaigns migration

Documentation > Migrating to Batch (mobile push)