React Native OTA Manager

A React Native library for managing Over-The-Air (OTA) updates with GitLab integration. This library provides automatic version checking, bundle downloading, and installation for React Native apps.

Features

• ✅ GitLab Integration: Direct integration with GitLab repositories
• ✅ Version Compatibility: Smart version checking with range operators (>, >=, <, <=, =)
• ✅ Build Number Tracking: Automatic build number management
• ✅ Platform Support: iOS and Android support
• ✅ Auto Update: Configurable automatic update checking
• ✅ Progress Tracking: Real-time update progress callbacks
• ✅ No UI: Pure logic component, integrate with your own UI

Installation

npm install schoolx-ota-manager
# or
yarn add schoolx-ota-manager

Dependencies

Make sure you have these dependencies installed:

npm install react-native-device-info react-native-ota-hot-update react-native-fs @react-native-async-storage/async-storage axios

Note: isomorphic-git is NOT required for this library since we download bundles directly via GitLab API, not using Git clone/pull operations.

Quick Start

1. Basic Usage with Component

import React, { useRef } from "react";
import { OTAUpdate } from "schoolx-ota-manager";

const App = () => {
  const otaRef = useRef();

  const handleProgress = (progress) => {
    console.log("Update progress:", progress.status, progress.message);
  };

  const handleUpdateAvailable = (hasUpdate) => {
    if (hasUpdate) {
      console.log("Update available!");
      // Trigger update installation
      otaRef.current?.installUpdate();
    }
  };

  return (
    <>
      <OTAUpdate
        ref={otaRef}
        gitlabToken="your-gitlab-token"
        gitlabProjectId="your-project-id"
        gitlabBaseUrl="https://gitlab.com/api/v4"
        repoFolder="schoolx-parent"
        onProgress={handleProgress}
        onUpdateAvailable={handleUpdateAvailable}
      />
      {/* Your app content */}
    </>
  );
};

2. Advanced Usage with OtaManager

import React, { useEffect } from 'react';
import { OtaManager } from 'schoolx-ota-manager';

const App = () => {
  useEffect(() => {
    const otaManager = new OtaManager({
      gitlabToken: 'your-gitlab-token',
      gitlabProjectId: 'your-project-id',
      gitlabBaseUrl: 'https://gitlab.com/api/v4',
      repoFolder: 'schoolx-parent',
      platform: 'ios', // or 'android'
      autoUpdate: false,
      checkInterval: 300000
    });

    // Set progress callback
    otaManager.onProgress((progress) => {
      console.log('Progress:', progress);
    });

    // Start auto checking
    otaManager.startAutoCheck();

    // Manual check
    otaManager.checkUpdate().then(updateInfo => {
      if (updateInfo.hasUpdate) {
        otaManager.installUpdate();
      }
    });

    return () => {
      otaManager.stopAutoCheck();
    };
  }, []);

  return (
    // Your app content
  );
};

Configuration

OtaConfig

interface OtaConfig {
  gitlabToken: string; // GitLab private token
  gitlabProjectId: string; // GitLab project ID
  gitlabBaseUrl: string; // GitLab API base URL
  repoFolder: string; // Repository folder name
  platform: "ios" | "android"; // Target platform
  autoUpdate?: boolean; // Auto install updates
}

Version Format

The version field in your version.json supports range operators:

{
  "ios": {
    "version": ">=1.0.0", // App version >= 1.0.0
    "buildNumber": 20241215001,
    "bundleType": "bytecode",
    "commitId": "main",
    "bundlePath": "ios/main.ios.hbc.jsbundle",
    "isForced": false,
    "releaseNotes": "Bug fixes and performance improvements"
  }
}

Supported operators: >, >=, <, <=, = (or no operator for exact match)

API Reference

OTAUpdate Component

Props

• gitlabToken: GitLab private token
• gitlabProjectId: GitLab project ID
• gitlabBaseUrl: GitLab API base URL
• repoFolder: Repository folder name
• onProgress: Progress callback
• onUpdateAvailable: Update availability callback
• onUpdateCompleted: Update completion callback

Ref Methods

• checkUpdate(): Check for updates
• installUpdate(): Install available update
• checkAndInstallUpdate(): Check and install if available
• checkOnAppStart(): Check for updates when app starts
• getInstalledBuildNumber(): Get current build number

OtaManager Class

Methods

• checkUpdate(): Check for updates
• installUpdate(): Download and install update
• checkAndInstallUpdate(): Check and install if available
• checkOnAppStart(): Check for updates when app starts
• onProgress(callback): Set progress callback

File Structure

Your GitLab repository should have this structure:

your-repo/
├── version.json
├── ios/
│   └── hermes.ios.hbc.zip
└── android/
    └── hermes.android.hbc.zip

Example version.json

{
  "android": {
    "version": ">=1.0.0",
    "buildNumber": 20241215001,
    "bundleType": "bytecode",
    "commitId": "main",
    "bundlePath": "android/index.android.hbc.bundle",
    "isForced": false,
    "releaseNotes": "Bug fixes and performance improvements"
  },
  "ios": {
    "version": ">=1.0.0",
    "buildNumber": 20241215001,
    "bundleType": "bytecode",
    "commitId": "main",
    "bundlePath": "ios/main.ios.hbc.jsbundle",
    "isForced": false,
    "releaseNotes": "Bug fixes and performance improvements"
  }
}

License

MIT