Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Migration Guide for Cordova Apps

Only AppBuilder apps that target Cordova 6.4.0 can be exported to Cordova CLI. If your app targets an older version, you need to migrate it to Cordova 6.4.0 and resolve any build errors before exporting to Cordova CLI.

The automatic migration process does not produce a working Windows Phone app. To resolve this issue, you need to follow the Additional Steps for Windows Phone from the manual migration procedure.

Prerequisites for Cordova CLI development

  • Cordova CLI version 6.4.0
    The exported apps will work as expected only in Cordova CLI version 6.4.0. To install it, you need to use the npm install -g cordova@6.4.0 command.
  • Properly configured environment
    To build the exported apps with the Cordova CLI, you need to setup your development environment and install all Cordova CLI requirements. You can use the cordova requirements command to check if your system is configured properly.
  • macOS system for iOS development
    You need a macOS system to build iOS apps with the Cordova CLI. For more information about the operating system to platform compatibility, see Platform Support.

Procedure for Automatic Migration

  1. Log in to Telerik Platform.
  2. (Optional) To migrate an app that contains TypeScript files, you need to complete the following steps:
    1. Open the app in question.
    2. In the Project Navigator, double-click the .abignore file to open it.
    3. Locate and remove the following lines (usually, lines 47 and 49): */**/*.ts and tsconfig.json.
  3. You have two ways to start the export process:
    • In the Apps tab, locate the app you want to migrate and click on the Export to Cordova CLI button next to it.
    • Inside your app, right-click on your app name (second node from the top in Project Navigator) and select Export to CLI.
  4. When the migration process is complete, an archive containing the migrated project will be automatically saved on your system. Extract the content of the archive to a suitable location.
  5. (Optional) If you have modified the Android Config.xml, iOS Config.xml or Windows Phone Config.xml files of your AppBuilder project, you need to manually transfer these changes to the respective platform tag in the config.xml of the exported project. The Android Config.xml and iOS Config.xml files can be found in the appbuilder-config folder of the exported project.
    • Additions made to the Android Config.xml file should be moved inside the <platform name="android"></platform> tag of the config.xml.
    • Additions made to the iOS Config.xml file should be moved inside the <platform name="ios"></platform> tag of the config.xml.
    • Additions made to the Windows Phone Config.xml file should be moved inside the <platform name="wp8"></platform> tag of the config.xml.
  6. Run the cordova build command to build the app or the cordova run command to build and deploy the app on a connected device. For more information about all available Cordova CLI commands, see the Cordova CLI Reference article.

