DevExtreme React - Packaging Tools

The last step in producing a mobile application is packaging. The applications created using the DevExtreme project templates can be easily packaged to be deployed to any device.

DevExtreme comes with the Build Native Package wizard. This wizard helps produce a native package for one of the following platforms.

  • iOS, Android and WindowsPhone
    A native package for these platforms is a PhoneGap container with your DevExtreme application packed as a resource. When building a package, the Package Builder replaces the fake cordova.js file located in the application project's root with a valid platform specific Cordova library version 3.7.

  • Any Platform
    You can generate a zip file that is ready for the PhoneGap Build server.

Below you will learn how to build a package from a Basic Application project template or the Mobile project of the Multi-Channel Application template. To learn how to get a package from the WinPhone project template, read the Packaging your Windows Store app using Visual Studio 2012 article. To learn how to get a package from the Win project template, read the Create a Sample Windows 8 App article.

Specify General Project Properties

Regardless of which platform you are going to package your application for, set the general project properties. To do this, right-click the application project in the Visual Studio Solution Explorer and choose Properties. In the invoked window, specify the General properties.

General Project Properties

  • Output Path
    Specify a folder for the output.
  • Start Page
    Set the application page that will be loaded when running your application.
  • Application Title
    Specify the application title that will represent the application on devices.
  • Root namespace
    A namespace used by the Add | New Item... dialog when adding a view using the DevExtreme View template. In this template, the function that returns a ViewModel of the added view is declared in the namespace that is set to this project property. For details, refer to the Set a Custom Namespace topic.
  • Version
    Specify your application's version.

    NOTE
    When building an iOS package, specify only the "Major", "Minor" and "Build" versions. The "Revision" version will not be considered.
  • Screen Orientation
    Specify the device orientation that your application supports.

  • Show Splash Screen
    Indicates whether or not to show the predefined splash screen.

Set Permitted URLs

The URLs that you navigate to from your application must be included in the "white list" of permitted links. Right-click the application project in the Visual Studio Solution Explorer and choose Properties, then populate the White list property presented in the PhoneGap tab.

White List

Follow the WhiteList Guide published in the PhoneGap documentation, because the application will be then built by PhoneGap.

Set Required Plugins

If you access device features in your application, specify the PhoneGap plugins that implement the corresponding device API.

Standard Plugins

Right-click your project in the Visual Studio Solution Explorer and choose Properties in the invoked window. All the standard PhoneGap plugins are listed by default within the PhoneGap tab.

Standard Plugins

Check the necessary plugins. They will be added to the project's config.xml file. Open this file and specify versions for the added plugins to make sure that they are compatible with the used Cordova version.

3rd Party Plugins

To use a custom 3rd party PhoneGap plugin in your application, do the following.

  • Register the required plugin in the application's config.xml file (this file is located in the root of your application project).

    HTML
    <widget xmlns="http://www.w3.org/ns/widgets">
        <!--...-->
        <plugin name="cordova-plugin-barcodescanner" version="0.7.3"/>
    </widget>

    The registered plugin will appear in the Plugins list in the checked state automatically.

    3rd Party Plugins

  • Build a custom PhoneGap application template with the required plugin inside.

NOTE
We recommend specifying versions for the added Cordova plugins in the config.xml file to make sure that they are compatible with the used Cordova version.

Custom Plugins

To use a custom PhoneGap plugin that is not registered in the PhoneGap repository, do the following.

  • Build a custom PhoneGap application template with the required plugin using the cordova command-line interface (CLI). As a result, you may have three custom application templates - each for a certain platform.

  • Put the custom PhoneGap application template(s) to an appropriate directory within your DevExtreme application project.

  • Set the Template file path property of your DevExtreme application project on the path of the added application template(s) (you can see this property within the Android package, iOS package and Windows Phone package tabs).

Set Cordova Version

As DevExtreme applications are packed using the PhoneGap Build, they must include the Cordova library. The DevExtreme project templates contain a fake cordova.js file located in the application project's root. When packing applications using the Build Native Package wizard, this fake file is replaced with a valid Cordova library version. You can pack DevExtreme applications with the Cordova library of another version. For this purpose, do the following.

  • Specify the required version of the Cordova library within the config.xml file.

    HTML
    <widget xmlns="http://www.w3.org/ns/widgets">
        <!--...-->
        <preference name="phonegap-version" value="cli-6.5.0" />
        <!--...-->
    </widget>
  • Build a custom PhoneGap application template with the required version of the Cordova library.

Build Custom PhoneGap Application Template

When building an iOS, Android or WinPhone package, a DevExtreme application is embedded into the DevExtreme-adapted PhoneGap application template. This template uses the Cordova library version 3.7 and accepts the standard PhoneGap plugins. If you need to use another version of the Cordova library or apply a custom 3rd party PhoneGap plugin(s), build a custom PhoneGap application template for your DevExtreme application. For this purpose, do the following.

  • Set your PhoneGap Build application token for the project's PhoneGap Build Token property within the PhoneGap properties tab.

    Application Token

    NOTE
    Your application token is located within the Client Applications tab of your PhoneGap account details.
  • Right-click your DevExtreme application project and choose the Build Application Template... item. The Build Template via PhoneGap API wizard will be invoked.

Build Application Template Wizard

