Codemagic Enhances Ionic Capacitor Support with Seamless OTA Updates for Web Layer

This article is written by Marijan Kozic

Codemagic Patch introduces live updates for HTML, CSS, and JavaScript specifically designed for Capacitor, Ionic, and Cordova-on-Capacitor applications, eliminating the need for new store binaries.

For instance, if a checkout button malfunctions on certain Android 15 devices and the resolution requires just four lines of TypeScript code residing in the web layer of a Capacitor app, the traditional process mandates navigating through binary creation, store submission, review periods, and gradual user updates—some of whom may never update. Over-the-air (OTA) updates negate this cumbersome process. Starting today, Codemagic Patch offers a solution tailored for Capacitor applications through our self-hosted tool.

Patch v0.6.0 includes two new packages: @codemagic/capacitor-patch for app integration and @codemagic/capacitor-patch-cli for command-line management of Capacitor releases. Both utilize the same server infrastructure, dashboard, and delivery mechanisms as our React Native SDK.

Transitioning from Appflow’s Live Updates

Ionic has announced the impending discontinuation of all Appflow features and services by December 31, 2027, providing a little over a year for migration. While support for Appflow will continue until then, over-reliance on this tool could lead to issues such as failed builds or errors in live updates, with users potentially facing blank screens.

A year may seem ample time, but migration for OTA services entails significant planning and deployment timelines. New SDK installations must occur within a native binary, requiring a review process and ensuring user installation across devices. In practice, the build for migration should be completed well in advance of the approaching deadline.

Having established and managed Capacitor apps on Codemagic for years, we are recognized by Ionic as an alternative for Appflow native builds. Additionally, Capacitor teams have accessed OTA updates through our CodePush service via the community cap-codepush plugin. Patch supersedes this setup with our native SDK that is carefully designed, vetted, and supported, allowing for seamless integration of native builds and live updates from a single provider.

Features of Patch

Patch provides a self-hosted server, an integrated SDK, a CLI for web build publication, and a comprehensive dashboard for tracking performance.

• Web-layer adjustments are deployed to devices already configured with the SDK, with checks occurring upon app launch and when returning to the foreground.
• Updates are downloaded as diffs of changes, with a backup to the full bundle in case of failure.
• Malfunctioning releases are automatically rolled back if the app does not report success.
• Control over update activation is granted, with options for mandating updates.
• Support for release signing is provided, with the server capable of rejecting unsigned submissions.
• Separate staging and production environments allow randomized rollout to a percentage of devices, streamlining promotion without necessitating rebuilds.
• The dashboard offers insights into release adoption, failure rates, and download sizes.

Simplifying OTA with Capacitor

Implementing OTA updates in React Native can be complex, involving interactions with bundlers (Metro or Expo), Hermes bytecode, and the New Architecture, as well as requiring integration with both the bundle construction and runtime loading processes.

In contrast, a Capacitor app operates as a native shell directing a WebView towards a directory of web assets, with @capacitor/core providing the necessary APIs to modify the folder direction (setServerBasePath, getServerBasePath, and persistServerBasePath). An OTA update consists merely of downloading a new folder, validating it, and directing Capacitor to it upon the subsequent launch. The absence of bundlers and bytecode formats significantly simplifies the process, minimizing potential update-related disruptions.

This simplicity is reflected in the CLI, where cmpatch-capacitor does not execute your build or require the execution of npx cap sync. Development can occur as usual (ionic build, ng build, vite build), with various front-end frameworks being supported for the release output.

Fewer components equate to fewer risks for update failures, a crucial characteristic for an update mechanism.

Native Versioning for Compatibility

It’s imperative for every team to understand a singular guideline prior to deploying their first OTA release using Capacitor: the web bundle interacts with native code through Capacitor plugins, personal native classes, and configuration settings. A bundle designed for a particular native version may not operate correctly with another version due to discrepancies between native and web code.

The Capacitor CLI does not utilize algorithms to analyze your native project, instead, every release targets a specific native app version (CFBundleShortVersionString for iOS, versionName for Android) and updates are only dispatched to that version. This means no ranges or wildcards are permitted. In practical terms:

• Increment the native version whenever there are any alterations that affect native functionality, such as adding, removing, or upgrading a plugin, modifying native code, or altering native configuration.
• When a single web bundle must be applied across multiple binary versions, individual releases should be executed for each version.
• Avoid deploying two dissimilar native builds under the same version number. If they differ in aspects that your web code relies on, no OTA tool will differentiate them.

