Sitemap

Introduction

native-update is a Capacitor plugin that ships over-the-air JavaScript bundle updates, in-app store update prompts, and native review prompts to mobile apps without rebuilding or resubmitting them.

AI Integration Guide

Quick reference for AI development agents integrating native-update.

Changelog

Release history for the native-update plugin.

Plans, limits and update delivery

What happens on the hosted Native Update service when an account goes over its plan's app or monthly active user limit, how update delivery pauses after a 7-day grace period, and what your app's users see.

Installation

Install the native-update Capacitor plugin into a new or existing Capacitor 8 project. Covers npm install, iOS pod install, Android sync, and verification.

Quick Start

Ship your first OTA update with native-update in five minutes — install, configure, sync, and listen for download progress events.

Live Update — Overview

The Live Update API ships JavaScript bundles to installed Capacitor apps over the air. Read this first before diving into method, type, enum, event, or config reference pages.

Live Update — Methods

Complete reference for all 20 Live Update API methods in native-update. Each entry includes the TypeScript signature, parameters, return value, errors thrown, and a runnable example.

Live Update — Types

TypeScript type reference for the Live Update API of native-update. Field-by-field breakdown of BundleInfo, SyncOptions, SyncResult, DownloadOptions, LatestVersion, CheckForUpdateResult, DownloadUpdateOptions, ValidateOptions, ValidationResult, and DeleteOptions.

Live Update — Enums

Enum reference for the Live Update API of native-update — UpdateStrategy, UpdateMode, ChecksumAlgorithm, SyncStatus, BundleStatus, and the Live-Update-relevant subset of UpdateErrorCode.

Live Update — Events

Event reference for the Live Update API of native-update — downloadProgress and updateStateChanged. Includes payload shapes, when they fire, and a complete listener-and-cleanup pattern.

Live Update — Config

Field-by-field reference for LiveUpdateConfig — every option that controls Live Update behaviour at initialise time, with defaults, types, and recommended production values.

App Update — Overview

The App Update API of native-update wraps Google Play In-App Updates and the iOS App Store version check behind one cross-platform interface, letting your Capacitor app prompt users to update the binary from inside the app.

App Update — Methods

Reference for all 5 App Update API methods in native-update — getAppUpdateInfo, performImmediateUpdate, startFlexibleUpdate, completeFlexibleUpdate, openAppStore. Each entry includes signature, parameters, errors, and a runnable example.

App Update — Types

TypeScript type reference for the App Update API of native-update — AppUpdateInfo and OpenAppStoreOptions, with field-by-field tables and example payloads.

App Update — Events

Event reference for the App Update API of native-update — appUpdateStateChanged, appUpdateProgress, appUpdateAvailable, appUpdateReady, appUpdateFailed, appUpdateNotificationClicked, appUpdateInstallClicked. Includes payload shapes, fire conditions, and the InstallStatus enum.

App Update — Config

Field-by-field reference for AppUpdateConfig — every option that controls App Update behaviour at initialise time.

App Review — Overview

The App Review API of native-update wraps Google Play In-App Review and Apple SKStoreReviewController behind one cross-platform interface, with sensible default throttling so you never burn the user's once-per-quarter system limit.

App Review — Methods

Reference for the two App Review API methods in native-update — requestReview and canRequestReview. Includes signatures, return types (ReviewResult and CanRequestReviewResult), and a complete usage pattern.

App Review — Config

Field-by-field reference for AppReviewConfig — every option that controls App Review throttling, custom triggers, debug mode, and web fallback URL.

Background Update — Overview

The Background Update API of native-update runs battery-aware and network-aware silent update checks while your Capacitor app is closed, with optional native notifications when an update is found or installed.

Background Update — Methods

Reference for all 8 Background Update API methods in native-update — enable/disable, status, schedule, trigger, plus notification preferences and permissions.

Background Update — Config

Field-by-field reference for BackgroundUpdateConfig and NotificationPreferences — every option that controls scheduled silent updates and the notifications they post.

Background Update — Events

Event reference for the Background Update API of native-update — backgroundUpdateProgress and backgroundUpdateNotification, with payload shapes and usage patterns.

Security — Overview

Security primitives in native-update — getSecurityInfo, SecurityConfig, certificate pinning, and the full UpdateErrorCode catalogue. Covers HTTPS enforcement, bundle signing, and input validation.

Security — Error Codes

