React Native SDK

If your app is using React Native the SDK helps you to easily integrate appcockpit.dev.

Links

• NPM

• Github

Functionality

Versions

Whenever the SDK detects a new version it will show an alert or UI component informing the user and ask them to update.

Maintenance mode

The SDK can request the current maintenance mode for an app. Showing the UI is up to the specific use case of your app.

Installation

Install via npm

npm i appcockpit-react-native-sdk --save

Setup

• Make sure you followed the Getting started guide

• Copy your API Token from the app settings

Pre-built update version UI

Pre-built regular update UI

Pre-built force update UI

For a more streamlined integration, you can use the pre-built update UI provider that handles version checking and update prompts automatically:

import { AppUpdateProvider } from "appcockpit-react-native-sdk";

const App = () => {
  const info = {
    platform: Platform.OS === "ios" ? "ios" : "android",
    appId: "<appcockpit_app_id>",
    appstoreId:
      Platform.OS === "ios" ? "<apple_app_store_id>" : "<play_store_id>",
    appVersion: "1.0.0",
    environment: "production",
  };

  const apiKey = "<api_token>";

  // Optional theme for the update button:
  const theme = {
    updateButton: {
      backgroundColor: "#FF0000",
      textColor: "white",
    },
  };

  return (
    <AppUpdateProvider info={info} apiToken={apiKey} theme={theme}>
      <AppContent />
    </AppUpdateProvider>
  );
};

The AppUpdateProvider automatically handles:

• Version checking on app startup
• Displaying update prompts when needed
• Managing force update scenarios
• Redirecting to app stores for updates

Custom update version UI

You can customize the update screen by providing your own CustomUpdateScreen component, or omit it to use the default update UI.

import { AppUpdateProvider } from "appcockpit-react-native-sdk";

const App = () => {
  const info = {
    platform: Platform.OS === "ios" ? "ios" : "android",
    appId: "<appcockpit_app_id>",
    appstoreId:
      Platform.OS === "ios" ? "<apple_app_store_id>" : "<play_store_id>",
    appVersion: "1.0.0",
    environment: "production",
  };

  const apiKey = "<api_token>";

  return (
    <AppUpdateProvider
      CustomUpdateScreen={CustomUpdateScreen}
      info={info}
      apiToken={apiKey}
    >
      <AppContent />
    </AppUpdateProvider>
  );
};

Custom Update Screen Implementation

When creating a custom update screen, your component must call the provided callbacks to allow the SDK to manage state and handle app store redirects:

type UpdateScreenProps = PropsWithChildren<{
  versionInfo: VersionResponse;
  appInfo: AppInfo;
  onClose: () => void;
  onUpdate: () => void;
}>;

const CustomUpdateScreen: React.FC<CustomUpdateScreenProps> = ({
  versionInfo,
  onUpdate,
  onClose,
}) => {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Update Available</Text>
      <Text style={styles.message}>
        Version {versionInfo.version} is now available. Please update to
        continue.
      </Text>

      <View style={styles.buttonContainer}>
        <TouchableOpacity style={styles.updateButton} onPress={onUpdate}>
          <Text style={styles.updateButtonText}>Update Now</Text>
        </TouchableOpacity>

        {!versionInfo.force_update && (
          <TouchableOpacity style={styles.closeButton} onPress={onClose}>
            <Text style={styles.closeButtonText}>Later</Text>
          </TouchableOpacity>
        )}
      </View>
    </View>
  );
};

Important callbacks:

• onUpdate(): Call this when the user wants to update. The SDK will redirect to the app store.
• onClose(): Call this when the user dismisses the update (only available for non-forced updates).

Version update alert

Regular update alert

Force update alert

Import the SDK and call the version check function in your startup phase of the app.

import { checkVersionUpdate } from 'appcockpit-react-native-sdk';

const App () => {
  const info = {
    platform: Platform.OS === "ios" ? "ios" : "android",
    appId: "<appcockpit_app_id>",
    appstoreId:
      Platform.OS === "ios" ? "<apple_app_store_id>" : "<play_store_id>",
    appVersion: "1.0.0",
    environment: "production",
  };

  const apiKey = "<api_token>";

  useEffect(() => {
    checkVersionUpdate(info, apiKey);

  }, []);

  return (<AppContent />);
};

Pre-built maintenance mode UI

Pre-built maintenance mode UI

For a streamlined maintenance mode integration, you can use the pre-built maintenance UI provider that handles maintenance checking and display automatically:

import { MaintenanceProvider } from "appcockpit-react-native-sdk";

const App = () => {
  const info = {
    appId: "<appcockpit_app_id>",
    environment: "production",
  };

  const apiKey = "<api_token>";

  // Optional theme for the maintenance screen:
  const theme = {
    backgroundColor: "#FFFFFF",
    textColor: "#000000",
  };

  return (
    <MaintenanceProvider info={info} apiToken={apiKey} theme={theme}>
      <AppContent />
    </MaintenanceProvider>
  );
};

The MaintenanceProvider automatically handles:

• Maintenance mode checking on app startup
• Displaying maintenance screen when maintenance mode is active
• Blocking app access during maintenance
• Periodic re-checking of maintenance status

Custom maintenance mode UI

You can customize the maintenance screen by providing your own MaintenanceScreen component, or omit it to use the default maintenance UI.

import { MaintenanceProvider } from "appcockpit-react-native-sdk";

const App = () => {
  const info = {
    appId: "<appcockpit_app_id>",
    environment: "production",
  };

  const apiKey = "<api_token>";

  return (
    <MaintenanceProvider
      MaintenanceScreen={MaintenanceScreen}
      info={info}
      apiToken={apiKey}
    >
      <AppContent />
    </MaintenanceProvider>
  );
};

Custom Maintenance Screen Implementation

When creating a custom maintenance screen, your component receives maintenance information that you can display to users:

type MaintenanceScreenProps = {
  maintenanceInfo: MaintenanceResponse;
};

const CustomMaintenanceScreen: React.FC<MaintenanceScreenProps> = ({
  maintenanceInfo,
}) => {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>
        {maintenanceInfo.title || "Under maintenance"}
      </Text>
      <Text style={styles.message}>
        {maintenanceInfo.description ||
          "We're currently performing maintenance. Please check back soon."}
      </Text>
    </View>
  );
};

Manual maintenance mode check

• Make sure you followed the Getting started guide

• Copy your API Token from the app settings

Import the SDK and call the fetch maintenance function in your startup phase of the app.

import { fetchMaintenance } from 'appcockpit-react-native-sdk';

const App () => {

  useEffect(() => {
    const fetchMaintenance = async () => {
      try {
        const maintenance = await getMaintenanceMode(
          {
            appId: "<appcockpit_app_id>",
            environment: "production",
          },
          "<api_token>"
        );

        console.log("Maintenance mode:", maintenance);
      } catch (error) {
        console.error("Error fetching maintenance mode:", error);
      }
    };

    fetchMaintenance();
  }, []);

  return (<AppContent></AppContent>);
};

Language Support

The SDK supports multiple languages for update prompts and maintenance screens. You can specify the language by using the LanguageKey enum exported by the SDK.

Usage with version check:

import { checkVersionUpdate, LanguageKey } from "appcockpit-react-native-sdk";

useEffect(() => {
  checkVersionUpdate(info, apiKey, LanguageKey.DE);
}, []);

Usage with providers:

import { AppUpdateProvider, LanguageKey } from "appcockpit-react-native-sdk";

<AppUpdateProvider info={info} apiToken={apiKey} language={LanguageKey.DE}>
  <AppContent />
</AppUpdateProvider>;

If no language is specified, the SDK defaults to English.