Appearance
Connect your app
For organisation membership, app permissions and the separate platform portal, see Organisations and access.
Before you begin
Use Node 22 or later and your project's existing package manager. Run setup from the React Native app root containing package.json. The SDK supports bare React Native 0.77+ and React 18.3.1+. Setup checks the installed React/RN versions before signing in or changing configuration. For a fresh checkout, install dependencies first if package.json uses version ranges. See React Native compatibility for native templates and migration steps.
Connect the project
- Create or select the correct platform app in the dashboard. Keep iOS and Android as separate dashboard apps.
- Open Setup guide and run its copied connect command from your project folder. The platform chosen during application creation is saved with that app. Older apps without a saved platform ask you to choose explicitly before showing commands; a choice from another app is never reused.
- Sign in when prompted. The helper downloads the pinned SDK and installs it with package scripts disabled.
Setup creates ota.config.json, platform snippets under ota-setup, a readiness helper, an AI integration guide and a vendored SDK archive. It automatically merges Production settings into the app's Info.plist or Android resources, including the server URL, public signing key and pairing flag. Private signing keys and expiring login sessions stay under ~/.pushota, outside your project. Back up the signing key securely.
For several iOS app targets or a custom Android module, pass --native-config with the intended app's configuration file. Setup identifies a single APPL plist without confusing it with a test bundle. Ambiguous targets stop before login or configuration changes. Android defaults to android/app/src/main/res/values/ota_config.xml; duplicate OTA entries in sibling values files are removed, while unrelated resources remain.
Repeat setup to refresh settings without duplicating entries or rotating keys. Native files and the AI guide are tracked for uninstall. See AI-assisted integration to let Codex or Claude finish the project-specific wiring.
Setup verifies the installed SDK's exact source revision after the package manager finishes. Yarn Classic refreshes its local archive cache when revisiting an SDK revision. A stale installation stops setup with an error rather than reporting that the expected SDK was installed.
Android OTA strings in qualified resources such as values-fr or other source sets can override the selected configuration. Setup and native preparation list these conflicting files and stop without changing them. Reconcile intentional variants before retrying. Embedded iOS framework and bundle plists are excluded from app discovery; an ambiguous application target still needs --native-config.
Wire the native app
Follow the dashboard's platform-specific steps. Native XML settings are already applied by the latest helper; the dashboard keeps them available as a reference. Merge the matching native bundle-loader code into the existing loader, preserving surrounding initialization.
Use the generated Production settings, including the pairing flag. Approved installations switch to Staging without a separate store build. Add ota-setup/OtaTestingEntry.jsx to a screen of your choice; see Test devices for owner approval and removal.
Setup also generates ota-setup/startOtaUpdates.js. Wire it once in the app root after essential startup checks succeed. Use your existing healthy-startup boolean instead of startupReady below and adjust the relative import path. Keep the ownership comments around OTA-only additions, so uninstall can remove the effect and its imports without removing your existing startup logic.
js
// BEGIN PUSHOTA
import { useEffect as useOtaEffect } from "react";
import { startOtaUpdates } from "./ota-setup/startOtaUpdates";
// END PUSHOTA
// BEGIN PUSHOTA
// Inside your app root, using your existing healthy-startup boolean:
useOtaEffect(() => {
if (!startupReady) return;
let disposed = false;
let stopUpdates;
startOtaUpdates()
.then((stop) => {
if (disposed) stop();
else stopUpdates = stop;
})
.catch((error) => console.warn("OTA startup readiness failed", error));
return () => {
disposed = true;
stopUpdates?.();
};
}, [startupReady]);
// END PUSHOTAThis keeps the returned cleanup function and also handles startup resolving after the component has unmounted. Do not mark unrelated code for removal. See readiness before choosing the health milestone. Verify the integration with node ota.cjs uninstall --dry-run; customized source wiring must be recognized before treating setup as complete.
Distribute the native build
Install iOS pods through your project's normal workflow. Build and distribute the native app through the store testing track, then install that build before testing OTA. A JavaScript update cannot introduce the native OTA SDK into an already-installed app.
The helper keeps an outside-project installation receipt so uninstall can reverse the standard integration, even if you delete the public config.
Existing installations automatically reuse their original private directory, signing keys and installation receipts. Legacy helper filenames and environment variables remain accepted during migration. New projects use the neutral names shown here.