Create Config.xml File

Although you used to could configure a few settings using the PhoneGap Build detail page, this option is no longer available. Each app you submit to the PhoneGap Build service now requires a configuration file that is named config.xml that MUST be included with the zip file when an app is loaded to PhoneGap Build. This file is used to set general/advanced settings, app icons, splash screens, permissions, developer info and plugins.

NOTE: If the app is created using PhoneGap Command Line Interface (CLI), it will automatically generate a config.xml file.

Beside writing the entire file yourself, there are two major ways to create this file:

Use Starter Template

You can use the a starter template from an online resource like Github. For example, you could use the sample template from https://github.com/phonegap/phonegap-start/blob/master/www/config.xml.

Below are some details about the various settings.

Minimum Properties

The config.xml file is used as the name implies to "configure" an app settings. It should be at the app root level and it is used to specify the app's metadata.

The <widget> is the root element for the config.xml file that has the following attributes:

Inside of the set of <widget> tag, you can add the following elements:

 

View sample of minimum properties.

Other Properties

You can the following additional properties to the config.xml file:

Permissions

Once you add the bare basics, you can add app's permission. If you do not need any permissions for your app, add the following line. You will still have the INTERNET permission which is required by PhoneGapBuild:


<preference name="permissions" value="none"/>

Otherwise, you can add a host of permissions inside of the <widget> element.

NOTE: You can define a specific version of PhoneGap to build your app to by adding the following preference:

<preference name="phonegap-version" value="3.6.0" />

View sample of minimum properties and preferences settings.

Icons

You need to specific icons for each platform you are building for.

NOTE: The icon.png is the default icon that will be used and must allays be named as such.

View sample of minimum properties, preferences and icon settings.

Splash Screens

You need to specific splash screens for each platform you are building for.

 

NOTE: You can also add the following to... (find out what this does):

<gap:config-file platform="ios" parent='CFBundleShortVersionString">
<string>100</string>
</gap:config-file>


View sample of minimum properties, preferences, icon and splash screen settings.

Access

You can also define various access to external domains.

Otherwise, you can specify specific domains:

View sample of minimum properties, preferences, icon, splash screen, and access settings.

Plug-ins

Last but not least, you can add some plug-ins to the config.xml file. There are core-plug-ins and third-party plug-ins.

A list of available plugins are available at https://build.phonegap.com/plugins

View sample of minimum properties, preferences, icon, splash screen, access and plug-in settings.

Use ConfigGAP

Another way to create the config.xml file is to use an app called ConfiGAP that is designed to help you create the config.xml files used by Adobe® PhoneGap™ Build. If you have ever used PhoneGap Build, you know that creating the config.xml file can be a complex chore. ConfiGAP was built to make that process a bit easier by defining the following items:



  1. Go to ConfiGAP at http://www.configap.com/.
  2. Click on the Download button to download the ConfiGAP app to your computer.
  3. Double-click on the installation file and in the Open File - Security Warning dialog box that appears, click the Run button to open the app.

Create New Config.xml File

Click the ConfiGAP icon if necessary to start the app. You will be presented with the General Settings screen. Additional settings include:

PhoneGap utilizes <preference> tags in the config.xml to customize an app configuration.

General Tab

The default screen is General where you set multi-platform preferences.

  1. Fill out ALL of the options on this screen. (See below for explanation of each field)
  2. Click the Advanced tab.


Multi-Platform Preferences:

EXAMPLE CODE:

<?xml version="1.0" encoding="UTF-8" ?>
<widget xmlns   = "http://www.w3.org/ns/widgets"
    xmlns:gap   = "http://phonegap.com/ns/1.0"
    id          = "com.richmediacs.com/adobeccapps"
    versionCode = "1" 
    version     = "1.0.0" >
    <name>ADOBE CC APPS</name>
    <description>
        What's New in Adobe CC
    </description>
    <author href="http://richmediacs.com" email="cornelius@richmediacs.com ">
          Cornelius Chopin
    </author>

    <platform name="ios"/>
    <platform name="android"/>
    <platform name="winphone"/>

    <preference name="phonegap-version" value="cli-6.1.0" />
    <preference name="orientation" value="portrait" />
    <preference name="fullscreen" value="false" />
    <preference name="webviewbounce" value="false" />
    <preference name="DisallowOverscroll" value="true" />
    <preference name="disallowOverscroll" value="true" />
    <preference name="target-device" value="universal"/>
    <preference name="deployment-target" value="7.0"/>
    <preference name="exit-on-suspend" value="false"/>
    <preference name="detect-data-types" value="true"/>
    <preference name="prerendered-icon" value="false"/>
    <preference name="StatusBarOverlaysWebView" value="false" />
    <preference name="ios-statusbarstyle" value="default"/>
    <preference name="StatusBarStyle" value="default" />
    
    <preference name="android-minSdkVersion" value="24" />
    <preference name="android-installLocation" value="auto" />

[REST OF THE MARKUP GOES BETWEEN THE OPENING AND CLOSING (E.G. <WIDGET> ... </WIDGET>)TAGS]
</widget>

CODE EXPLANAITON

Cross-platform settings:

Each <preference> element represents preferences that you want to set for a given platform with a set of name/value pairs attributes. Below are some of the most common preferences:

General Preferences:

iOS Specific Preferences:

Android Specific Preferences:

Advanced Tab

The Advanced tab is where you set advanced features (e.g., SDK versions, loading options) for all of the platforms

  1. If necessary, click on the Advanced tab

  2. Set Advanced preferences for one or more platforms you are targeting:
Android Preferences:



iOS Preferences:


Window Preferences:


Icons Tab

If you do not specify a icon, then the PhoneGap logo will be used as the app's icon. The attributes for the icon element are:

src: (required) specifies the location of the image file, relative to your site directory
width: (optional) but recommended, width in pixels
height: (optional) but recommended, height in pixels

See screenshot in Creating Graphic Assets under the Test App menu on how to create icons.

 

(MOVE TO CREATING GRAPHICS ASSETS)
TIP: Since all of the icons are squares with the same width and height, if you name the icons with the word "icon" and one of the dimension value, (e.g., icon_60.png or icon_114.png) it will be easier to locate them wihen you need to upload them.
  1. Click on the Apps tab
  2. Click on the corresponding button (iOS7+, iOS6, Android or Default) for a given platform and for iOS click on both the Apps icons and Setting & Spotlight Icons options.
  3. Click the Plus (+) button for each type and navigate to the images that were created in the Creating Graphics Assets section of this tutorial.

iOS7+

iOS6

Android

All Android resource qualifiers which refer to device density and language.

/Default

The default icon must be named icon.png and must reside in the root of your application folder.

Splashes Tab

The Splashes tab is where you set the various splash screens images that are needed for the app store to market your app. They are requied on iOS but optional but highly recommended on Android.

  1. Click on the Splash Screens tab. See screenshot in Creating Graphic Assets under the Test App menu on how to create splash screens.
  2. Click on the corresponding button (iPhone, iPad, or Android)
  3. Click the Plus (+) button for each type and navigate to the images that were created in the Creating Graphics Assets section of this tutorial.

    NOTE: It is helpful to note the following dimensions:
    • the pair of values represents portrait (e.g. 640 x 960) and lanscape (e.g., 960 x 640) with the width and height being reversed.
    • the Non-Retina dimensions are half the height and width of the Retina dimensions.
    • the iOS6+/iOS6 iPhones dimensions are the same as the iPad - Retina and iPad Non-Retina.

iPhone

iPad

EXAMPLE: 

<platform name="ios">
    <splash src="res/screen/ios/Default~iphone.png" width="320" height="480"/>
    <splash src="res/screen/ios/Default@2x~iphone.png" width="640" height="960"/>
    <splash src="res/screen/ios/Default-Portrait~ipad.png" width="768" height="1024"/>
    <splash src="res/screen/ios/Default-Portrait@2x~ipad.png" width="1536" height="2008"/>
    <splash src="res/screen/ios/Default-736h.png" width="2208" height="1242"/>
    <splash src="res/screen/ios/Default-667h.png" width="750" height="1334"/>
    <splash src="res/screen/ios/Default-568h@2x~iphone.png" width="640" height="1136"/>
</platform>

Android

All Android resource qualifiers which refer to device density and language.

EXAMPLE CODE: The <icon> element is used with the "src" (source) and the "qualifier" attributes all six screen densities. You can also add "-port" or "-land" to each screen densities to specify if it will be in the portrait or landscape mode.

<platform name="android">
    <splash src="res/screen/android/drawable-port-ldpi-screen" qualifier="ldpi"/>
    <splash src="res/screen/android/drawable-port-mdpi-screen" qualifier="mdpi"/>
    <splash src="res/screen/android/drawable-port-hdpi-screen" qualifier="hdpi"/>
    <splash src="res/screen/android/drawable-port-xhdpi-screen" qualifier="xhdpi"/>
    <splash src="res/screen/android/drawable-port-xxhdpi-screen" qualifier="xxhdpi"/>
    <splash src="res/screen/android/drawable-port-xxxhdpi-screen" qualifier="xxxhdpi"/>
</platform>

Permissions Tab

The Permissions Tab is where you set the various types of permission and access to other web sites.

Permissions are only used by Android [and Windows??]. Users will see a request when they install an app about what permissions are needed (e.g., camera, location) for a given app. These permissions are mapped to a PhoneGap API.

Because an app runs in a browser, if it needs to access resources from another domain, you need to give it access to those remote resources by supplying the URL names and sub-domains (Instead of specifying sub-domain, you can get it full access by using the asterisk (*) as a wildcard (e.g., <access origin="*" subdomains="true"/>).

  1. Click the Permissions tab.
  2. Set Android permissions and access elements.




EXAMPLE CODE: 

<preference name="permissions" value="none"/>
<access origin="*" subdomains="true"/>

<allow-intent href="http://*/*"/>
<allow-intent href="https://*/*"/>
<allow-intent href="tel:*"/>
<allow-intent href="sms:*"/>
<allow-intent href="mailto:*"/>
<allow-intent href="geo:*"/>

<platform name="android">
  <allow-intent href="market:*"/>
</platform>

<platform name="ios">
   <allow-intent href="itms:*"/>
   <allow-intent href="itms-apps:*"/>
</platform>

Plugins Tab

You can include API Plugins or Available Plugins (e.g., scanner, social sharing) to extend the functionality of your app.

  1. Click the Plugins tab.
  2. Select the plug-ins you need for your app.

    NOTE: You will still need to write code for the plug-in to work in your app.
    API Plugins:


    Third-Party Plugins:


  3. After you have made all of the modification you need, select File > Save... from the menu to save all of the changes to the config.xml file.:
  4. (OPTIONAL) Open the config.xml file to see the configuration settings that it created.
  5. If necessary, move the config.xml file to the same level as the index.html file in the site.

NOTE: You can manually edit the config.xml file. However, a better approach is to reopen confiGAP again by selecting File > Open... from the menu to make any changes you want and then select File > Save... from the menu to save the updates.

EXAMPLE CODE:

 

Complete Sample File Explanation

The config.xml file is an XML file that is used to set the various attributes for the app:

NOTE: For a complete listing of preferences, go to http://docs.phonegap.com/. 
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" xmlns:gap = "http://phonegap.com/ns/1.0" 
id="com.richmediacs.adobeccapps" versionCode="1.0" version="1">
<name>Adobe CC Apps</name>
<description>What's New In Adobe CC for  DW, PS, AI and ID.</description>
<author href="http://www.richmediacs.com" email="cornelius@richmediacs.com">Cornelius Chopin</author>
<preference name="phonegap-version" value="cli-5.2.0" />
<preference name="orientation" value="default" />
<preference name="fullscreen" value="false" />
.
.
.
<gap:plugin name="org.apache.cordova.device" />
<gap:platform name="ios" />
<gap:platform name="android" />
<icon src="icons/icon36x36.png" gap:platform="android" gap:density="ldpi" />
<icon src="icons/icon48x48.png" gap:platform="android" gap:density="mdpi" />
<icon src="icons/icon72x72.png" gap:platform="android" gap:density="hdpi" />
<icon src="icons/icon96x96.png" gap:platform="android" gap:density="xhdpi" />
<icon src="icons/icon144x144.png" gap:platform="android" gap:density="xxhdpi" />
<icon src="icons/icon192x192.png" gap:platform="android" gap:density="xxxhdpi" />
<icon src="icon.png" />
</widget>

Configure Multiple Flavors (MOVE TO ANDROID STUDIO)

You can also use Android Studio to create multiple flavors.

In a new Android Studio project in the gradle.build file, the default config is called the default flavor. However, you can define multiple flavors with each flavor resulting in a unique APK file.

There are several reasons for creating multiple flavors:

  1. Select File > Project Structure... from the menu.


  2. In the Project Structure dialog box that appears, select or enter the following options:
    1. Choose the app module and click on the Flavors tab.
      NOTE: You see the default config flavor. Each flavor defines the properties on the right side of the screen.
    2. Click the plus (+) icon.
      WHY: To create a new flavor.
    3. Type a flavor (e.g., Demo) in the name field.
      NOTE: You should see it updated in the side panel. The new flavor will inherit all of the properties from the default configuration so you  only need to set properties that you want to change for that flavor.
    4. Go back to my default configuration, and copy the application ID.
    5. Go to the new flavor (e.g., Demo), and paste that application ID and I'll add .demo to the end (e.g., com.myAwesomeApp.demo).
      WHY: So the Demo flavor has its own unique application ID.
    6. Click the plus (+) icon again.
      WHY: To create another flavor.
    7. Name the flavor Full but don't reset any values.
      WHY: So that it inherit all of the properties from the default configuration.
    8. Click the OK button.
      NOTE: You will be returned to the gradle.build file and see the message that the "Gradle project is sync om progress."
    9. Select Build > Generate Signed APK... from the menu.
    10. Click the Next button (If you selected the Remember Passwords checkbox initially.)
    11. Click the Next button.
      NOTE: Notice now you see the two flavors that you created earlier.
    12. Select both flavors from the list and then click the Finish button.
    13. After a while, in the Generate signed APK dialog box that appears, you should see the message "Signed APK's generated successfully."
    14. Click the Show in Explorer button or Show in Finder button to open the APK file or navigate to where you saved it.


    15. Navigate to the directory where the APK were saved (e.g., desktop)
      NOTE: You should see there is one for demo and one for full. You can now submit this release version of the APK to the app store. You can create different behavior and different appearances in the different flavors. Go to the Google developer. website.(http://developer.android.com/tools/building/configuring-gradle.html) and click on the work with build variants link for details.