Release Over the Air Updates with App Center's CodePush

Last update: Edit

1 Introduction

Using Native Mobile Builder and Mendix Studio Pro, you can update your Mendix native apps over the air (OTA). OTA updates are a fast and painless way of updating elements like layouts, pages, assets, or even your app’s business logic (such as nanoflows and JavaScript actions).

Native apps are separated into two parts: a wrapper that functions as a native iOS or Android app, and a bundle loaded dynamically by the wrapper. Elements like your business logic and static assets are part of this dynamically-loaded bundle. When you have changes you want to deploy, the Native Mobile Builder can bundle them in a new, updated bundle and painlessly deploy them. On the next app restart, your end-users will be updated to the latest version and continue their business as usual.

OTA updates are bound to a specific app version and build number. Therefore, you can target specific updates to specific versions of your app. For example, you can push an update for version 1.0.0 as a legacy version that supports older devices, and also push an update for the 2.0.0 version of your app which includes more features.

This how-to will teach you how to do the following:

  • Build an app that can use CodePush OTA updates
  • Push an OTA update for a released app
  • Preserve your model’s integrity
  • Transfer a CLI OTA-compatible app to the Native Mobile Builder

2 Prerequisites

Before starting this how-to, make sure you have completed the following prerequisites:

  • Deploy your app by completing How to Deploy Your First Mendix Native Mobile App.
  • Ensure you have set up and configured App Center for your app. For information on setting up App Center, see the App Center Token section of How to Deploy Your First Mendix Native Mobile App. If you previously opted out of configuring App Center while building your app, you must navigate to the Tokens screen and toggle on the I want to use App Center option.
  • Install your app on a test device or emulator.
  • Read the Offline-First reference guide. Understand this document before issuing OTA updates or releasing new versions.

3 When to Use OTA Updates

3.1 Safely Pushing OTA Updates Without Redeploying

It is good practice to always redeploy your Mendix app before pushing a new OTA update. However, releasing an OTA update without redeploying your Mendix app to Mendix Cloud in these cases is usually safe:

  • Style changes
  • Static image, text, or other static asset changes
  • Layout changes
  • Nanoflow changes
  • JavaScript action changes
  • Widgets added or removed
  • A new custom Javascript-only widget or module was added
  • Non-destructive model changes (for more information, see Offline-First)

3.2 When a Full Release Is Required

