The application descriptor

The application descriptor

The application descriptor is a metadata file used to define various aspects of the application. It is in the application root directory.

General structure

The application descriptor is a metadata file used to define various aspects of the application. It is in the application root directory and has the name application-descriptor.xml.
The following example shows the format of the file:
<application>
The <application> element is the root element of the descriptor. The </application> element is the closing tag.
<?xml version="1.0" encoding="UTF-8"?>
<application id="fcb" platformVersion="5.0">
xmlns="http://www.example.com/application-descriptor" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xsi:schemaLocation="http://www.example.com/application-descriptor
../../../../../gadgets/application-descriptor/src/main/resources/schema/application-descriptor.xsd">
The root element takes two mandatory attributes.

id

Contains the identifier of the application. The identifier must be identical to the application folder name. It must be an alphanumeric string that starts with a letter. It can also contain underscore ("_") characters. It must not be a reserved word in JavaScript.

platformVersion

Contains the MPF version on which the application was developed.
<displayName> and <description>
The <displayName> and <description> elements contain the name and description of the application. They are displayed in the operations console and are copied to the descriptor files of various web and desktop environments.
<displayName>First Bank</displayName>
<description>Conveniently and securely manage the checking, savings, and credit card accounts using FCB's banking widget.</description>
<author>
Use the <author> element and its subelements to provide information about the application author. This data is copied to the descriptor files of the web and desktop environments that require it.
<author>
<name>ACME</name>
<email> info@acme.com </email>
<homepage> acme.com </homepage>
<copyright> (C) ACME 2014 </copyright>
</author>
<mainFile> and <thumbnailImage>
The <mainFile> element contains the name of the main HTML file of the application.
The <thumbnailImage> element contains the path to the thumbnail image for the application, including the image file name. The path is relative to the main application folder.
<mainFile>index.html</mainFile>
<thumbnailImage>common/images/thumbnail.png</thumbnailImage>
<smsGateway>

The <smsGateway> element defines the SMS gateway to be used for SMS push notifications. It has one mandatory attribute, id, which contains the identifier of the SMS gateway. The ID must match one of the gateway identifiers that are defined in the SMSConfig.xml file.
<smsGateway id="kannelgw"/>

<tags>
The <tags> element is supported by Android, iOS and Windows Phone 8 environments. During application deployment, the specified tags are created, updated, or deleted on the MobileFirst management database tables. In the following example, the <tags> specifies customer categories. Tags represent topics of interest to the user and provide user with an ability to receive notifications according to the chosen interest. This feature enables ability for sending and receiving messages by tags. A message is targetted to only the devices subscribed for a tag.
<tags>
  <tag>
    <name>Silver</name>
    <description>Silver customers</description>
  </tag>
  <tag>
    <name>Gold</name>
    <description>Gold customers</description>
  </tag>
</tags>
environment <version>
Each environment on which the application can run must be declared with a dedicated XML element: <iphone>, or <ipad>. Each such element has one mandatory attribute: version (except for web apps). The value of the version attribute is a string of the form x.y, where x and y are digits (0-9).

For mobile apps, the version is shown to users who download the app from the app store or market.

For desktop apps, the version determines whether MobileFirst Server automatically downloads a new version of the app to the user's desktop.
<iphone version="1.0" />
<android version="1.0" />
<blackberry10 version="1.0" />
<blackberry version="1.0" />
<windowsPhone8 version="1.0">
  <uuid>87e096eb-6882-4cef-9f66-e68769de3926</uuid>
</windowsPhone8>
<windows8 version="1.0">
  <certificate PFXFilePath="Path to certificate file" password="certificate password"/>
  <uuid>556a98a3-63fb-4602-827c-0b6bd9d00490</uuid>
</windows8>
<ipad version="1.0" />
<mobileWebApp />
<air version="1.0" />
bundleId
In the <iphone> and <ipad> elements, provide the bundle ID of the application in the bundleId attribute. Each time the MPF builder builds the application, it copies the value of this attribute to the appropriate native configuration file in the Xcode project of the application. Do not modify this value directly in the native configuration file because it is overridden by the builder with the value that you indicate in this attribute.
<iphone version="1.0" bundleId="com.mycompany.myapp"> (or <ipad>)
<pushSender password="${push.apns.senderPassword}"/>
<worklightSettings include="false"/>
<security> … </security>
</iphone>
For iOS apps that use the Apple Push Notification Service (APNS), use the <pushSender> element to define the password to the SSL certificate that encrypts the communication link with APNS. The password attribute can refer to a property in worklight.properties and can therefore be encrypted.
The app user can use the MobileFirst settings page to change the address of the MobileFirst Server with which the app communicates. By default, the settings page is disabled. To enable it for the app, change the include attribute of <worklightSettings> element to true. When the settings page is enabled, that page is accessible using the settings app on the iOS device.

