sodcalculator

10 Tech How-To

Ship Safe JavaScript OTA Updates Between App Releases

Guide 10-43135 · Updated · Step by step

Shipping JavaScript over-the-air (OTA) lets you fix bugs and tweak features in a released app without waiting for a store review. This guide shows you how to set up a safe OTA pipeline that keeps your app stable, rollback-ready, and compliant with platform rules. You’ll learn the exact steps to bundle, sign, deliver, and verify updates, plus how to avoid the common pitfalls that break apps in production.

What You’ll Need

  • A JavaScript-based mobile app (React Native, Expo, Cordova, or similar) that supports OTA updates.
  • A code-signing certificate or key pair (e.g., a private key for signing update bundles).
  • A static file host or CDN (e.g., S3, Firebase Hosting, or any HTTPS server).
  • A backend endpoint (or serverless function) that serves the latest update manifest.
  • Version control (Git) and a CI/CD pipeline (GitHub Actions, GitLab CI, etc.).
  • Access to your app’s binary release process (to embed the public key and initial bundle).

Step-by-Step

  1. Plan your update strategy. Decide which parts of your app will be JS-only (safe to update OTA) and which require a native binary release (e.g., new native modules, SDK changes). Keep native changes out of OTA updates.
  2. Set up code signing. Generate a dedicated key pair for OTA updates. Keep the private key secure in your CI/CD secrets. Embed the public key in your app’s native code at build time. This ensures only your signed bundles can be installed.
  3. Create a versioning scheme. Use semantic versioning for both the native binary (e.g., 1.2.0) and the JS bundle (e.g., 1.2.0-ota.1). Track a monotonic build number for each OTA release. Your update manifest should include: app version, OTA version, bundle URL, hash, and required native version.
  4. Build the JS bundle. In your CI pipeline, run the bundler (e.g., Metro for React Native) to produce a minified JS bundle. Ensure you use the same bundling configuration as your release build (e.g., production mode, proper environment variables).
  5. Hash and sign the bundle. Compute a SHA-256 hash of the bundle file. Then sign the hash (or the bundle itself) with your private key using a standard algorithm like RSA-SHA256. Store the signature alongside the bundle.
  6. Upload the bundle and manifest. Upload the bundle file to your CDN with a unique filename (e.g., bundle-1.2.0-ota.1.jsbundle). Upload a manifest JSON file that points to this bundle, including the version, hash, signature, and minimum native version. Make sure the CDN serves with correct content-type and caching headers (e.g., no-cache for the manifest).
  7. Update the manifest endpoint. Your backend should serve the latest manifest for a given app version. For example, GET /updates?app_version=1.2.0 returns the newest OTA bundle for that native version. Ensure this endpoint is HTTPS and has proper authentication if needed (e.g., an API key).
  8. Implement the OTA client in your app. Add a module that checks for updates on app start (or on a timer). It should: fetch the manifest, compare the OTA version with the current one, verify the signature using the embedded public key, verify the hash, and then download and apply the bundle. Use a library like react-native-code-push or expo-updates if you’re using Expo, or write a custom updater for Cordova/other frameworks.
  9. Apply the update safely. Download the bundle to a temporary location. Verify the hash and signature again before replacing the current bundle. Use atomic file operations: write the new bundle to a temp file, then rename over the old one. Keep the previous bundle as a backup for rollback.
  10. Test the update flow in staging. Before pushing to production, test the entire flow in a staging environment: build a new bundle, upload it, and run the app in a simulator or device to confirm the update applies correctly. Also test rollback by intentionally sending a bad bundle and verifying the app falls back.
  11. Roll out gradually. Use a phased rollout: release the update to a small percentage of users (e.g., 5%), monitor crash reports and user feedback, then increase the percentage. Your manifest endpoint can support this by returning the update only to a subset of requests based on a user ID hash.
  12. Monitor and rollback. After the update is live, watch your crash reporting and analytics for anomalies. If something goes wrong, you can roll back by updating the manifest to point to the previous bundle (or by returning a no update response). Because the old bundle is still available, clients will revert.

Common Mistakes

  • Updating native code as part of the JS bundle (e.g., including native modules in the bundle) — this will break the app.
  • Not signing the bundle or using a weak hash — allows tampering.
  • Forgetting to set a minimum native version — an OTA update might require a newer native API that older binaries don’t have.
  • Overwriting the current bundle without keeping a backup — makes rollback impossible.
  • Ignoring cache headers on the manifest — clients may get stale updates.
  • Testing only on one device/OS version — OTA issues often appear only on older devices.

Tips

  • Always include a build number in your manifest and enforce that OTA updates are only applied if the native binary version matches the required one.
  • Use a separate signing key for OTA than for your app store builds — this limits blast radius if one is compromised.
  • Compress the bundle (e.g., gzip) to reduce download size, but remember to hash the uncompressed content.
  • Implement a “sticky” rollout: once a user receives an update, they should keep getting that same version even if the rollout percentage changes.
  • Add a timeout and retry logic for downloads to handle poor network conditions.
  • Keep a changelog of OTA updates for debugging.

Troubleshooting

Update not applying: Check that the manifest is being fetched (look at network logs). Verify the signature and hash match. Ensure the native version in the manifest matches the app’s binary version.

App crashes after update: Immediately roll back by pointing the manifest to the previous bundle. Then reproduce the crash in staging and check for native code changes that slipped in.

Users stuck on old version: Check CDN caching headers — the manifest might be cached. Also ensure the client is checking for updates at the right time (e.g., on app resume).

Signature verification fails: Confirm the public key embedded in the app matches the private key used to sign. Check that the signature algorithm is consistent (e.g., RSA-SHA256) and that you’re signing the correct data (hash vs. full bundle).

Rollout percentage not working: Ensure your manifest endpoint is stateless and uses a consistent user ID hash. If using a CDN, make sure the endpoint isn’t cached per user.

Download fails on slow networks: Implement resumable downloads or at least retry with exponential backoff. Also consider serving the bundle from a CDN with edge caching.

Frequently Asked Questions

Q: Is OTA update allowed on the App Store and Google Play? A: Yes, as long as the update does not change the app’s functionality in a way that violates store guidelines (e.g., introducing new features that need review). Apple and Google allow OTA for bug fixes and minor tweaks, but not for significant changes.

Q: Can I roll back an OTA update? A: Yes, by updating the manifest to point to a previous bundle or by returning a “no update” response. Clients that already have the bad bundle can be told to revert if you keep the previous bundle available.

Q: What’s the difference between OTA update and a native release? A: OTA updates only change the JavaScript (or other interpreted) code, while native releases change the compiled binary (e.g., Swift/Java/Kotlin). OTA updates are faster and cheaper but cannot change native APIs or SDKs.

Q: How do I ensure security? A: Use code signing with a strong algorithm, embed the public key in the app, and verify the hash and signature before applying any update. Also use HTTPS for all communication.

Q: What if my app needs a new native module? A: That requires a native release. You cannot ship native modules via OTA. Plan your release cycle accordingly.

Q: How often should I check for updates? A: On app start and on resume is typical. Avoid checking too frequently to save battery and bandwidth. You can also add a manual “check for updates” button.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →