Appearance
Test devices
Use the same native build in TestFlight or Google Play testing and in the public store. Configure it for Production. Approve individual installations to receive Staging updates.
PushOTA does not infer access from TestFlight, a Play track, an app login, or a version number. A paired installation of 1.4.1 receives Staging; an unpaired installation of that same version receives Production. Native compatibility checks still apply.
Integrate once
- Run the current dashboard Setup guide for each platform app. Both deployments are created automatically.
- Merge the generated Production native settings, including
CodePushTestDevicePairingEnabled. Install the supplied SDK, update iOS pods, and register the resulting native build using the guide. - Keep the readiness/update helper connected after healthy startup.
- Place the generated
ota-setup/OtaTestingEntry.jsxin a settings, support or developer screen of your choice:
jsx
import OtaTestingEntry from "./ota-setup/OtaTestingEntry";
// Inside your chosen screen's render output:
<OtaTestingEntry />;Adjust the relative import path to your screen. Opening the panel grants no testing access. You control where users find it; there is no automatic hidden gesture or app-account requirement.
For your own entry button, import OTATestingPanel from @appzung/react-native-code-push and supply visible and onClose. It supports light/dark appearance, selectable pairing codes and Leave testing. Keep it mounted while its visible state changes.
Distribute a new native build. Pairing adds native persistence and activation checks on iOS and Android; JavaScript OTA cannot add them to an older binary. Production and Staging share the app's signing identity. No publishing credential, dashboard password or private signing key belongs in the app.
Pair an installation
- The tester opens OTA testing and selects Generate pairing code.
- They give the code to the project owner. It expires in 10 minutes and can be approved once.
- The owner selects the correct platform app, opens Test devices, enters the code and a device name, acknowledges Staging protection and selects Approve device.
- The active, visible panel checks every five seconds. Approval switches to Staging, clears previous channel updates and restarts from the embedded bundle. The normal update worker then fetches a compatible Staging release.
Approval lasts 90 days, is scoped to this app installation, and survives restarts. Another app, phone or reinstall must pair separately. Organisation administrators approve/remove installations; all organisation members can view the list through their default Viewer access. Publisher access does not grant device management. Scoped publishing tokens cannot manage devices.
The first approval enables pairing-only Staging delivery for this platform app. Existing builds using a fixed Staging key stop receiving Staging updates. Migrate them to Production configuration with pairing first. Production and Staging cannot be renamed or deleted while this policy is enabled. Other deployment names are not protected by pairing; do not use them as protected testing channels.
New Staging download links expire after 15 minutes and are checked against the approved installation on every download request. Removing that installation rejects future requests, including previously issued links. Removal cannot retract bytes already downloaded, or public/cached artifacts from before pairing protection was enabled. Releases promoted to Production remain publicly downloadable by design.
Publish, test and promote
Publish to Staging, test the feature and recovery, then promote the signed release to Production in the dashboard. Promotion does not change device membership.
sh
node ota.cjs publish ios --deployment Staging --target-version 1.4.1
node ota.cjs publish android --deployment Staging --target-version 1.4.1Run each command in its configured project. Omit --target-version to detect the latest public store version. A newer TestFlight/Play testing version needs its explicit version. Lookup failure stops and asks for a version; it never guesses.
Remove or leave testing
Select Remove beside an installation. Server authorization ends immediately. At the next successful pairing check, the client discards its credential, invalidates old downloads, clears current/pending/backup OTA packages and restarts from the binary's embedded bundle. The normal worker then checks Production. An old in-flight Staging package cannot activate after that transition.
Leave testing resets the local route even offline. If the server was unreachable, its list entry remains until the owner removes it or it expires. The installation has discarded its credential and uses Production locally.
An offline app keeps its current healthy version until it reconnects. Removal cannot instantly change an unreachable device. Network/server errors preserve the channel and abort new downloads until a later successful check. Cancelling an unused pairing code keeps the healthy Production version.
Pairing does not erase app data or reverse database migrations. Keep data formats compatible with embedded and rollback versions. Channels control update eligibility, not confidentiality: distributed bundle URLs and installed app files are not secret storage.
Programmatic API
The SDK exports beginTestDevicePairing(), getTestDeviceStatus(refresh = false) and leaveTestDevicePairing(). Status exposes the channel, pairing state, code and expiry where applicable, never the device credential. Native installation storage excludes the credential from cloud backup and keeps it separate from OTA package files.
The panel and regular update checks handle routing. Do not override releaseChannelPublicId in a pairing-enabled app; conflicting overrides are rejected.
Troubleshooting
- Invalid, expired or used code: generate another and select the right platform app.
- Pairing not enabled: merge current Production settings, rebuild and install that binary.
- Still on Staging after removal: open the app online and check for updates, or open the panel. Check connectivity to your OTA server.
- No update after approval: confirm a Staging release matches the native version and registered runtime. Pairing never relaxes signatures or compatibility.
- Missing device: approvals expire after 90 days. Reinstallation requires pairing again.
See uninstall to remove the generated panel, standard imports, settings and SDK wiring together.