Procedure for Manual Migration

  1. Log in to Telerik Platform.
  2. (Optional) If you plan to build the exported app for Windows Phone, you need to open your app in your preferred AppBuilder client and open the Windows Phone Manifest file. For more information, see Edit Configuration Files. This step will ensure that the file is present in the exported project.
  3. In the Apps tab, select Download Code to download and save an archive containing your AppBuilder app. Extract the content of the archive to a suitable location. If you are developing locally with the AppBuilder extension for Visual Studio or the AppBuilder CLI, you can use the app stored on your system.
  4. Install Cordova CLI version 6.4.0 by running the npm install -g cordova@6.4.0 command.
  5. Use the command given below to create a new Cordova CLI project. The AppID must be identical to the Application identifier of your AppBuilder app.
    
        cordova create {Path} {AppID} {Name}
    
    
  6. Delete all files and folders located inside the www folder of the newly created Cordova CLI project.
  7. Copy all files (except .abignore, .abproject, .yo-rc.json, cordova.*.js) and folders (except the App_Resources and Plugins folders) from the AppBuilder app to the www folder of the newly created Cordova CLI project. Do not delete any files or folders from the AppBuilder app because you will need them later.
  8. Take the following values from the .abproject of the AppBuilder app and place them inside the config.xml of the Cordova project.
    • Take the Description value from .abproject and place it inside the <description></description> tag in config.xml.
    • Take the Author value from .abproject and place it inside the <author></author> tag in config.xml.
  9. (Optional) If you have modified the Android Config.xml, iOS Config.xml or Windows Phone Config.xml files of your AppBuilder project, you need to manually transfer these changes to the respective platform tag in the config.xml of the exported project.
    • Additions made to the Android Config.xml file should be moved inside the <platform name="android"></platform> tag of the config.xml.
    • Additions made to the iOS Config.xml file should be moved inside the <platform name="ios"></platform> tag of the config.xml.
    • Additions made to the Windows Phone Config.xml file should be moved inside the <platform name="wp8"></platform> tag of the config.xml.
  10. To include an AppBuilder Core plugins to your app, open the config.xml of the Cordova CLI project and reference the desired plugin. Below you can find all Core plugin references. You can add all of them to your project or only the ones used in your AppBuilder app:
    
        <plugin name="cordova-plugin-battery-status" spec="https://github.com/apache/cordova-plugin-battery-status#59189285b60dacf6433aafa7294178598fb920a4" />
        <plugin name="cordova-plugin-camera" spec="https://github.com/apache/cordova-plugin-camera#9eba35e2f6d5c69d0594b41ac4a49cc2cfc7c3b3" />
        <plugin name="cordova-plugin-contacts" spec="https://github.com/apache/cordova-plugin-contacts#af620d6cde05dde428e4e55fafdb21c4b58bc8c2" />
        <plugin name="cordova-plugin-device" spec="https://github.com/apache/cordova-plugin-device#a736ae44b1e17be545f586f33bd98194b6401e34" />
        <plugin name="cordova-plugin-device-motion" spec="https://github.com/apache/cordova-plugin-device-motion#5e0e28f4f2ad594bf484382f6afede268729286d" />
        <plugin name="cordova-plugin-device-orientation" spec="https://github.com/apache/cordova-plugin-device-orientation#4b5ead9000326e36eda4975f29e7bf9cf12bbaa4" />
        <plugin name="cordova-plugin-dialogs" spec="https://github.com/apache/cordova-plugin-dialogs#233aff26f8102d25ed531518c83c4e2be7127bdf" />
        <plugin name="cordova-plugin-file" spec="https://github.com/apache/cordova-plugin-file#db39e7ccab1df556f9bff6ce4e748eac703c41da" />
        <plugin name="cordova-plugin-file-transfer" spec="https://github.com/apache/cordova-plugin-file-transfer#aee45754a9d685ac867a9d0fbb843a66d2845551" />
        <plugin name="cordova-plugin-geolocation" spec="https://github.com/apache/cordova-plugin-geolocation#7934ed70269cab91cd109607da36f602b25d1892" />
        <plugin name="cordova-plugin-globalization" spec="https://github.com/apache/cordova-plugin-globalization#594651d27275dc2013f86e0ccc7e78a9a6d6f654" />
        <plugin name="cordova-plugin-inappbrowser" spec="https://github.com/apache/cordova-plugin-inappbrowser#009e662c82f4fa153f0d0ccc14995ddb3b495de5" />
        <plugin name="cordova-plugin-media" spec="https://github.com/apache/cordova-plugin-media#f0a6d4512002176adae1a7cc4d58b6d6a0b06722" />
        <plugin name="cordova-plugin-media-capture" spec="https://github.com/apache/cordova-plugin-media-capture#b09b24d71b53937db0351f0e041be18751699a20" />
        <plugin name="cordova-plugin-network-information" spec="https://github.com/apache/cordova-plugin-network-information#0079edbaa5e24419ea383d918cbe960d3d4cae99" />
        <plugin name="cordova-plugin-splashscreen" spec="https://github.com/apache/cordova-plugin-splashscreen#782939f7ef27b2955a16f77c9bba9e66af9f53a0" />
        <plugin name="cordova-plugin-statusbar" spec="https://github.com/Icenium/cordova-plugin-statusbar#b3139a0eae6f001e8cd805b07aea86780694a5c1" />
        <plugin name="cordova-plugin-vibration" spec="https://github.com/apache/cordova-plugin-vibration#fcc6f19a087fe620c63b79a270f5b8a033a1791e" />
        <plugin name="cordova-plugin-whitelist" spec="https://github.com/apache/cordova-plugin-whitelist#79f74a00e2b0bbd865fab7f006343e85b45a2f3c" />
    
    
  11. (Optional) To include a Telerik Verified Marketplace plugins to your app, you need to find the repository of the plugin and reference it manually to the config.xml file of the Cordova CLI project or use the cordova plugin add <*.git> command. All Verified plugins have installation steps for Cordova CLI in their repositories.
    For example, to add version 2.1.8 of the ImagePicker plugin to your app, you need to add <plugin name="com.synconset.imagepicker" spec="https://github.com/Telerik-Verified-Plugins/ImagePicker#2.1.8" /> to the config.xml or follow the installation steps in the repository.
  12. (Optional) To include a custom plugin to your app, open the config.xml of the Cordova CLI project and reference the plugin from the Plugins folder of the AppBuilder app or follow the installation steps in the plugin repository.
    For example, to reference a custom plugin located on the file system (the Plugins folder of the AppBuilder project) add <plugin name="my-custom-plugin" spec="PATH_TO_CUSTOM_PLUGIN" /> to the config.xml, where the PATH_TO_CUSTOM_FOLDER is the path to the custom plugin located in the Plugins folder of the AppBuilder app.
  13. If your app contains configuration specific files (*.release.* or *.debug.*), you should delete one of them and rename the other by removing the configuration modifier from the file name.
    For example, if you have myfile.debug.js and myfile.release.js, you need to delete the first one and rename the second to myfile.js.
  14. If your app contains platform specific files (*.ios.*, *.android.* or *.wp8.*), you should keep only one of them and rename it by removing the platform modifier from the file name. To continue using the platform specific files in your Cordova CLI project, you can use the com.telerik.cordovaPlatformSpecificFiles plugin. To include this plugin to your Cordova CLI project, open the config.xml file and add <plugin name="cordova-plugin-whitelist" spec="https://github.com/Icenium/cordova-platform-specific-files#3a3c4a66bb1c3dd13de32f9788bbf83b0be57c71" />.
  15. Proceed to the platform specific steps.