Complete UpdateErrorCode catalogue for native-update — every code that can be thrown across Live Update, App Update, App Review, Background Update, and Security flows, grouped by domain with recommended remediation.

Security — Certificate Pinning

Reference for the CertificatePinning and CertificatePin types in native-update plus a working OpenSSL recipe to extract SHA-256 pins from your update server's TLS certificate.

Core — Lifecycle

Reference for the core lifecycle methods of native-update — initialize, isInitialized, configure, reset, cleanup. Covers what each does, when to call it, and the ordering rules between them.

Core — Config (PluginInitConfig)

Field-by-field reference for PluginInitConfig — the single configuration object passed to NativeUpdate.initialize() at app boot. Covers every flag across server, security, live-update, app-update, and review settings.

CLI — Overview

The native-update CLI ships with the npm package and provides project bootstrap, key-pair generation, bundle creation, signing, verification, a local dev server, deployment monitoring, and backend scaffolds. Read this first.

init — Scaffold native-update config

native-update init scaffolds a native-update.config.js file by prompting for app ID, server URL, default channel, and auto-update. Optional --example flag writes a working integration snippet.

keys generate — Generate signing key pair

native-update keys generate produces an RSA-2048 or RSA-4096 key pair for RSA-SHA256 bundle signing. The private key is chmod 600; the public key goes into your app's native-update config.

bundle create — Package a web build into an OTA bundle

native-update bundle create packages your built web directory (./dist, ./www, etc.) into a versioned ZIP plus a JSON metadata file with SHA-256 checksum, channel, and arbitrary release notes.

bundle sign — Sign an OTA bundle with your private key

native-update bundle sign produces an RSA-SHA256 signature of an OTA bundle and writes a sidecar .sig JSON file. The signed bundle and signature both upload to your backend; the device-side SDK verifies before applying.

bundle verify — Verify a signed bundle with your public key

native-update bundle verify confirms an OTA bundle's RSA-SHA256 signature against your public key. Use it as a CI safety net before uploading — exits 1 if the signature is invalid.

server start — Run a local dev update server

native-update server start runs a tiny Express server that serves bundles from a local directory. Designed for testing the device-side sync flow against your own machine before deploying a real backend.

monitor — Watch live deployment stats

native-update monitor polls a backend's /api/stats endpoint every 5 seconds and renders a terminal dashboard with current version, channel, download totals, and recent activity. Useful for tracking a rollout in real time.

backend create — Scaffold an Express, Firebase, or Vercel backend

native-update backend create generates a starter Express / Firebase Functions / Vercel serverless backend with the HTTP contract the SDK expects. The output is a SCAFFOLD with TODO[SCAFFOLD-IMPLEMENT-BEFORE-DEPLOY] markers — not production-ready.

CLI — deploy & remote commands

Deploy a bundle from CI or your terminal with an access token — deploy, apps list, builds list/promote/rollout/status/delete, jobs status, and token info.

Public API — Overview

Manage your apps, builds, and releases over HTTP with a personal access token. Deploy from CI, a script, or an AI agent — the same things the dashboard does.

Public API — Endpoints

Every route on the public management API, with curl examples — token introspection, app CRUD, API keys, signing keys, keystore backup, builds, upload, promote, rollout, delete, and job status.

Public API — Queued jobs

Uploads return 202 with a job id. How the job lifecycle works, how to poll it, and what happens when processing fails.

Backend — Overview

native-update needs a backend that serves bundle metadata and the bundle ZIP. Use the hosted Native Update service, or your own server that implements the documented contract. This page helps you pick.

Node + Express Minimal Backend

The example-apps/node-express reference is the smallest backend that implements the native-update HTTP contract. ~160 lines of Express + multer, JSON-file metadata, no auth, no signing — meant to be read in one sitting and adapted.

API Contract

The exact HTTP contract every native-update backend must satisfy. Six endpoints, full request and response shapes, authentication, status codes, error envelopes, and the field semantics the SDK enforces.

Android Platform Guide

Everything you need to wire native-update into an Android Capacitor app — required permissions, manifest additions for background updates, WorkManager constraints, Play Core integration, ProGuard rules, signing setup, and Play Console-compliance pitfalls.

iOS Platform Guide

Everything you need to wire native-update into an iOS Capacitor app — Info.plist keys, BGTaskScheduler permitted identifiers, background mode capabilities, ATS exceptions, SKStoreReviewController throttling, keychain usage, App Store Review guideline compliance, privacy manifest entries.