By respecting these versioning practices, teams will experience fewer complications. For those who may not currently follow strict version control, OTA implementation will prompt better practices that ultimately benefit the development workflow. The newly included binary version filter on the Patch dashboard’s deployment and metrics pages simplifies the monitoring of performance across versions.

In summary, any modifications will fall into one of two categories:

Understanding the Benefits and Limitations of OTA

WhileOTA services have advantages, it’s essential to clarify the specific benefits they provide.

The primary advantage is speed—fixes to the web layer significantly reduce the lag associated with review processes, allowing users to receive updates almost instantly. For consumer applications, this speed can avert negative reviews. In B2B or internal applications, it can mean the difference between extended issues and quick resolutions.

Moreover, with OTA updates, fewer versions need to be supported concurrently. Store-exclusive updates maintain a myriad of outdated versions, each generating potential bug reports. OTA significantly reduces this incidence, ensuring devices using the same binary converge on a common web bundle.

Additionally, the release cycles can progress independently. Native builds can adhere to longer timelines dictated by compliance, whether it’s monthly or quarterly, while the web layer can be updated whenever the development team is ready. With features like staging, gradual rollouts, and promotion, companies gain a well-controlled process from development to full deployment.

However, OTA cannot facilitate the distribution of changes involving native code, as application stores strictly delineate this boundary.

Apple’s Developer Program License Agreement, section 3.3.1(B) forbids apps from downloading executable code but allows interpreted code, such as JavaScript run within a Capacitor WebView. Conditions apply, however—downloaded code cannot alter the app’s core functions or subvert security protocols like signing and sandboxing. Furthermore, it must not transform the app into a marketplace for other applications.

Conversely, Google Play enforces more stringent guidelines. Their Device and Network Abuse policy explicitly prohibits applications from updating themselves outside of Google Play or downloading executable code like dex, JAR, or .so files. An exception is made for interpreter-based code operating within a virtual machine with restricted access to Android APIs, exemplified by JavaScript in a WebView. This code must still comply with existing Play policies.

Consequently, both stores effectively relay a similar conclusion: bug fixes, copy adjustments, UI enhancements, and incremental improvements can be distributed over the air. However, using OTA to alter the app’s original reviewed functionality poses risks to developer accounts. Ensuring signed releases complies with Apple’s conditions, while maintaining diligent native version control keeps changes appropriately confined to reviewed binaries.

Implementation Options for Patch: Self-hosting or Codemagic Hosting

Unlike several OTA services, Patch provides flexibility in deployment options—it can be self-hosted or managed by Codemagic.

Self-Hosted Deployment

The Patch server, release worker, and dashboard can be operated on your infrastructure through a streamlined Docker Compose deployment involving Caddy for TLS, the Patch server, PostgreSQL, and S3-compatible object storage, with optional Cloudflare or CloudFront for CDN support. All data, including bundles, metrics, and release history, remains localized. The Capacitor SDK communicates seamlessly with this standard Patch server. Setup requires a one-time configuration with the self-hosting guide, and cmpatch-capacitor manages Capacitor-specific functionalities efficiently thereafter.

The SDKs and CLIs are distributed under the Apache 2.0 license. The server adheres to the Codemagic Server License, which is free for up to 1,000,000 monthly active devices, transitioning to Apache 2.0 two years post-release. The only restriction placed on users is against reselling Patch as a competing OTA service.

To explore its capabilities without full deployment, a local evaluation stack can be run. This setup operates the live server, database, storage, and dashboard on your machine via Docker, allowing connection to the Capacitor CLI:

git clone https://github.com/codemagic-ci-cd/codemagic-patch.git
cd codemagic-patch
./scripts/local-eval/up.sh

cmpatch-capacitor config set --server-url http://localhost:3000
cmpatch-capacitor login

The local server offers easy one-click login, eliminating the need for account creation.

Self-hosting aligns particularly well with organizations that have stringent data residency policies, operate within regulated or isolated environments, or prefer to maintain complete control over their infrastructure.

Codemagic-Hosted Option

While self-hosting offers several advantages, managing infrastructure can be resource-intensive. For teams seeking to prioritize their application development, opting for a hosted version of Patch can prove beneficial.

Codemagic’s hosted Patch operates on our infrastructure, granting the first 100,000 monthly active users free access, with no constraints on updates or bandwidth. For teams exceeding this threshold, details about additional pricing tiers can be found on our pricing page. Furthermore, enterprise plans are available, offering dedicated servers and region-specific options to streamline update infrastructure and data management.

