Appearance
Native compatibility
OTA bundles can change JavaScript and assets. A change to a native module, React Native, Hermes, native configuration or the OTA SDK needs a new native build. Runtime protection prevents accidentally sending JavaScript built against different native inputs to an existing store version.
Prepare a store build
- Download the current helper from Connect your app, update the pinned SDK, complete native wiring and install native dependencies, including iOS pods.
- Set the intended version/build in your native project.
- From the project root run:
sh
node ota.cjs prepare-native ios --target-version 1.2.3 --build-number 42sh
node ota.cjs prepare-native android --target-version 1.2.3 --build-number 42The command hashes native sources and linked dependencies, embeds CodePushRuntimeVersion in native configuration, and registers the exact version/build. This includes the app's and dependencies' codegenConfig, their TurboModule/Fabric specifications and relative specification imports. These JavaScript/TypeScript files generate native interfaces, so a changed method type requires a new native build. Run preparation after dependency installation and before your release build. A changed native input requires preparation again and a new build number. For a custom iOS layout, add --native-config ios/YourApp/Info.plist.
Build, test and distribute that native version through your store process. Then open Native compatibility in the dashboard and enable protection. Registration is a source record, not proof that a binary was built, approved or installed. Enabling protection requires an explicit acknowledgement that you have tested and distributed the protected build.
Publish normally
sh
node ota.cjs publish ios --deployment Staging
node ota.cjs publish android --deployment Staging --target-version 1.2.3Omitting a version still performs automatic public store lookup. An explicit version overrides that lookup only. Neither option bypasses the runtime check. The publisher recomputes the fingerprint and requires a matching registered target version. It signs an immutable runtime manifest with the bundle. The server checks publication, promotion, edits and rollback; the new native SDK checks downloaded and installed bundles independently.
Use the checkout and locked dependencies for the native store build you are targeting. Ordinary application JavaScript/assets and marketing/build version labels do not change the fingerprint. Native dependency sources, native lockfiles, codegen inputs and native project configuration do. A native mismatch stops publication. File diagnostics explain the available evidence before you decide whether to restore the original inputs or prepare a future native build. Do not edit the registered hash to bypass the check.
Upgrading to codegen-aware fingerprints
Runtime fingerprint schema 2 adds codegen inputs that older helpers omitted. A previously prepared schema-1 runtime will not match the new helper. Run prepare-native again, build a new native binary, distribute it through the store testing track and install it before publishing updates for that runtime. Merely registering a new hash does not change existing installed binaries. An explicit --target-version does not bypass this requirement.
Existing installed runtimes and releases remain on the server; upgrading the helper does not force old clients to install an incompatible update or remove their healthy bundle. Keep the prior native source/build records for recovery. Do not disable compatibility protection or copy the old runtime hash to work around the migration.
Catching drift before a store upload
Use the current ota.cjs helper. After dependency installation, patches and CocoaPods have finished, run:
sh
node ota.cjs prepare-native ios --target-version 1.4.6 --build-number 4
node ota.cjs verify-native ios
# Android equivalent:
node ota.cjs prepare-native android --target-version 1.4.6 --build-number 12
node ota.cjs verify-native androidPreparation installs a tracked, removable build guard. Existing integrations can add it with node ota.cjs install-build-guard ios or android. Installation does not prepare a new runtime, publish an update or upload anything to a store.
The iOS guard runs from the standard React Native .xcode.env application bundle phase for non-Debug configurations. It checks the source fingerprint, the actual root runtime setting, the prepared version/build and Xcode's selected plist. Android's guard attaches to each non-debuggable application's pre-build task and checks its resolved version/build. These checks run locally without login or network access. A mismatch, deleted configuration or missing helper stops the build; recovery records cannot authorize a future store build. Keep the standard React Native environment-loading phase in custom Xcode projects, and run verify-native explicitly in custom archive pipelines as well.
The exact managed guard text is excluded from the native fingerprint because it only validates builds. Altered guard text and other native configuration remain inputs. This also preserves the distinction between a missing and an empty Xcode environment file. The iOS guard resolves Node using the project's .xcode.env.local override in a subshell before checking; keep environment configuration idempotent, as React Native loads that override again afterward. Android preparation uses the selected --native-config module. Uninstall restores the original environment/build script through its installation receipt.
Xcode may renumber a build during export. That does not alter native compatibility by itself. Save the exported IPA and archive together with the prepared source/dependency snapshot; do not treat a build number as a substitute for the runtime check.
Recovering an already distributed iOS build
An administrator can explicitly recover an existing signed IPA that retained an older runtime identifier. This is an audited exception for a reviewed source baseline, not automatic detection that two native builds are equivalent. First establish the actual store build and its original source/dependencies, review the difference, and test the candidate against that native build. If the evidence is insufficient, do not approve a recovery simply because publication failed.
On macOS, run from the intended project:
sh
node ota.cjs recover-native ios \
--ipa /path/to/original-export.ipa \
--bundle-id com.example.app \
--target-version 1.4.5 --build-number 3 \
--expected-source-fingerprint REVIEWED_64_CHARACTER_SHA256 \
--reason "Describe the archive, original baseline and compatibility review"Use the independently reviewed source fingerprint, not a guessed value or a freshly accepted mismatch. The helper verifies the IPA's code signature and its exact app identifier, version/build, OTA server, Production channel and signing key. It hashes the complete IPA, requires the current source to match the reviewed fingerprint, and signs an attestation with this app's publishing key. The server requires an app administrator, rejects scoped publishing credentials for recovery, and stores an immutable, audited record. It will not overwrite an existing build or invent an unregistered installed runtime. IPA contents and private keys are not uploaded.
Publishing must explicitly select that record:
sh
node ota.cjs publish ios --deployment Staging --target-version 1.4.5 --recovery-build 3Omitting --recovery-build retains the normal strict match. A changed native source, version or variant fails; the helper also rechecks inputs after bundling. The downloaded package still carries the original signed runtime and exact target version, and the installed SDK's signature, runtime and rollback checks remain unchanged. The dashboard identifies recovered builds and shows their approved source fingerprint and review reason.
A recovery build number selects evidence; it is not a new device-routing selector. Existing SDKs route by app version and embedded runtime. Other installations sharing both values can receive the same update. Validate the affected native builds and use approved test installations for Staging before considering Production. Never claim a recovery is restricted to a store build number that the installed SDK does not transmit.
Browsing registered builds
Open Native compatibility in the dashboard. The dialog shows 20 builds at a time, newest registrations first, with Load older builds for the rest. Search by version, build number, variant or any part of a runtime fingerprint; search includes older records beyond the first page. The registry supports up to 1,000 builds per app.
The list scrolls within the dialog while its title, close button and paging controls stay accessible. On narrow screens it fills the screen. Expand a runtime identifier to inspect it, or choose Copy runtime to copy the full fingerprint. The preparation command is under Prepare a native store build. These controls do not change registrations or bypass the distribution confirmation required to enable protection.
Variants and limits
For different native flavors or build environments, pass the same explicit --runtime-variant enterprise to preparation and publication. Commit the public project configuration. External build inputs, toolchains and environment-dependent flags must be reproducible and represented by distinct variants; this is source compatibility protection, not binary attestation. The CLI rejects native input symlinks and ambiguous configuration paths rather than silently skipping them. Codegen source directories and relative imports must remain inside their declaring package. Individual native binary inputs are streamed with a 512 MiB limit; normalized native text and codegen source files have a 20 MiB limit. Exceeding a limit stops preparation/publication explicitly.
Staging and Production channel/key fields are excluded from the fingerprint so a tested bundle can be promoted unchanged. The signed target version cannot be edited during promotion: publish separately for a different native version.
Existing installed apps
The current helper uses fingerprint schema 2. It includes application and linked-dependency Codegen configuration and native specification sources, including referenced types. Changes to a TurboModule or native component specification require a new native build even though the specification is written in JavaScript or TypeScript. Ordinary app UI JavaScript remains eligible for OTA.
When upgrading from the earlier helper or SDK, prepare, rebuild and distribute a new native store build before publishing for its new runtime. Registering a new fingerprint alone cannot change binaries already installed by users. Older runtime records remain valid for those binaries; the new helper does not fall back to a less complete fingerprint to bypass a mismatch.
Existing binaries cannot acquire this native check through OTA alone. A new store build is required. Protected binaries skip legacy bundles; legacy binaries skip runtime-protected bundles and keep their last healthy version. Enabling protection requires protected packages for future publication, but you can still pause legacy releases. Rollback to an older compatible protected release stays available.
Uninstall removes the embedded runtime field along with the rest of the standard integration. Unrelated source edits are preserved. See complete uninstall.
See exactly which native inputs changed
Helper 1.8.0 saves file-level SHA-256 hashes with each new prepare-native registration. Fingerprint schema 2 and all compatibility rules are unchanged. Existing working runtimes keep the same hash. Only relative input paths and hashes are uploaded; file contents and absolute laptop paths are not uploaded.
The hashes cover the same inputs as the runtime fingerprint: native project files, linked dependency files and Codegen specifications. Configuration hashes use the existing normalization (for example, version labels and managed OTA settings are excluded); they are not necessarily raw file checksums. Ordinary UI JavaScript and assets remain outside this native fingerprint.
To compare your current project with an exact registered build:
sh
node ota.cjs diagnose-native ios --target-version 1.4.5 --build-number 3sh
node ota.cjs diagnose-native android --target-version 1.4.5 --build-number 12The terminal lists added, changed and removed paths, with before/after hashes. It prints the first 50 changes; add --all to print them all. A mismatch exits with an error. It saves a comparison in Native compatibility → the build → File diagnostics, where you can search paths, filter change types, load more results and copy hashes. Refresh that panel after running a new comparison. Its timestamp and author identify a saved comparison, not a live view of your computer.
If publication fails and there is one unambiguous build for the target version/variant, the helper saves this comparison automatically. An explicit --recovery-build selects that recovery's baseline. With multiple possible baselines, run diagnose-native with the exact build number; the publisher will not guess. Diagnosing a mismatch never authorizes it. The signed release runtime, exact target version, server checks and device checks remain enforced.
New preparation also saves ota-setup/ios/native-manifest.json or ota-setup/android/native-manifest.json for offline build-guard errors. Keep that file with the prepared project. A missing or edited snapshot does not disable the runtime check; it only limits file-level explanation. Complete uninstall removes these generated files through the installation receipt.
Older builds and later capture
Older registrations contain only an overall fingerprint. They show File evidence unavailable, not “zero changes.” We cannot reconstruct an original snapshot from a hash or name a changed file without a baseline. Repeating prepare-native for an old registration does not relabel today's evidence as an original preparation record.
If you still have matching source inputs, explicitly attach a snapshot:
sh
node ota.cjs capture-native ios --target-version 1.4.5 --build-number 3
# Android uses the same command with android and its exact version/build.This command succeeds only if the freshly computed fingerprint equals the build's approved source fingerprint. The dashboard labels it Captured later. It is not original archive evidence. For an approved existing-build recovery, it describes the reviewed source, while the installed app retains its original runtime. The recovery attestation, build registration and existing releases are unchanged. A mismatch or unsupported older fingerprint schema is rejected; there is no force option or hash fallback.
Only administrators and app Publishers may save comparisons or matching snapshots. Members with view access can read them. Automation credentials need register-native to capture a snapshot, and publish to save a comparison; access remains restricted to the credential's app.
Snapshots are immutable, deduplicated per app, and included in the SQLite backup. Each app has a 64 MiB snapshot budget; individual snapshots accept up to 20,000 inputs and 2 MiB of JSON. The latest comparison is retained for each of the 20 most recently compared builds. Older comparison reports may expire; registered snapshots remain. Deleting an app removes its snapshots and comparisons.