Manual Migration: Additional Steps for iOS

  1. Add version 4.3.1 of the iOS platform to the Cordova CLI project by running the cordova platform add ios@4.3.1 command.
  2. Copy the content of App_Resources/iOS folder of the AppBuilder app and paste it in the platform/ios/{app-name}/Resources folder of the Cordova CLI project.
  3. In the Cordova CLI project, delete the platform/ios/{app-name}/Images.xcassets folder.
  4. In the Cordova CLI project, open platform/ios/{app-name}/{app-name}-Info.plist and make the following modifications:
    • Take the DisplayName value from .abproject of the AppBuilder app and place it inside the <string></string> tag of the CFBundleDisplayName key.
    • Reference the icon assets by adding the following keys and values under the CFBundleIcons key:
        <dict>
            <key>CFBundlePrimaryIcon</key>
            <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>icon@2x.png</string>
                <string>icon.png</string>
                <string>Icon-Small.png</string>
                <string>Icon-Small@2x.png</string>
                <string>Default.png</string>
                <string>Default@2x.png</string>
                <string>icon-72.png</string>
                <string>icon-72@2x.png</string>
                <string>Icon-Small-50.png</string>
                <string>Icon-Small-50@2x.png</string>
                <string>Default-Landscape.png</string>
                <string>Default-Landscape@2x.png</string>
                <string>Default-Portrait.png</string>
                <string>Default-Portrait@2x.png</string>
                <string>icon-40.png</string>
                <string>icon-40@2x.png</string>
                <string>icon-60.png</string>
                <string>icon-60@2x.png</string>
                <string>icon-76.png</string>
                <string>icon-76@2x.png</string>
            </array>
            <key>UIPrerenderedIcon</key>
            <true/>
            </dict>
        </dict>
    
    • Reference the splash screen assets by adding the following keys and values:
        <key>UILaunchImages</key>
        <array>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default</string>
            <key>UILaunchImageOrientation</key>
            <string>Portrait</string>
            <key>UILaunchImageSize</key>
            <string>{320, 480}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default</string>
            <key>UILaunchImageOrientation</key>
            <string>Landscape</string>
            <key>UILaunchImageSize</key>
            <string>{320, 480}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default-568h</string>
            <key>UILaunchImageOrientation</key>
            <string>Portrait</string>
            <key>UILaunchImageSize</key>
            <string>{320, 568}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default-568h</string>
            <key>UILaunchImageOrientation</key>
            <string>Landscape</string>
            <key>UILaunchImageSize</key>
            <string>{320, 568}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default-667h</string>
            <key>UILaunchImageOrientation</key>
            <string>Portrait</string>
            <key>UILaunchImageSize</key>
            <string>{375, 667}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default-667h</string>
            <key>UILaunchImageOrientation</key>
            <string>Landscape</string>
            <key>UILaunchImageSize</key>
            <string>{375, 667}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default-736h</string>
            <key>UILaunchImageOrientation</key>
            <string>Portrait</string>
            <key>UILaunchImageSize</key>
            <string>{414, 736}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default-Landscape-736h</string>
            <key>UILaunchImageOrientation</key>
            <string>Landscape</string>
            <key>UILaunchImageSize</key>
            <string>{414, 736}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default-Portrait</string>
            <key>UILaunchImageOrientation</key>
            <string>Portrait</string>
            <key>UILaunchImageSize</key>
            <string>{768, 1024}</string>
            </dict>
            <dict>
            <key>UILaunchImageMinimumOSVersion</key>
            <string>8.0</string>
            <key>UILaunchImageName</key>
            <string>Default-Landscape</string>
            <key>UILaunchImageOrientation</key>
            <string>Landscape</string>
            <key>UILaunchImageSize</key>
            <string>{768, 1024}</string>
            </dict>
        </array>
    
  5. Run the cordova build command to build the app or the cordova run command to build and deploy the app on a connected device. For more information about all available Cordova CLI commands, see the Cordova CLI Reference article.