Interested parties are encouraged to reach out via email at sales@codemagic.io for additional information.

Beginning Your Journey with Patch

The Patch documentation contains comprehensive step-by-step instructions for setting up your environment and successfully deploying your first OTA release.

1. Determine your hosting choice for Patch. Install the self-hosting option using the self-hosting guide or engage our team for a hosted service setup. Trialing the local stack mentioned earlier is also a viable first step.

2. Install the CLI and establish distinct Patch applications for each platform. Ensure that each application has its own Staging and Production deployment keys. Avoid sharing between iOS and Android to prevent overwriting.

npm install -g @codemagic/capacitor-patch-cli

cmpatch-capacitor config set --server-url https://YOUR_PATCH_SERVER
cmpatch-capacitor login # opens the browser

cmpatch-capacitor app create --name MyApp-iOS
cmpatch-capacitor app create --name MyApp-Android
cmpatch-capacitor deployment list --app MyApp-iOS # deployment IDs and keys
cmpatch-capacitor deployment list --app MyApp-Android

3. Integrate the SDK into your Capacitor project. Compatibility extends to the two latest major Capacitor versions (currently 7 and 8) and requires a minimum SDK version of 24 or higher for Android.

npm install @codemagic/capacitor-patch
npx cap sync

Configuration parameters should be added within capacitor.config.ts, with a distinct block for each platform. The API URL and download base URL should be sourced from your Patch server, accessible via the self-host installer or provided for those opting for hosted Patch.

// capacitor.config.ts (excerpt)
plugins: {
  CodemagicPatch: {
    ios: {
      deploymentKey: 'YOUR_IOS_DEPLOYMENT_KEY',
      apiUrl: 'https://YOUR_PATCH_API_URL',
      downloadBaseUrl: 'https://YOUR_PATCH_DOWNLOAD_BASE_URL',
    },
    android: {
      deploymentKey: 'YOUR_ANDROID_DEPLOYMENT_KEY',
      apiUrl: 'https://YOUR_PATCH_API_URL',
      downloadBaseUrl: 'https://YOUR_PATCH_DOWNLOAD_BASE_URL',
    },
  },
},

Invoke start() once the app’s user interface has loaded its first screen:

import { CheckFrequency, start } from '@codemagic/capacitor-patch';

// Initiates checks on app launch and every return to the foreground.
// Calling after the first render confirms the bundle as healthy.
start({ checkFrequency: CheckFrequency.ON_APP_RESUME });

Placement of this call is critical; invoking start() informs the SDK that the running bundle is stable—execute it post-render to ensure that any loading issues during startup will trigger a rollback. Additionally, it may be beneficial to configure all values as native resources (in Info.plist or strings.xml) if CI utilizes environment-specific configurations. Incorporating npx codemagic-patch-check-config within your native build process can help identify shared deployment keys before they are published. This check processes JSON, so point to the synced copy post-execution of npx cap sync: npx codemagic-patch-check-config android/app/src/main/assets/capacitor.config.json. The Patch documentation contains detailed guidance on native Capacitor setup, update checks, installation modes, and the available APIs. The SDK reference elaborates on all the features supported.

4. Publish a release to Staging using the CLI. Construct web assets through your established process, then publish the resulting folder on a per-platform basis. Remember that --target-binary-version must correspond to the version number of the native release (CFBundleShortVersionString on iOS, versionName on Android). The www directory mentioned should align with the webDir in your capacitor.config.ts.

npm run build

cmpatch-capacitor release create --bundle-path www 
  --app MyApp-iOS --deployment Staging 
  --target-binary-version 1.4.0

cmpatch-capacitor release create --bundle-path www 
  --app MyApp-Android --deployment Staging 
  --target-binary-version 1.4.0

These commands will publish updates for individual platforms. Testing the Staging release on devices before submitting to the stores requires the SDK integrated in that same version.

5. Release the native update and subsequently publish to Production via CI. The SDK must be included in the installed app for devices to receive updates, necessitating an initial binary following standard store release protocols. Continue with building, signing, and distributing via Codemagic as per usual. The CI/CD for Ionic apps documentation outlines the process of establishing repository connections and initial workflows, while the Ionic Capacitor build guide elaborates on code signing, versioning, and publishing procedures for both platforms.

Post-native release, future Production deployments fall under CI automation. Generate a token using cmpatch-capacitor token create, store it alongside the server URL and deployment IDs derived from deployment list, facilitating pipeline updates. The initial release guide includes this entire workflow, covering both promotion and staggered rollouts.