Web Platform Guide

What native-update can and cannot do when running in a browser, the service-worker-based update fallback, and when the web target is actually useful (browser dev fallback for Capacitor, PWA-style update prompts, automated tests).

Your first OTA update — end to end

A step-by-step walkthrough from a fresh Capacitor project to a verified OTA update applied on a real device. Covers install, signing-key generation, bundle creation, signing, upload, the device-side sync, and verifying the new bundle ran.

Manage release channels

How to use channels (production, staging, beta, canary) to route different bundle versions to different cohorts of devices without changing your app's code.

Restrict an API key to your app (ship the key safely)

Lock a native-update API key to specific web origins, Android apps (package + signing certificate), and iOS bundle ids so it can be shipped inside your app without a proxy server of your own. Covers the dashboard flow, getting signing-cert fingerprints with keytool, the plugin version requirement, and what the restrictions do and do not protect.

Rotate signing keys without breaking active bundles

How to introduce a new bundle-signing keypair while keeping bundles signed by the old key verifiable on existing devices. Covers the multi-key transition window, the dashboard's rotation flow, and the emergency revoke path for a leaked private key.

Roll back a bad bundle

How to revert devices to a previous bundle after a bad release. Covers the automatic crash-rollback, the server-side rollout-throttle path, and the explicit per-device rollback API.

Migrate from CodePush

A practical migration guide from Microsoft CodePush (App Center) to native-update. Maps CodePush concepts to native-update equivalents, covers running both side-by-side during the transition, and lists the gotchas that bite real migrations.

Integrate with CI/CD (GitHub Actions)

A production-grade GitHub Actions workflow that builds, bundles, signs, verifies, and uploads an OTA release on every push to main. Covers secret management, key handling, fan-out across channels, and the manual-approval pattern for production rollouts.

Test bundles in development

Three local-test loops for OTA bundles — the bundle-verify smoke test, the native-update server start dev server, and the full-device LAN test. Covers what each one catches, what it doesn't, and when to use which.

Troubleshoot updates

Diagnose the most common native-update failures — updates not detected, downloads failing, installs rejected, crash rollbacks, and dashboard mismatches — with the real SDK methods.

How OTA updates work

A conceptual walkthrough of the over-the-air update lifecycle in native-update, from the moment you push a release to the moment the user sees the new bundle. Covers bundle creation, delivery, sync, verification, atomic apply, and rollback.

Bundle integrity and signing

A conceptual explanation of the two-layer integrity model native-update uses for OTA bundles — SHA-256 for transit integrity and RSA-SHA256 signing for source authentication. Covers what each layer protects against, the trust chain, and the threats the model does not address.

Update strategies compared

A side-by-side comparison of the four update strategies native-update offers — immediate, on-app-start, on-app-resume, and background — covering when each fires, what the user sees, the trade-offs, and which to default to.

Architecture

A diagrammed walkthrough of how the native-update system is layered — the CLI, the backend, the SDK runtime, the platform-native modules, and the storage tier. Includes mermaid diagrams of the build-time, deploy-time, and runtime data flows.

Security model

The threat model native-update is designed to defend against, the three layers of defense it implements (transport, content, runtime), what's in scope and what isn't, and the operational practices the model assumes you follow.

Error handling philosophy

Why native-update fails open on analytics writes, fails closed on signature verification, returns typed error codes, and keeps the app running through OTA failures. Explains the design principles behind the SDK's error surface.

About Native Update

Native Update is a SaaS product for Capacitor apps, built and maintained by the Native Update team. How to reach us, and how the plugin is licensed.

Native Update releases

Release notes for each published version of native-update, newest first.

Feed

Native Update release notes, newest first, with RSS and Atom links for your feed-reader app.

Native Update 4.1.1

Native Update 4.1.1 release notes: refreshed Capacitor 8, CLI, build, lint and test dependencies, with no change to the public plugin API.

• Release

Native Update 4.1.0

Native Update 4.1.0 release notes: a locally signed bundle can now be uploaded with its signature, and deploy picks up the sibling .sig file.

• Release

Native Update 4.0.0

Native Update 4.0.0 release notes: real delta delivery, Capacitor 8 and current toolchain requirements, RSA-SHA256 signatures and locked configuration.

• Release

Native Update 3.4.0

Native Update 3.4.0 release notes: the full app lifecycle on the Public Management API, the all_apps token scope and new CLI commands.

• Release