• iOS
  • Android
  • Windows
  • Web
  • Cordova
  • Unity
  • Adobe Air
  • Dashboard
  • API
  • Guides
  • FAQ
  • Documentation > Guides

    Migrating to Batch

    If you are coming from another push provider, Batch provides a way to import your existing tokens from Parse, Urban Airship or 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. 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:

    1. Upgrade your plan: The token import feature is only available on the Developer plan and higher.
    2. 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.
    3. 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.

    Importing your tokens

    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. On iOS, please make sure the push tokens of the production and the development’s P12 certificate are not in the same export.

    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.

    Parameters 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 Required - User's timezone in TZ format. If you do not specify a timezone, the timezone of the user will be automatically "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 and send it 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
      Dates must be sent as UNIX timestamps, 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));
    
    ?>

    Importing from Accengage

    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 your export at support@batch.com, please make sure you have renamed it as follows: EXPORT_APPNAME_OS_APIKEY.csv.

    Importing from Parse

    First, go to your dashboard, select your app and click on "App settings". Then click on General in the side menu and the "Export app data" button.

    Parse Export

    If everything goes well, you will receive an email containing a .zip file with all your push tokens in a JSON file. Please rename the zip file as follows to make sure our team can import it as quickly as possible: EXPORT_APPNAME_OS_APIKEY.zip.

    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.

    IMPORTANT
    As Parse describes it in its documentation (see the paragraph starting with "By default"), Parse used its own GCM sender ID instead of the one generated by Google.

    Unless you specified your own GCM sender ID in your code when you integrated Parse, none of the Android tokens collected by Parse are pushable by another push provider.

    Importing from PushWoosh

    You can request an export of your devices' tokens at help@pushwoosh.com, mentioning your username.

    Before sending us your export at support@batch.com, please make sure you have renamed it as follows: EXPORT_APPNAME_OS_APIKEY.csv. We will notify you once the import is complete.

    Importing from Urban Airship

    All you need to do is to select your app, go to SettingsAPI & Integrations and note your App Key and your App Master Secret.

    Urban Airship APIs

    Then, just send them to us at support@batch.com with your app name and your Batch API key and we will take care of exporting and importing your tokens for you.

    Importing from OneSignal

    If you're coming from OneSingal, you will only need to request an export of your devices' tokens through an API export. You can find here how to request your raw token export.

    Please rename the zip file as follows to make sure our team can import it as quickly as possible: EXPORT_APPNAME_OS_APIKEY.csv

    Once you rename your 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.

    Targeting imported users

    After we’ve completed your tokens import, a new IMPORTED segment will be available. Imported users

    There are a few things you need to keep in mind before targeting your newly imported users:

    • The IMPORTED segment is not targeted by default when you create a new campaign. Don't forget to select it the next time you want to send a notification.
    • Imported users will be progressively analysed and transferred to other Smart Segments after their first session.
    • The first time you send a notification to your imported users, Batch will clean the inactive or invalid tokens that may come from your previous push provider. Depending on how many invalid tokens we find, the number of users in the IMPORTED segment will decrease a few days after the import.