HowTo: Versioning Your Smart Device Application

Official Content
This documentation is valid for:

The application versioning is a critical component its maintenance. Every end user needs specific information about the application version that is installed on their devices and which upgrade version is available for installation.

Also, the application may need to query the system for your application's version, to determine compatibility and identify dependencies. For example, publishing service may need to check the application version to determine compatibility and establish upgrade/downgrade relationships. The native apps generated by GeneXus are installed on the smart devices, so when you are about to launch a new version of your app you take chances that your older version quits working or start bugging because some changes have been made on the server side of your application.


Little of background

The core of every GeneXus smart device application is the Flexible Client. This fact means that the app can detect whether the server has a newer or an update version of the metadata and then begin to behave using that version.

Flexible Clients brings up many advantages:

  • You can update some parts of your app without the need of waiting for the whole approving stages of the markets.
  • The older clients are advised that an update is needed and automatically start to update the client version.

However, this does not cover every scenario. For example, when newer versions have some changes its binary code, such as a new User Control, the Flexible Client is not going to be able to update itself to the newer version. In this case, there is a "Not Supported Client scheme" that is going to be applied. To sum up, if the version of the metadata needs to be updated (a minor change occurs), as a developer you want your app to automatically start updating. On the other hand, if there is a scenario of "Not Supported client scheme" (a major change occurs) the best option is that the application redirects the user to the store to download the most recent version.

So this document explains how versioning is used in GeneXus for Smart Devices by developing a simple example.


Main components

There are three properties per platform in the Smart Devices Main object level involved in the versioning process.

  • Version code
    A string value composed of two numbers X and Y separated by a '.' (dot) that represents the version of the application, relative to others. The X indicates a major upgrade and Y a minor upgrade. For example, a value of "2.4" means that the application was upgraded two times in a major way and four times in a minor way relative to the major version.
  • Version name 
    A string value that represents the release version of the application as it is shown to the end user. For simplicity, it should have the same value as the above property followed by a dot and a build number (e.g. "2.4.126").
  • Where the application must be updated
    An URL where the application can be downloaded (usually, a store) in case that the end user needs a major upgrade.

Let's see the behavior on each platform.

Android specific

Android Version Code property Every time that the developer publishes a newer version of the application (the *.apk file), an upgrade of this value is required by Google Play Store (or another store). Otherwise, it will display an error message like this:
Versioning - Android - Upload fail caused by same code version
Android Version Name property The version which is displayed in the app details of the store.
Versioning - Android - Version name in Play Store
Update URL property (1) Refer to this document.

iOS specific

Apple Version Code property It has the same meaning as the Android's version of this property after following the process of how to upgrade the application on the Apple App Store.
Apple Version Name property   It applies the same concept of Android's version of this property but only on the Apple App Store.
Versioning - iOS - Version name in App Store
App Store URL The URL of the iTunes website where the application is hosted. It takes the following aspect:<your_apple_app_identifier>  (e.g.
Where the Apple App ID is provided once the application is published (it can be queried on iTunes Connect).
Versioning - iOS - App ID from iTunes Connect
For advanced users, it can also be a custom URL pointing to a manifest.plist file as follows.
The <url_to_the_manifest.plist_file> must be escaped (e.g. the URL should be written as


Behavior when versioning

Minor change case

For minor changes or changes that our app can update itself, we can change the number after the '.' (dot) as follows. This action will make the app in our device to automatically update the metadata information.

  Current version   Newer version
Versioning - Android - Step 1 Flecha_der Versioning - Android - Step 2
Versioning - iOS - Step 1 Flecha_der Versioning - iOS - Step 2


  Detect new version  Update finished
iOS-Minor-Step1_gif iOS-Minor-Step2_gif

Major change case

For major changes in where the app must be upgraded by downloading it from the store we can change the number before the '.' (dot) as follows. This action will force the end user to redirect to the store by its URL and download the newer version of the app.

  Current version   Newer version
Versioning - Android - Step 2 Flecha_der Versioning - Android - Step 3
Versioning - iOS - Step 2 Flecha_der Versioning - iOS - Step 3


  Detect new version  Redirect to the store  Start updating 
Versioning - Android - Major - Step 1 Versioning - Android - Major - Step 2 Versioning - Android - Major - Step 3
iOS-Major-1_png iOS-Major-2_png  



(1) Replacement of Android Google Play URL property that enhanced the possibility of including other URL's stores instead of just Google Play.


See also