The application descriptor

IBM Worklight v5.0.5 > Develop IBM Worklight applications > Start with Worklight projects, applications, environments, and skins > Anatomy of an IBM Worklight Application
The application descriptor

Overview

The application descriptor defines aspects of the application...
/IBM/Worklight/ApplicationCenter/installer/IBMAppCenter/apps/AppCenter/application-descriptor.xml

Example format..
<?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">
Elements

The <application> element is the root element of the descriptor. It has two mandatory attributes:

id The ID must be identical to the application folder name. Alphanumeric string that starts with a letter. Can contain underscore ("_") characters. Must not be a reserved word in JavaScript.
platformVersion Contains the version of the IBM Worklight Platform on which the app was developed.
<displayName>First Country Bank</displayName>
<description>Manage your checking account using FCB's banking widget.</description>
The <displayName> and <description> elements contain the name and description of the application. They are displayed in the IBM Worklight Console and are copied to the descriptor files of various web and desktop environments.
<author>
    <name>ACME</name>
    <email> info@acme.com </email>
    <homepage> acme.com </homepage>
    <copyright> (C) ACME 2011 </copyright>
</author>
You can 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.
<height>410</height>
<width>264</width>
The <height> element is used to determine the height of the application on iGoogle and desktop environments.
The use of iGoogle is deprecated in Worklight version 5.0.5. Support might be removed in any future version.
The <width> element is used to set the width of the application on desktop environments.
<mainFile>fcb.html</mainFile>
<thumbnailImage>common/images/thumbnail.png</thumbnailImage>
The <mainFile> element contains the name of the main HTML file of the application.
The <thumbnailImage> element contains the path to and the name of the thumbnail image for the application. The path is relative to the main application folder.
<worklightServerRootURL> 
    https://www.acme.com/mobile-services 
</worklightServerRootURL>
The <worklightServerRootURL> is used to define the URL for accessing the WL server for mobile and desktop apps. It can be any URL of the form:
protocol://domain[:port][/path]

The element <worklightServerRootURL> replaces the former <worklightRootURL> element, which is deprecated and might not be supported in any future release.
<smsGateway id=kannelgw/>
The <smsGateway> element defines the SMS gateway to be used for SMS Push Notifications. It has one mandatory attribute:

id Contains the ID of the SMS gateway. The ID must match one of the gateway IDs defined in SMSConfig.xml.
<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>
<windowsPhone version="1.0">
  <uuid>62a2a2cf-0092-448e-8e7b-130687ca2938</uuid>
</windowsPhone>
<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 version="1.0" />
<vista version="1.0" />
<dashboard version="1.0" />
<air version="1.0" />
Each environment on which the application can run must be declared with a dedicated XML element. Each such element has one mandatory attribute, version. The value of this version is a string of the form x.y, where x and y are digits (0-9).

For mobile apps, the version is exposed to users who download the app from the app store or market.
For desktop apps, the version determines whether the WL server automatically downloads a new version of the app to the user's desktop
For web apps, the value of the version has no functional meaning and is available for documentation purposes only.
<iphone version="1.0" 
           bundleId="com.mycompany.myapp"> (or <ipad>)

    <pushSender password="${push.apns.senderPassword}"/>
    <worklightSettings include="true"/>
    <security> … </security>

</iphone>
In the <iphone> and <ipad> elements, provide the bundle ID of the application in the bundleId attribute. Each time the IBM Worklight builder builds your application, it copies the value of this attribute to the appropriate native configuration file in the Apple Xcode v4.5 project of the application. Do not modify this value directly in the native configuration file as it is overridden by the builder with the value you indicate in this attribute.
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 thus be encrypted.
The app user can use the IBM Worklight settings screen to change the address of the WL server with which the app communicates. To enable it for the app, specify the <worklightSettings> element. When enabled, the settings screen is accessible using the settings app on the iOS device.
<android version="1.0" 
         sharedUserId="com.mycompany">

    <pushSender key="AIzaSyDcSz7OvxQwr7XKg_0UdOaNJz0pYXuaS_c" 
                senderId="54385266031"/>

    <worklightSettings include="true"/>

    <security> … </security>

</android>
The sharedUserId attribute is optional; it is required only when device provisioning is activated on the application by specifying the <authentication> element. sharedUserId allows multiple applications with the same value for this attribute to access the same keystore item on the device. The applications can thus use the same secure device ID assigned to the device by the IBM Worklight app.
Android apps that have the same sharedUserId but are signed with a different certificate cannot be installed on the same device.
For Android apps that use the Google GCM (Android push notification services), use the <pushSender> element to define the connectivity details to the Android push notification service. The key is the GCM API key, and the senderId is the GCM Project Number.
The app user can use the IBM Worklight settings screen to change the address of the WL server with which the app communicates. To include it in the app, specify the <worklightSettings> element. When the screen is included in the app, a menu item is automatically appended to the options menu of the app. Users can tap this menu item to reach the screen.
<windowsPhone8 version="1.0">
    <uuid>87e096eb-6882-4cef-9f66-e68769de3926</uuid>