Choose the platform for which you are going to build a custom application template. The wizard will upload a DevExtreme application template with your application's config.xml file to your private PhoneGap repository, then an .apk/.ipa/.appx file will be built and downloaded to your application project. Finally, the created application template will be removed from your private PhoneGap application repository.

Build Log

Close the wizard. The created application template will be added to the templates folder in your application project and a path to this template will be assigned to the Template file path property of the application project automatically (you can see this property within the Android package, iOS package and Windows Phone package tabs).

Templates Folder

As a result, the created custom application templates will be used when packing your DevExtreme application (read below to learn how to prepare a package).

Build Package for iOS

As you were developing this application, you already included layouts and style sheets specific to the iOS platform. The next step is to set the project properties required for building a native iOS package. To do this, right-click the application project in the Visual Studio Solution Explorer and choose Properties, then specify the properties that are presented in the iOS package tab.

iOSPackage Properties

  • Package information
    Specify a unique ID to identify your application in the AppStore.

  • Signing

    You do not have to specify these properties, because the certificate will be created during the iOS package built by the DevExtreme Build Package wizard (see below). If you have already obtained a certificate, you can specify it here, in which case it will be used by the DevExtreme Build Package wizard automatically.

  • Devices family

    Specify the underlying hardware type on which this app is designed to run.

  • App Icons and Splash Images

    Assign the icons and splash images that will be built into the application's native package. To learn about image recommendations, refer to the http://developer.apple.com/ site.

  • Package localization

    If you localize your application, specify the application languages so that they are available for end users in the AppStore.

  • Application Template

    Specify a custom PhoneGap application template for the iOS native package. When going through the Build Package wizard, this template will be used as a base to build a native package for the application.

Now, you can easily create a native iOS package with your application right from Visual Studio. Right-click the application project and choose Build Native Packages.... The Build Package wizard will run.

Build For iOS

Choose iOS and go through all the wizard steps. This will result in a native package that is ready to be loaded to the AppStore. For details on the iOS application release requirements, refer to the developer.apple.com site.

Watch Video

Build Package for Android

As you were developing this application, you already included layouts and style sheets specific to the Android platform. The next step is to set the project properties required for building a native Android package. To do this, right-click the application project in the Visual Studio Solution Explorer and choose Properties, then specify the properties that are presented in the Android package tab.

Android Package Properties

  • Package|Name
    Specify the package name to be assigned to your Android application.

  • Package|Debuggable
    Check this option to enable WebView debugging when the application runs on an Android device.

  • Version
    Specify an additional element for the application version.

  • Signing

    You do not have to specify these properties, because the certificate will be created during the iOS package built by the DevExtreme Build Package wizard (see below). If you have already obtained a certificate, you can specify it here. In this instance, it will be used by the DevExtreme Build Package wizard automatically.

  • App Icons and Splash Images

    Assign the icons and splash images to be built into the application's native package. To learn about image recommendations, refer to the Launcher Icons and Supporting Multiple Screens articles.

  • Application Template

    Specify a custom PhoneGap application template for the Android native package. When going through the Build Package wizard, this template will be used as a base for building a native package for the application.

Now, you can easily create a native Android package with your application right from Visual Studio. Right-click the application project and choose Build Native Packages.... The Build Package wizard will run.

Build For Android

Choose Android and go through all the wizard steps. As a result, you will get a file that is ready to be loaded to the Google Play. For details on the requirements for an Android application release, refer to the developer.android.com site.

Watch Video

Build Package for WinPhone

As you were developing this application, you included layouts and style sheets specific to the WinPhone platform. The next step is to set the project properties required for building a native Windows Phone package. To do this, right-click the application project in the Visual Studio Solution Explorer and choose Properties, then specify the properties that are presented in the Windows Phone package tab.

WinPhone Package Properties

  • Signing

    Specify a path to the .pfx file used to sign the application package.

  • Packaging

    These properties are analogous to the properties from the app manifest file for the Windows Phone.

  • App Icons and Images

    Assign the icons and splash images to be built into the application's native package. To learn about image recommendations, refer to the Tile design guidelines for the Windows Phone article.

  • Package localization

    If you localize your application, specify the application's languages so that they are available for end users in the Windows Phone Store.

  • Application Template

    Specify a custom PhoneGap application template for the Windows Phone native package. When going through the Build Package wizard, this template will be used as a base for building a native package for the application.

Now, you can easily create a native Windows Phone package with your application right from Visual Studio. Right-click the application project and choose Build Native Packages.... The Build Package wizard will run.

Build For WinPhone

Choose Windows Phone and go through all the wizard steps. As a result, you will get a file that is ready to be loaded to the Windows Store. For details on the requirements for a Windows Phone application release, refer to the Windows Phone Dev Center.

Watch Video

Prepare Zip for PhoneGap Build

The DevExtreme project templates can be built for any platform using the build.phonegap.com. For this purpose, generate a zip package of your application using the Build Package wizard.

Before running the Build Package wizard, set the required version of the Cordova library if needed and include required PhoneGap plugin(s) into the application project.

To prepare a zip package for the PhoneGap Build, right-click the application project and choose Build Native Packages... The Build Package wizard will be invoked.

ZIP Build

Choose Zip and a PhoneGap package will be generated automatically.