The application descriptor

<application>

<application id="App_Test" platformVersion="7.1.0"
  xmlns="http://www.worklight.com/application-descriptor" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

Attributes

Elements

<accessTokenExpiration>

Optional.

Defines the expiration period (in seconds) of OAuth access tokens. The default is 3600 seconds (one hour).

Client applications can use the token to access protected resources as long as the token has not expired. When the token expires, the client application has to obtain a new access token to access a protected resource. Obtaining a new access token may happen automatically without user intervention if all the realms by which the resource is protected have not expired. However, if one of the realms that is included in the security test of the resource has expired, and the realm requires user input (such as a form-based authenticator), the user has to re-authenticate.

<accessTokenExpiration>360</accessTokenExpiration>

<author>

Provides information about the application author. This data is copied to the descriptor files of the web and desktop environments that require it.

<description>

Description of the application. The description is displayed in the MobileFirst Operations Console and is copied to the descriptor files of various web and desktop environments.

<directUpdateAuthenticityPublicKey>

Optional.

<displayName>

The name of the application. The name is displayed in the MobileFirst Operations Console and is copied to the descriptor files of various web and desktop environments.

Note: This element supports English only.

<environment>

Each environment on which the application can run must be declared with a dedicated XML element: For example, iphone, or windowsPhone8. The following example shows the possible values for environment:

<iphone version="1.0" />
<android version="1.0" />
<blackberry10 version="1.0" />
<blackberry version="1.0" />
<windowsphoneuniversal version="1.0" />
  <uuid>34e026eb-6652-4ab-9f66-m68195re2931</uuid>
<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" />

Each such environment element has one mandatory attribute: version (except for web apps). See version for details.

<features>

Controls which features are included in your 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.

This element is added automatically with no contents when the application is first created. If later you add JSONStore features and want to include these resources in the application build, you can edit the <features> element.

If you do not include JSONStore in the build but use it in your code, an error is raised when you run the app, and you can add it to the <features> element with a QuickFix.

If, during the testing phase, you find that your application does not use the JSONStore resources, you can reduce the size of your Android app by removing the JSONStore argument from the <features> element. When you add or remove a feature, build the application again for the change to take effect.

Note: The JSONStore resources are still included in your iOS application builds.

For more information about the <features> element, see Including and excluding application features.

<licenseAppType>

Declares the application type for token licensing. This element is ignored if the MobileFirst Server does not have token licensing activated.

Possible values (values are case-sensitive; must be all uppercase):

• NON_PRODUCTION: Use this while you are developing and testing the application on the production server.
  Important: Using NON_PRODUCTION for a production app is a breach of the license terms.
• APPLICATION: Use this for most applications when you are ready to deploy the app on a production server. This is the default. The production server must have token licensing activated, and enough tokens must be available.

• ADDITIONAL_BRAND_DEPLOYMENT: Use this when you are ready to deploy an additional brand deployment app on a production server. The app must be an additional brand deployment of an existing app for which an APPLICATION token has already been used. Your organization must have purchased an Additional Brand Deployment license for you to use this option. In addition, the code in the similar application must meet specific requirements such as the percentage of code that is different. Refer to your IBM MobileFirst™ Platform Foundation - Additional Brand Deployment software license for details.

  The production server must have token licensing activated, and enough tokens must be available.

If token licensing is activated on the server and this element is not present in the application descriptor, then the default setting APPLICATION is used.

For more information, see Licensing in MobileFirst Server and your IBM MobileFirst Platform Foundation software license.

Note: Token licensing, as defined by <licenseAppType> is not related to Oauth access tokens, as defined by <accessTokenExpiration>.

<languagePreferences>

Contains a comma-separated list of languages to display system messages. For more information, see Enforce language preference for MobileFirst messages.

<loginPopupHeight> and <loginPopupWidth>

When login is configured as popup, you must provide the dimensions of the login window.

<loginPopupHeight> Height in pixels </loginPopupHeight>
<loginPopupWidth> Width in pixels </loginPopupWidth>

<mainFile>

Contains the name of the main HTML file of the application.

<smsGateway>

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/>

<targetCategory>

Declares the target category of your application. You can generate more accurate license reports for the ADDRESSABLE DEVICE license metric. This element is added automatically when the application is created. By default, the target category is set to UNDEFINED. If your application is licensed under the ADDRESSABLE DEVICE metric, you must edit this element to specify the relevant target category.

Possible values:

• UNDEFINED
• B2E: IBM MobileFirst Platform Foundation Enterprise
• B2C: IBM MobileFirst Platform Foundation Consumer

<thumbnailImage>

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>

<userIdentityRealms>

A comma-separated ordered list of user identity realms for OAuth authentication. The realms should be ordered by preference. The first successfully authenticated realm in this list is selected as the user identity realm. If the list is empty, or no realm in the list was authenticated, the ID token contains no identity information. This element is optional and the default value is an empty list.

<userIdentityRealms>WASLTPARealm, CustomAuthenticatorRealm</userIdentityRealms>

Note: This attribute is used to set user identity in the OAuth-based flows. For the classic (pre-V7.0) flows, see the documentation for the customSecurityTest security test.

Sub-attributes

applicationId

Optional.

This attribute specifies the name of the application, as specified in the worklight.plist file. The values in the application-descriptor.xml and worklight.plist must match, and the value of applicationId must be the same as the value of id. This attribute is required if you use the IBM MobileFirst Platform Foundation classic security model. For more information, see MobileFirst application authenticity overview.