If you have made any changes directly to your iOS or Android app, you will have to fully redeploy your app to the app stores for the changes to take effect. OTA updates do not suffice and a full release is required in the following cases:

  • The initial release of your app
  • A Studio Pro version upgrade that requires a new Native Template version
  • You fundamentally changed your app’s functionality (this is an Apple App Store limitation, and will require a re-release and re-review of your app by Apple — your app might be removed if you do not comply)
  • A new native module has been added (such as the Native Mobile AR module—for more information see Modules.
  • The app has been renamed
  • The app’s launcher icons have been changed
  • The splash screen has been changed

4 Build an App That Can Use CodePush OTA Updates

Apps built using the Mendix Native Mobile Builder have OTA updates with App Center’s CodePush disabled by default. To make OTA updates via App Center’s CodePush available to your app’s users, you must toggle the App Center OTA Support capability on.

Next you must build new binaries with this capability toggled on, and then release the apps to their respective app stores (only users with the new apps will be able to receive OTA updates). To do these things, follow these steps:

  1. Click App > Build Native Mobile App.
  2. Navigate to App Capabilities:

    Start Mendix Native Mobile Builder
  3. Toggle App Center CodePush OTA Support on:

    OTA capability enabled
  4. Click Save.

  5. Build an application for distribution and make a note of the version number used:

    Build release app page

To make the OTA update functionality available to your users, release the new binaries via the appropriate app stores. If you are testing the functionality you can now install the apps on your test devices.

5 Deploying an OTA Update

OTA updates let you correct mistakes in your published apps without issuing a new release. For example, imagine you issued a new release and later found a spelling mistake on your welcome screen:

Typo in welcome screen

Before OTA updates, you would have to make a new release and configure it in the app stores. But OTA updates make fixing such a mistake easy.

To release a new version OTA, follow these steps:

  1. Correct the message to Welcome to your new native mobile app. Thank you for using this app!
  2. Save your changes.
  3. Note the version and build number of the app build you want to update. This how to assumes an app version of 1.0.0 and a build number of 1.
  4. Click App > Build Native Mobile App.
  5. Under the Build app for distribution drop-down list, select Deploy OTA update via CodePush.
  6. Type in the target app version you wish to release the OTA update for. This version needs to match exactly with the app version used for building the app binaries in the previous step, or the one released on the app stores.
  7. Click Release an OTA update via CodePush.
  8. The Mendix Native Mobile Builder will compile your app and resources and release the OTA updates.
  9. On compilation, you will receive links to the CodePush OTA update administration pages for your Android and iOS apps:

    OTA build step success
    OTA App Center page
  10. Wait for the Native Mobile Builder to complete.

  11. Restart the app on your testing device. You should be greeted with the following message: Update available: An update is available that must be installed.

  12. Tap Confirm to update your app.

  13. The app should reload and greet you with the following dialog box: Information: Update is installed.

6 Preserving Your Model’s Integrity

Mendix native apps are offline first. This means you should be cautious when changing the following elements, and should avoid changing them if possible:

  • The navigation profile
  • An offline-first entity (for example, with entity name changes or new entity relationships)

Generally, you should avoid making destructive changes to offline-synced entities. In the rare cases this is unavoidable, releasing a new app version or doing OTA updates might put your end-users in an unrecoverable state.

6.1 Offline Apps and Data Loss

Data loss can occur when OTA updates or new releases coincide with apps being offline. For example, imagine you are hard at work optimizing the data store entity structure by consolidating entities to speed up sync operations. You release that morning. You push a new runtime by clicking the Publish button in Studio Pro, and then run the Native Mobile Builder to push a new update to the apps. All seems to work fine.

That same morning however, your engineers were hard at work gathering field data in a remote area. Later that afternoon the engineers return back to the city and attempt to synchronize their data using the app’s built-in synchronize button. Their synchronization fails. They do the only thing they can think of: restart the app. When the app starts they are greeted with the Update Available screen. They hit the continue button, get updated, and their data is lost or partially synchronized.

This issue is independent from OTA updates and specific to offline apps. Your offline app runs a snapshot of your runtime’s model locally. So as a Mendix developer, you have to think twice before doing major chages that might make the app’s state unrecoverable. In the example above the entity model was changed, and when the app attempted to synchronize it failed. This can create unrecoverable situations that will require a re-installation of the app, and can lead to data loss for unsynced data.

7 Transferring a CLI OTA-Compatible App to Native Mobile Builder

The transition from the CLI to Mendix Native Mobile Builder for OTA-supporting apps requires a few manual steps. These steps ensure you do not have to release your apps to the app stores again.

7.1 Gathering the Required Information

  1. Navigate to App Center.
  2. While logged in, find the Android and iOS apps used for building your app.
  3. Check the URLs and note down the application ID as seen in the URLs. For example, in https://appcenter.ms/users/user.name/apps/App-Android/distribute/code-push, the Android app’s ID is App-Android.
  4. If your app is built under an organization the URL might look like this: https://appcenter.ms/orgs/org-name/apps/App-Android/distribute/code-push. In this case, note the org-name as seen in the URL.

7.2 Moving Your App to Native Mobile Builder

  1. Launch the Mendix Native Mobile Builder for your app.
  2. If you have not yet completed the setup wizard, complete it now.
  3. Quit the tool completely.
  4. Navigate to your app’s directory and find the nativemobile folder (for example, C:\Users\user\Documents\Mendix\App\nativemobile).
  5. Enable Hidden items in Explorer to be able to see the .config file if it is not visible.
  6. Open the .config file and look for a key named App Center. If it is there, it might contain some app names already, like this example:

    "appcenter": {
        "iosAppName": "App-iOS",
        "androidAppName": "App-Android"
    },
    

    Optionally, if your apps are built in an App Center organization, add the organization name like this example:

    "appcenter": {
        "iosAppName": "App-iOS",
        "androidAppName": "App-Android"
        "organization": "your-organization-here"
    },
    

    If the file does not exist, add it manually. Either way, make sure to change the names to reflect the IDs of your App Center apps. Then make sure the newly changed file is still a valid JSON.

  7. Restart the Mendix Native Mobile Builder for your app. If the tool does not start, verify once more that the .config file is a valid JSON.

Try to push an OTA update for an unreleased version of your app, for example v0.1.0. If the OTA update shows up on your App Center app’s CodePush administration page, congratulations! You successfully transferred your app over to the Mendix Native Mobile Builder.

If the OTA release button remains disabled, verify that the app names added in the configuration are correct and make sure to add the organization property if your apps are under an organization. After you correct the mistakes, restart the Mendix Native Mobile Builder and try again.

8 Read More