What Are "Binary Compatible Changes"?

The documentation for Live Update states "The Live Update feature only works on binary compatible changes" but what, exactly, does that mean?

General Application Structure

A hybrid mobile application consists of three major components

• The web application
• The native application
• Native plugins

The web application is where most of your coding occurs. This consists of all of the JavaScript / TypeScript, SASS / CSS, and HTML that you write when you develop an Ionic application, along with any other static assets that your application references such as icons and images.

The native application is generated by Cordova. This application provides the interface between the web application and the native OS via a web view.

The native plugins are a bridge between the web application and specific APIs in the native OS.

Changes that are Binary Compatible

So long as only items that have been changed are contained within the "Web App" portion of the Application Architecture, the application is still "binary compatible" and the update can be delivered via the Ionic Appflow Live Update service.

This includes:

• JavaScript / TypeScript logic
• SASS / CSS styling
• HTML layout
• Assets (Images, Icons, static JSON files, etc)

Changes that are not Binary Compatible

If you change any items that are outside of the "Web App" portion of the Application Architecture, the application is no longer "binary compatible" and must be repackaged and resubmitted to the app stores.

For a typical application, this would be the result of either upgrading a plugin or adding a new plugin. It's important to note that even a minor or patch version upgrade to a given plugin can cause issues with binary compatibility. Thus, it is recommended to use explicit versioning (no ^ or ~ in your plugin versioning) or use a .npmrc file to manage your plugins.

Examples of changes that do require a new app store release:

Cordova

• Cordova plugin updates (even a minor or patch version update)
• Upgrading cordova-ios or cordova-android
• Modifying the config.xml file (which governs the native binary configuration)
• Modifying the application's icon or splash screen

Capacitor

• Upgrading the Capacitor version used by the application
• Upgrading any of the Capacitor or Cordova plugins used by the project
• Modifying the values in the capacitor.config.json file
• Modifying the application's icon or splash screen
• Any other modification that is made to the Xcode or Android Studio projects, including but not limited to changes to the Info.plist or AndroidManifest.xml files