bundleId

Mandatory for iOS target environments. Not applicable to other target environments.

This attribute is copied 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.

cacheManifest

Manages and edits the contents of the application cache for Desktop Browser and Mobile Web applications, and controls 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. If you edit this file, you can remove these unnecessary resources and speed up your application.

The following values are valid modes.

no-use

Default mode. The cache manifest is not included in the application HTML files. There is no cache manifest, so decisions about which resources are cached are decided by the browser.

generated

The builder generates a default cache manifest and includes it in the application HTML files.

• 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.

The builder also creates a backup of the previous cache manifest, called worklight.manifest.bak. This file is overwritten in every build.

user

The builder does not generate the cache manifest, but it does include it in the application HTML files. You must maintain the cache manifest manually.

If you open the application descriptor in Design view, you can view and set the current mode of this 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

For more information about the cache manifest, see Application cache management in Desktop Browser and Mobile Web apps.

showInTaskbar

Determines behavior of the AIR application on the task bar. For more information, see Specifying the application taskbar for Adobe AIR applications.

version

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.

Sub-elements

<allowedDomainsForRemoteImages>

• <windowsPhone8>: Enables the application tile to access remote resources. Use subelement <domain> to define the list of allowed remote domains from which to access remote images. Each domain in the list is limited to 256 characters.
  Note: You cannot add this subelement to the application descriptor by using the Design editor. You must use the Source editor instead.

<certificate>

• <air>: Sign the AIR application before you publish it. For more information, see Signing Adobe AIR applications.
• <windows8>: Sign the Windows 8 Universal application before you publish it. For more information, see Signing Windows 8 Universal apps.

<height>

Determine the height of the application on desktop environments.

<pushSender>

• <iphone> or <ipad>: For iOS apps that use the Apple Push Notification Service (APNS). Defines the password to the SSL certificate that encrypts the communication link with APNS. The password attribute can refer to a property in the worklight.properties file and can therefore be encrypted.
• <android>: 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 Enabling the GCM Service page on the Android website for developers.
• <windowsPhone8>: For apps that use the Microsoft Push Notification Service (MPNS), you can indicate that the app is a "pushable" application. That is, the app subscribes to event sources and receives push notifications. You can also set attributes for authenticated push. For more information, see Setting up push notifications for Windows Phone Silverlight 8.

<security>

A subelement of the <iphone>, <ipad>, <android>, <windowsPhone8>, <windows8>, and <windowsphoneuniversal> elements. It is used to configure security mechanisms for protecting your apps against various malware and repackaging attacks. The element has the following structure:

<encryptWebResources>

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 builder encrypts the resources. The application decrypts them when it first runs on the device. Not supported on Windows Phone Silverlight 8, Windows 8 Universal, and Windows Phone 8 Universal.

<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 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, provide a list of file extensions to be ignored in this calculation. Supported on Android, iOS, Windows 8 Universal, and Windows Phone 8 Universal.

<publicSigningKey>

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 Extracting a public signing key.

<productId>

Valid only in the Windows Phone Silverlight 8 environment, under <windowsPhone8>/<security>. The default value 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>

Valid in the Windows Phone Silverlight 8 environment, under <windowsPhone8>/<security>. This element is also valid in the Windows 8 Universal environment, under <windows8>/<security> and in the Windows Phone 8 Universal environment, under <windowsphoneuniversal>/<security>. The application ID value must match the value of the wlAppId property that is located in the wlclient.properties file.

<packageName>

Valid only in the Android, Windows 8 Universal, and Windows Phone 8 Universal environments. For Android, this element is required under <android>/<security>. This element is optional for all Windows platforms. If used for Windows 8 Universal, add it under <windows8>/<security>. If used for Windows Phone 8 Universal, add it under <windowsphoneuniversal>/<security>. This element is the family name of the package and the value can be picked up from the package.appxmanifest file.

For example:

<security>
  <encryptWebResources enabled="false"/>
  <testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3"/>
  <!-- publicSigningKey is valid only for Android -->
  <publicSigningKey> value </publicSigningKey> 
  <!-- productId is valid only for Windows Phone Silverlight 8 -->
  <productId>22cbbacb-e323-4419-befb-d3aff42f2126</productId>
  <!-- applicationId is valid for Windows Phone Silverlight 8, Windows 8 Universal, and Windows Phone 8 Universal -->
  <applicationId>MyProj</applicationId>
  <!-- packageName is valid for Android, Windows 8 Universal and Windows Phone 8 Universal -->
  <packageName>4d0fb885-07fd-4d16-897d-255ab527486e_vr9ykqv283qqw</packageName>
</security>

<tags>

Supported by Android, iOS, Windows Phone Silverlight 8, Windows 8 Universal, and Windows Phone 8 Universal environments. During application deployment, the specified tags are created, updated, or deleted on the 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 targeted 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>

For more information about the setting of Tag-based notification, see Setting up Tag-based notifications.

<width>

Set the width of the application on desktop environments.

<worklightSettings>

You can use the 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 element to true. When the settings page is enabled, that page is accessible by using the settings app on the iOS device.

<uuid>

Uniquely identifies an application. The UUID is automatically generated when you create the environment for the application. Required for the following target environments:

• Windows Phone Silverlight 8
• Windows 8 Universal
• Windows Phone 8 Universal

Deprecated elements