@cubebox/react-native-update-manager

Professional Update Manager and Compliance System for React Native apps. Handle forced updates, maintenance mode, device blocking, and more with a simple, customizable API.

✨ Features

• 🔄 Automatic Version Checks: Checks against your backend for new versions
• 🚨 Forced Updates: Block access until the user updates
• 💬 Optional Updates: Show a modal suggesting an update
• 🔒 Compliance System: Block specific devices or show warnings
• 🛠️ Maintenance Mode: Show a maintenance screen during downtime
• 📊 Device Tracking: Automatic heartbeats and device metadata
• 🎨 Customizable UI: Use built-in screens or bring your own
• ⚡ Performance: Caching with MMKV and optimized network calls

📦 Installation

npm install @cubebox/react-native-update-manager

Peer Dependencies

You need to install these dependencies:

npm install react-native-mmkv @react-native-community/netinfo react-native-device-info

iOS Setup

cd ios && pod install

🚀 Quick Start

Wrap your app with UpdateProvider and UpdateGate:

import { UpdateProvider, UpdateGate } from '@cubebox/react-native-update-manager';

const config = {
  backendUrl: 'https://api.myapp.com/updates',
  packageName: 'com.myapp',
  versionCode: 1,
  checkOnForeground: true,
  // Optional: Custom assets (GIFs)
  assets: {
    updateGif: require('./assets/rocket.gif'),
    blockedGif: require('./assets/blocked.gif'),
    maintenanceGif: require('./assets/maintenance.gif'),
    warningGif: require('./assets/warning.gif'),
  }
};

function App() {
  return (
    <UpdateProvider config={config}>
      <UpdateGate>
        <YourApp />
      </UpdateGate>
    </UpdateProvider>
  );
}

⚙️ Configuration

The config object accepts the following properties:

| Property | Type | Required | Description | |----------|------|----------|-------------| | backendUrl | string | Yes | Base URL of your update API | | packageName | string | Yes | Your app's package name / bundle ID | | versionCode | number | Yes | Current build number of the app | | assets | object | No | Custom assets (GIFs) for UI screens | | trackingUrl | string | No | URL for metrics (defaults to backendUrl) | | checkOnForeground | boolean | No | Check for updates when app becomes active | | backgroundIntervalMinutes | number | No | Interval for background checks | | shouldShowUpdate | (info) => boolean | No | Custom logic for forced updates |

🔌 Backend API Specification

Your backend should respond to GET {backendUrl}/{packageName}/{versionCode} with:

{
  "success": true,
  "data": {
    "exists": true,
    "app_name": "My App",
    "package_name": "com.myapp",
    "current_version": {
      "version": "1.2.0",
      "version_code": 5,
      "changelog": "Bug fixes and improvements",
      "download_url": "https://play.google.com/store/apps/details?id=com.myapp"
    },
    "installed_version": {
      "version_code": 1
    },
    "needs_update": true,
    "force_update": true,
    "optional_update": false,
    "maintenance_mode": false,
    "compliance": {
      "status": "active" // or "warning", "blocked"
    }
  }
}

📱 UI Components

The package includes these built-in components used by UpdateGate:

• UpdateRequiredScreen: Shown when force_update is true
• UpdateOptionalModal: Shown when optional_update is true
• BlockedScreen: Shown when compliance status is blocked
• MaintenanceScreen: Shown when maintenance_mode is true
• WarningModal: Shown when compliance status is warning

🪝 Hooks

useUpdateManager()

Access the update state manually:

import { useUpdateManager } from '@cubebox/react-native-update-manager';

function MyComponent() {
  const { needsUpdate, updateInfo, checkNow, isChecking } = useUpdateManager();

  return (
    <View>
      <Text>Checking: {isChecking ? 'Yes' : 'No'}</Text>
      <Button title="Check Update" onPress={checkNow} />
    </View>
  );
}

📊 Device Tracking

The package automatically sends heartbeats to {trackingUrl}/metrics/heartbeat if configured.

You can also track custom events:

import { trackEvent } from '@cubebox/react-native-update-manager';

trackEvent(backendUrl, packageName, 'custom_event', { foo: 'bar' });

📄 License

MIT