Migrating from Appflow Live Updates

Many concepts from Appflow translate directly to Patch, with Appflow channels equivalent to Patch deployments and available Staging and Production options from the outset. Notably, there are differences worth understanding prior to migration:

• The SDK transition necessitates one native release. It is impossible to send a new OTA SDK through an existing one. Plan for a native release to switch from Appflow Live Updates to @codemagic/capacitor-patch, ensuring ample time for it to propagate to users before the December 2027 cutoff.
• Runtime channel switching is unavailable. Appflow’s getConfig() and setConfig() functionalities allow for in-app switching between channels. The Patch SDK does not support this; a different strategy such as separate beta builds pointing to a Beta deployment will be necessary.
• Release history isn’t imported. Existing Appflow channels, builds, or deployment histories will not carry over to Patch; the first Patch release initiates a fresh record.
• Distinct keys for each platform. In contrast to Appflow, which utilized a singular channel name across platforms, Patch requires separate deployment keys for iOS and Android.
• Exact matching of binary versions is critical. Ensure a clear native versioning strategy prior to migration if your Appflow configuration employed more flexible version matching.

While these elements shouldn’t create major obstacles, the initial rule regarding SDK transition will influence timelines, as elaborated in the migration guide for Appflow.

Users currently leveraging our CodePush service with cap-codepush will notice no immediate changes. Transitioning to Patch follows a similar process: completing a single native release updated with the new SDK and publishing via cmpatch-capacitor rather than code-push.

Identifying Situations Where Patch May Not Be Suitable

We prefer customers to select the most appropriate tool for their needs. Below are scenarios where Patch may not provide sufficient assistance:

If most updates are native. Changes like plugin upgrades, alterations to Capacitor versions, and native feature adjustments necessitate a reviewed binary regardless of which OTA service is utilized. For teams focusing heavily on these areas, creating a fast and reliable structure for native builds and releases becomes paramount, something Codemagic can cater to as well.

If your beta program relies on runtime channel switching. Transitioning may necessitate reevaluation; Patch currently lacks this functionality. Planning for separate beta builds will become necessary, so care should be taken in the leadup to migration.

If your native versioning lacks clarity. Stricter adherence to exact version targeting may feel cumbersome. We endorse strict procedures to prevent ambiguity regarding compatibility, but it requires some managerial adjustment.

If you are content with Appflow. Immediate migration isn’t necessary, yet it’s pivotal to prepare well before the December 2027 deadline, as a native release will be central to this transition.

Frequently Asked Questions

Are Live Updates Natively Supported in Capacitor?

No, Capacitor does not include an updater as part of its core functionalities. Codemagic Patch includes a separate SDK (@codemagic/capacitor-patch) paired with a CLI (cmpatch-capacitor).

Can Patch Replace Appflow Live Updates, and By What Timeline?

Yes, Patch can serve as a replacement for Appflow Live Updates concerning web-layer deployments. Given the December 31, 2027, cessation of Appflow services, the Patch SDK must be integrated within a native binary well ahead of this date, as devices still connected to the prior SDK will continue to attempt communication with Appflow.

Is Self-Hosting Possible for Patch, and Who Is It Intended For?

Yes, self-hosting is available free of charge for up to 1,000,000 monthly active devices. Companies exceeding this limit must negotiate hosting arrangements with us; no upfront signup is necessary.

Which Changes Can Be Updated via OTA, and What Requires Store Releases?

HTML, CSS, and JavaScript in the web layer qualify for OTA updates, targeting specific native versions. Any modifications involving plugins, native code, or configuration alterations will necessitate a standard store release with an updated version.

Conclusion

Patching Capacitor with our new SDK presents a streamlined approach to OTA support. The latest tools bring forth binary differences, automatic rollback for crash loops, signed releases, and controlled rollout options—all reducing the chances of issues leading to blank screens. Codemagic offers the flexibility of self-hosting Patch or opting for hosted solutions, free for up to 1 million active users. Enterprise plans provide options for dedicated or geolocated servers, alongside expert guidance on compliance requirements.

The current release marks the inception of the Capacitor SDK and CLI (v0.1.0), with detailed changelogs available in the Patch release notes. We value your feedback on its functionality.

If you anticipate the shutdown of Appflow in your operational timeline, initiate steps towards migration early. Experiment with the local evaluation stack this week and incorporate the SDK into your next native release.