For Android apps that use Google Cloud Messaging (GCM), use the <pushSender> element to define the connectivity details to GCM. The key is the GCM API key, and the senderId is the GCM Project Number.
For more information about GCM API key and GCM Project Number, see the Enable the GCM Service page on the Android website for developers.
The app user can use the MobileFirst settings page to change the address of the MobileFirst Server with which the app communicates. By default, the settings page is disabled. To enable it for the app, change the include attribute of the <worklightSettings> element to true. When the page is included in the app, for Android, a menu item is automatically appended to the options menu of the app. Users can tap this menu item to reach the page.

See The <security> element.
sharedUserId
The sharedUserId attribute is optional. Set it only when device provisioning is activated on the application by the <authentication> element. When the sharedUserId attribute is set, multiple applications with the same value for this attribute can access the same keystore item on the device. The applications can thus use the same secure device ID as the one assigned to the device by the MobileFirst app.
Android apps that have the same sharedUserId but are signed with different certificates cannot be installed on the same device.
<android version="1.0" sharedUserId="com.mycompany">
<pushSender key="AIzaSyDcSz7OvxQwr7XKg_0UdOaNJz0pYXuaS_c" senderId="54385266031"/>
<worklightSettings include="false"/>
<security> … </security>
</android>
<windowsPhone8>
The <windowsPhone8> element has three subelements:
The <uuid> subelement is used to uniquely identify a Windows Phone 8 application on the device. It is automatically generated by MobileFirst Studio when you create the Windows Phone 8 environment for the application.

For Windows Phone 8 apps that use the Microsoft Push Notification Service (MPNS), use the <pushSender> subelement to indicate that the app is a "pushable" application. That is, the app subscribes to event sources and receives push notifications. You also use the <pushsender> subelement to set attributes for authenticated push. See Set up push notifications for Windows Phone 8.
The <allowedDomainsForRemoteImages> subelement is used to enable the application tile to access remote resources. Use subelement <domain> within <allowedDomainsForRemoteImages> to define the list of allowed remote domains from which to access remote images. Each domain in the list is limited to 256 characters.
We cannot add thee <allowedDomainsForRemoteImages> subelement to the application descriptor using the Design editor. We must use the Source editor instead.
<windowsPhone8 version="1.0">
<uuid>87e096eb-6882-4cef-9f66-e68769de3926</uuid>
<pushSender/>
<allowedDomainsForRemoteImages>
  <domain>http://icons.aniboom.com</domain>
  <domain>http://media-cache-ec2.pinterest.com</domain>
</allowedDomainsForRemoteImages>
</windowsPhone8>
<windows8>
The <windows8> element contains the following subelements:

Use the <certificate> subelement to sign the Windows 8 application before you publish it. See Signing Windows 8 apps.

Use the <uuid> subelement to uniquely identify a Windows 8 application. The UUID is automatically generated by MobileFirst Studio when you create the Windows 8 environment for the application.
<windows8 version="1.0">
<certificate PFXFilePath="Path to certificate file" password="certificate password"/>
<uuid>556a98a3-63fb-4602-827c-0b6bd9d00490</uuid>
</windows8>
<mobileDeviceSSO>

When the <mobileDeviceSSOelement> element is specified, device single sign-on (SSO) is enabled for the application. Therefore, when a session requires authentication in a realm and a session is already active from the same device as authenticated in that realm, the authentication details from the existing session are copied to the new session. The user does not have to re-authenticate when starting the new session.
<mobileDeviceSSO join="true" />

<air>
The optional <air> element has the following structure:

The showOnTaskbar attribute determines behavior of the AIR application on the taskbar. See Specify the application taskbar for Adobe AIR applications.

Use the <certificate> element to sign the AIR application before you publish it. See Signing Adobe AIR applications.

Use the <height> element to determine the height of the application on desktop environments.

Use the <width> element to set the width of the application on desktop environments.
<air version="1.0" showOnTaskbar="always">
<certificate password="password" PFXFilePath="path-to-pfx"/>
<height>410</height>
<width>264</width></air>
<popup>
When login is configured as popup, we must provide the dimensions of the login window.
<loginPopupHeight> Height in pixels </loginPopupHeight>
<loginPopupWidth> Width in pixels </loginPopupWidth>
The <security> element

The <security> element is a subelement of the <iphone>, <ipad>, <android>, and <windowsPhone8> elements. It is used to configure security mechanisms for protecting the iOS, Android, and Windows Phone 8 apps against various malware and repackaging attacks. The element has the following structure:

<encryptWebResources>

The <encryptWebResources> element controls whether the web resources that are associated with the application are packaged and encrypted within the application binary file (a file with the .apk or .app name extension). If its enabled attribute is set to true, the MPF builder encrypts the resources. The application decrypts them when it first runs on the device.

<testWebResourcesChecksum>

The <testWebResourcesChecksum> element controls whether the application verifies the integrity of its web resources each time it starts running on the mobile device. If its enabled attribute is set to true, the application calculates the checksum of its web resources and compares the checksum with a value that was stored when the application was first run. Checksum calculation can take a few seconds, depending on the size of the web resources. To make it faster, we can provide a list of file extensions to be ignored in this calculation.