Manual Migration: Additional Steps for Android

  1. Add version 6.1.0 of the Android platform to the Cordova CLI project by running the cordova platform add android@6.1.0 command.
  2. In the Cordova CLI project, open the config.xml file and add the following preferences inside the <platform name="android"></platform> tag.
    
    <preference name="splashscreen" value="splashscreen"/>
    <preference name="splashScreenDelay" value="10000"/>
    
    
  3. In the Cordova CLI project, open the platforms/android/res folder and delete all folders that start with drawable and mipmap.
  4. Copy all folders that start with drawable from the App_Resources/Android folder of the AppBuilder app and paste them in the platforms/android/res folder of the Cordova CLI project.
  5. In the Cordova CLI project, open platforms/android/res/values/strings.xml and make the following modification:
    • Take the DisplayName value from .abproject of the AppBuilder app and place it inside a <string name="display_name"></string> tag in <resources></resources>.
  6. In the Cordova CLI project, open platforms/android/AndroidManifest.xml and make the following modification:
    • In the <application> key, change android:label="@string/app_name" to android:label="@string/display_name".
    • In the <application> key, change android:icon="@mipmap/icon"" to android:icon="@drawable/icon"".
    • In the <activity> key, change android:label="@string/activity_name" to android:label="@string/display_name".
    • Replace all TelerikCallbackActivity references with MainActivity.
  7. Run the cordova build command to build the app or the cordova run command to build and deploy the app on a connected device. For more information about all available Cordova CLI commands, see the Cordova CLI Reference article.

Manual Migration: Additional Steps for Windows Phone

  1. Add version 3.8.2 of the Windows Phone 8 platform to the Cordova CLI project by running the cordova platform add wp8@3.8.2 command.
  2. Copy all SplashScreen*.jpg and ApplicationIcon.png files, Assets and Tiles folders from the App_Resources/WP8 folder of the AppBuilder app and paste them (or replace any existing ones) in the platforms/wp8 folder of the Cordova CLI project.
  3. Copy the content of the App_Resources\WP8\WMAppManifest.xml file of the AppBuilder app and use it to overwrite the content of the platforms/wp8/Properties/AppManifest.xml file of the Cordova CLI project.
  4. Take the following values from the .abproject of the AppBuilder app and place them inside the platforms/wp8/Properties/AppManifest.xml of the Cordova project.
    • Take the value of the WPSdk key from .abproject and use it to replace the $WPSdk$ variable in AppManifest.xml.
    • Replace $WP8DeploymentSchema$ with "http://schemas.microsoft.com/windowsphone/2012/deployment"
    • Take the value of the Description key from .abproject and use it to replace the $Description$ variable in AppManifest.xml.
    • Take the value of the WP8PublisherID key from .abproject and use it to replace the $WP8PublisherID$ variable in AppManifest.xml.
    • Take the value of the WP8Publisher key from .abproject and use it to replace the $WP8Publisher$ variable in AppManifest.xml.
    • Take the value of the Author key from .abproject and use it to replace the $Author$ variable in AppManifest.xml.
    • Take the value of the DisplayName key from .abproject and use it to replace the $DisplayName$ variable in AppManifest.xml.
    • Take the value of the BundleVersion key from .abproject and use it to replace the $BundleVersion$ variable in AppManifest.xml.
    • Take the value of the WP8ProductID key from .abproject and use it to replace the $WP8ProductID$ variable in AppManifest.xml.
    • Take the value of the ProjectName key from .abproject and use it to replace the $ProjectName$ variable in AppManifest.xml.
    • Take the value of the WP8TileTitle key from .abproject and use it to replace the $WP8TileTitle$ variable in AppManifest.xml.
    • Inside the <ScreenResolutions> tag, add the following:
        <ScreenResolution Name=“ID_RESOLUTION_WVGA” />
        <ScreenResolution Name=“ID_RESOLUTION_WXGA” />
        <ScreenResolution Name=“ID_RESOLUTION_HD720P” />
    
    • Inside the <Capabilities> tag, add the following:
        <Capability Name=“ID_CAP_WEBBROWSERCOMPONENT” />
        <Capability Name=“ID_CAP_NETWORKING” />
    
  5. Use the cordova build command to build the app or the cordova run command to build and deploy the app on a connected device. For more information about all available Cordova CLI commands, see the Cordova CLI Reference article.
Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.