ota-sdk-mac 🚀

The official Over-the-Air (OTA) update SDK for React Native. Keep your apps up-to-date without waiting for App Store or Play Store reviews.

⚡️ Getting Started in 4 Steps

1. Get your API Key: Create an account on your OTA Admin Panel and generate an API Key.
2. Install the SDK: npm install ota-sdk-mac and follow the Setup Guide.
3. Initialize the App: Add the Usage Logic to your App.tsx.
4. Push your first update: Use the OTA CLI to deploy.

🏗 How it Works

graph TD
    A[Developer Laptop] -->|ota release-react| B(OTA Backend)
    B -->|S3 + Manifest| C{Storage}
    D[User Device] -->|Check Update| B
    B -->|Download URL| D
    D -->|Download & Verify| D
    D -->|Atomic Swap| D
    D -->|Next Launch| E[New Bundle Active]

🔧 Setup Guide

Android Setup

Option A: React Native < 0.75 (Classic)

In MainApplication.kt, change your ReactNativeHost base class:

override val reactNativeHost: ReactNativeHost =
  object : OtaReactNativeHost(this) {             
    override fun getPackages() = PackageList(this).packages.apply {
        add(OtaPackage())
    }
  }

Option B: React Native 0.75+ (New Architecture / Bridgeless)

Update MainApplication.kt to use the OtaBundleLoader:

import com.pyqota.OtaBundleLoader
import com.pyqota.OtaPackage

override val reactHost: ReactHost by lazy {
    val bundlePath = OtaBundleLoader.resolveOrNull(this)
    DefaultReactHost.getDefaultReactHost(
      context = applicationContext,
      packageList = PackageList(this).packages.apply { add(OtaPackage()) },
      jsBundleFile = bundlePath
    )
}

iOS Setup (Crucial)

Unlike standard libraries, you must manually update your AppDelegate to tell React Native to load the JS bundle from the OTA storage instead of the default location.

Option A: Swift (AppDelegate.swift)

import react_native_ota

class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
  override func bundleURL() -> URL? {
    #if DEBUG
      return RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
    #else
      return OtaModule.bundleURL() // <--- ADD THIS
    #endif
  }
}

Option B: Objective-C (AppDelegate.mm)

#import <react-native-ota/OtaModule.h>

- (NSURL *)bundleURL {
#if DEBUG
  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
#else
  return [PYQOTA bundleURL]; // <--- ADD THIS
#endif
}

📱 Usage

You have two ways to initialize the SDK. Option B is recommended for production apps as it allows you to rotate keys without a new app release.

Option A: Basic (Hardcoded Keys)

Best for quick testing or simple apps.

import OTAClient from 'ota-sdk-mac';

const client = OTAClient.builder()
  .appId('your.bundle.id')
  .apiKey('your-api-key')
  .endpoint('https://ota.api.com')
  .build();

async function init() {
  await client.configure(); // Mandatory
  await client.rollbackIfCrashed();
  client.sync(); // Check & Apply
}

Option B: Self-Healing (Recommended) 🛡️

Best for production. Loads keys from native manifests and can automatically "heal" (fetch fresh keys) if your API key expires or is leaked.

1. Add Native Defaults

Add your initial configuration to the native manifests:

• Android (AndroidManifest.xml): Add <meta-data android:name="OTA_API_KEY" android:value="..." /> inside the <application> tag.
• iOS (Info.plist): Add OTA_API_KEY and OTA_ENDPOINT keys.

2. Initialize in JS

const client = OTAClient.builder()
  .appId('your.bundle.id')
  .build();

async function init() {
  // selfHealingInit automatically calls client.configure() for you 
  // after it finds or fetches valid keys.
  await client.selfHealingInit('https://your-config-server.com/ota-discovery.json');
  
  await client.rollbackIfCrashed();
  client.sync();
}

⏱ Stability Marker (Important)

To prevent accidental rollbacks, you must tell the SDK when the app has booted successfully (e.g., after 5 seconds of stable runtime):

setTimeout(() => client.markGood(), 5000);

📊 Tracking Download Progress

You can track download progress and show a loading bar in your UI using the built-in progress listener:

import OTAClient, { addDownloadProgressListener } from 'ota-sdk-mac';

// 1. Start listening for progress
const subscription = addDownloadProgressListener((progress) => {
  console.log(`Downloaded: ${progress.bytesDownloaded} / ${progress.totalBytes}`);
  console.log(`Percent: ${progress.percent}%`);
});

// 2. Start the download
await client.download(update.info);

// 3. Clean up the listener when you're done
subscription.remove();

Alternatively, if you use the client.sync() convenience method, you can pass the listener directly:

await client.sync({
  onProgress: (progress) => {
    setDownloadPercent(progress.percent);
  }
});

🚀 Publishing Updates (CLI)

Use the companion OTA CLI to push updates from your CI/CD or local machine:

npx --package ota-cli-mac ota release-react \
  --appId com.yourcompany.app \
  --platform android \
  --apiKey YOUR_API_KEY

🛡 Crash Rollback System

If an update contains a bug that causes the app to crash during startup, the SDK detects it (using the markGood() timer) and automatically rolls back to the last known stable version on the next launch.

📄 License

MIT