</windowsPhone8>
The <uuid> element is used to uniquely identify a Windows Phone 8 application on the device. It is automatically generated by the IBM Worklight Studio when you create the Windows Phone 8 environment for the application.
<windowsPhone version="1.0">
    <uuid>62a2a2cf-0092-448e-8e7b-130687ca2938</uuid>
</windowsPhone>
The <uuid> element is used to uniquely identify a Windows Phone 7 application on the device. It is automatically generated by the IBM Worklight Studio when you create the Windows Phone 7 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>
The <windows8> element contains the following subelements:

<certificate> Use the <certificate> subelement to sign the Windows 8 application before publishing it.
<uuid> Use the <uuid> subelement to uniquely identify a Windows 8 application. It is automatically generated by the IBM Worklight Studio when you create the Windows 8 environment for the application.
<mobileDeviceSSO join="true" />
When this element is specified, device SSO is enabled for the application. Thus, when a session requires authentication in a realm and there is already an active session from the same device authenticated in that realm, the authentication details from the existing session are copied to the new session. The user experience implications are that the user does not have to reauthenticate when starting the new session.
<air version="1.0" showOnTaskbar="always">
    <certificate password="password" PFXFilePath="path-to-pfx"/>
</air>
The optional <air> element has the following structure:

The showOnTaskbar attribute determines behavior of the AIR application on the taskbar.
Use the <certificate> element to sign the AIR application before publishing it.
<facebook version="1.0" loginDisplayType="type" />
<igoogle version="1.0" loginDisplayType="type" />
The use of the <facebook> and <igoogle> elements is deprecated in Worklight version 5.0.5. Support might be removed in any future version.
The <facebook> and <igoogle> elements receive a loginDisplayType attribute, which can be used to specify how the app login screen is displayed. type can be one of the following values:

popup To log in to a separate browser window.
embedded To embed the login form within the application frame.
<loginPopupHeight> Height in pixels </loginPopupHeight>
<loginPopupWidth> Width in pixels </loginPopupWidth>
When login is configured as popup, provide the dimensions of the login window.
<vista version="1.0" />
<dashboard version="1.0" />
The use of the <vista> and <dashboard> elements is deprecated in Worklight version 5.0.5. Support might be removed in any future version.
</application>
The closing tag.

The security element

The security element occurs under the <iphone>, <ipad>, and <android> elements, and is used to configure security mechanisms for protecting your iOS and Android apps against various malware and repackaging attacks.
The element has the following structure:
<security>
    <encryptWebResources enabled="false"/>

    <testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3"/>

    <publicSigningKey> value </techSigningKey>
</security>
The element <encryptWebResources> controls whether the web resources associated with the application are packaged and encrypted within the application binary file (a file with the extension .apk or .app). If its enabled attribute is set to true, the IBM Worklight builder encrypts the resources. They are then decrypted by the application when it first runs on the device.
The element <testWebResourcesChecksum> 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 it with a value stored when it was first run. Checksum calculation can take a few seconds, depending on the size of the web resources. To make it faster, you can provide a list of file extensions to be ignored in this calculation.
The element <publicSigningKey> is valid only in the Android environment, under <android>/<security>. This element contains the public key of the developer certificate that is used to sign the Android app. For instructions on how to extract this value, see Extract a public signing key

Deprecated elements

The following elements have been deprecated since version 4.1.3:
<provisioning>
<viralDistribution>
<adapters>
<mobile>
The following elements have been deprecated since version 5.0:
<worklightRootURL>
The following elements have been deprecated since version 5.0.0.3:
<usage>
The following elements have been deprecated since version 5.0.5:
<dashboard>
<facebook>
<igoogle>
<vista>
Parent Anatomy of an IBM Worklight Application

+
Search Tips | Advanced Search

id	The ID must be identical to the application folder name. Alphanumeric string that starts with a letter. Can contain underscore ("_") characters. Must not be a reserved word in JavaScript.
platformVersion	Contains the version of the IBM Worklight Platform on which the app was developed.

<certificate>	Use the <certificate> subelement to sign the Windows 8 application before publishing it.
<uuid>	Use the <uuid> subelement to uniquely identify a Windows 8 application. It is automatically generated by the IBM Worklight Studio when you create the Windows 8 environment for the application.

popup	To log in to a separate browser window.
embedded	To embed the login form within the application frame.