<publicSigningKey>

The <publicSigningKey> element is valid only in the Android environment, under <android>/<security>. This element contains the public key of the developer certificate used to sign the Android app. For instructions on how to extract this value, see Extracting a public signing key.

<productId>

The <productId> element is valid only in the Windows Phone 8 environment, under <windowsPhone8>/<security>. Default is the GUID for the project (128 bit). During the app submission process, a new product ID is inserted into the WMAppManifest.xml file.

<applicationId>

The <applicationId> element is valid only in the Windows Phone 8 environment, under <windowsPhone8>/<security>. The application ID value must match the value of the wlAppId property, located in the wlclient.properties file.
<security>
<encryptWebResources enabled="false"/>
<testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3"/>

<publicSigningKey> value </publicSigningKey> 

<productId>22cbbacb-e323-4419-befb-d3aff42f2126</productId>
<applicationId>MyProj</applicationId>
</security>
The <features> element

Since IBM Worklight v6.0.0, we can control which features are included in the application. This capability gives you a finer degree of control over the size of your application, and therefore over its capacity to download and start quickly.
In application-descriptor.xml, the <features> element is added automatically when the application is first created, but with no contents. If later we add JSONStore features and want to include these resources in the application build, we can edit the <features> element. We can do so using the Application Descriptor Editor or an XML editor, as shown in the following example:
<application xmlns="http://www.worklight.com/application-descriptor" id="MyProj" platformVersion="6.0.0">
      ...
    <features>
        <JSONStore/>
    </features>
</application>
If we do not include JSONStore in the build but use it in the code, an error is raised when we run the app, and we can add it to the <features> element with a QuickFix.
If, during the testing phase, you find that the application does not use the JSONStore resources, we can reduce the size of the Android app by removing the JSONStore argument from the <features> element. When we add or remove a feature, build the application again for the change to take effect.
The JSONStore resources are still included in the iOS application builds.
For more information about the <features> element, see Including and excluding application features.

The <cacheManifest> element

A new element now exists in the application-descriptor.xml named <cacheManifest>. By using this element, we can manage and edit the contents of the application cache for Desktop Browser and Mobile Web applications, and thus control which resources are fetched when the application starts. Unused resources such as large images or unused files, when included in the Cache Manifest file, increase the startup time for these applications. By editing this file, we can remove these unnecessary resources and speed up the application.
The cacheManifest element accepts three values, as shown in the following table.

Property Description
no-use In this mode (which is the default), the cache manifest is not included in the application HTML files. This setting means that there is no cache manifest and that decisions about which resources are cached are up to the browser.
generated In this mode, the MobileFirst Studio builder generates a default cache manifest and includes it in the application HTML files. The default cache manifest is generated depending on the environment:

For Desktop Browser environments, all resources are under NETWORK, which means: no cache at all.

For Mobile Web environments, all resources are under CACHE, which means: cache everything.

In generated mode, in addition to creating the cache manifest, the builder creates a backup of the previous cache manifest, called worklight.manifest.bak. This file is overwritten in every build.
user In this mode, the MobileFirst Studio builder does not generate the cache manifest, but it does include it in the application HTML files. This setting means that the user must maintain the cache manifest manually.

If we open the application descriptor in Design view, we can view and set the current mode of the <cacheManifest> element with the DDE editor:

In Design view, each option is given a description:

Not Included in the application (default): no-use mode

Managed by Worklight: generated mode

Managed by user: user mode

We can also edit the value in the <cacheManifest> element of application-descriptor.xml itself, as shown in the following code sample:
<application xmlns="http://www.worklight.com/application-descriptor" id="MyProj" platformVersion="6.0.0">
      ...
    <mobileWebApp cacheManifest="generated"/>
    <desktopBrowser cacheManifest="generated"/>
</application>
For more information about the cache manifest, see Application cache management in Desktop Browser and Mobile Web apps.

The <languagePreferences> element

The<languagePreferences> element contains a comma-separated list of languages to enforce IBM MobileFirst Platform Foundation to display system messages. See Enforce language preference for MobileFirst messages.

Deprecated elements

The following table lists deprecated and removed elements:

Element IBM MobileFirst Platform Foundation version

<provisioning>
<viralDistribution>
<adapters>
<mobile>
Deprecated as of V4.1.3
<worklightRootURL Deprecated as of V5.0
<usage> Deprecated as of V5.0.0.3
<worklightServerRootURL> This element was a replacement for <worklightRootURL> and was removed in IBM Worklight v6.0.0:

Parent topic: Anatomy of a MobileFirst application

Element	IBM MobileFirst Platform Foundation version
<provisioning> <viralDistribution> <adapters> <mobile>	Deprecated as of V4.1.3
<worklightRootURL	Deprecated as of V5.0
<usage>	Deprecated as of V5.0.0.3
<worklightServerRootURL>	This element was a replacement for <worklightRootURL> and was removed in IBM Worklight v6.0.0: