Approov Service for React Native

A wrapper for the Approov SDK to enable easy integration when using React Native for making the API calls that you wish to protect with Approov using fetch() or similar. In order to use this you will need a trial or paid Approov account.

Table of Contents

• Adding the Approov Dependency
• Manifest / Project Changes
• Initializing Approov
• Using Approov
• Checking It Works
• Next Steps

Adding the Approov Dependency

Add the Approov service layer to your existing app with:

npm install @approov/approov-service-react-native

If you experience an error related to peer dependencies, append --force to install with your particular React Native version. The plugin supports version 0.76 or above.

For Expo projects use:

expo install @approov/approov-service-react-native

Manifest / Project Changes

For iOS you must install pod dependencies. Change to the ios directory and run:

pod install

Do not worry if this generates warnings about duplicate UUIDs.

Initializing Approov

Import the service layer:

import { ApproovProvider, ApproovService } from '@approov/approov-service-react-native';

You MUST await successful completion of ApproovService.initialize(config) with your valid Approov configuration before making any protected request. Gate every protected request path, including background tasks and startup effects, on that completion. Android and iOS no longer wait for initialization inside their request interceptors; a request sent before initialization can proceed unprotected. If initialization fails, keep protected requests blocked. Do not rely on a startup delay or polling isInitialized() as a substitute for awaiting the initialization promise.

Initialize explicitly during startup and keep a correlation id in your app logs:

const approovSessionId = global.crypto?.randomUUID?.() || `${Date.now()}-${Math.random()}`;

async function initializeApproov() {
  try {
    await ApproovService.initialize('<enter-your-config-string-here>');

    const enabled = await ApproovService.isApproovEnabled();
    if (enabled) {
      const deviceId = await ApproovService.getDeviceID();
      console.log('Approov initialized', { approovSessionId, deviceId });
    } else {
      throw new Error('Approov protection is not enabled');
    }
  } catch (error) {
    console.error('Approov initialization failed; protected requests remain blocked', {
      approovSessionId,
      error,
    });
    throw error;
  }
}

async function startProtectedRequests() {
  await initializeApproov();
  // Start protected requests only after the await above succeeds.
}

If you prefer component-wrapped startup, wrap your application with ApproovProvider. The same initialization requirement applies: protected requests must remain blocked until initialization completes successfully, including requests started outside the provider's children. Initialization resets the token, binding and substitution headers, exclusion regexes and any service mutator, so apply those in onInitialized, which runs after each successful initialization and before approovReady becomes true. onInit runs before initialization, so anything it sets from that list is lost. See Configuration Is Reset By Initialization:

const approovConfiguration = () => {
  ApproovService.setBindingHeader('Authorization');
};

return (
  <ApproovProvider config="<enter-your-config-string-here>" onInitialized={approovConfiguration}>
    <View>
      <Button onPress={callAPI} title="Press Me!" />
    </View>
  </ApproovProvider>
);

The config string is provided in your Approov onboarding email.

Using Approov

On Android, token processing uses an application interceptor and certificate pinning uses a network interceptor. Clients share the service's pin state: initialization loads pins before its promise resolves, and SDK configuration updates refresh that state for existing clients. Creating clients does not fetch pins. The initial SDK pin fetch can still block initialization. Approov pins replace the client's built-in pinning policy; customer pins are not merged. Every HTTPS network exchange checks the current pins against the certificate chain the trust manager verified, including exchanges on reused connections; these checks do not fetch pins from the SDK.

Once initialization succeeds, network requests may have Approov tokens, message signatures, dynamic pinning, or secure substitutions applied. Initially you will not have set which API domains to protect, so requests are unchanged, but the service will contact the Approov cloud and log UNKNOWN_URL (Android) or unknown URL (iOS).

WebSockets are not supported. A WebSocket connection, including GraphQL subscriptions carried over one, is passed through without an Approov token, secure string substitution or message signature, and Approov does not pin it. Protect only HTTPS requests with Approov; GraphQL queries and mutations sent over HTTPS are protected like any other request. See USAGE.md.

Support is provided for the rn-fetch-blob networking stack through the @approov/rn-fetch-blob fork:

npm uninstall rn-fetch-blob
npm install @approov/rn-fetch-blob

Checking It Works

You may use the ApproovMonitor component, also imported from @approov/approov-service-react-native, inside ApproovProvider. This outputs console logging on the state of Approov initialization.

During initial rollout and whenever you add observability SDKs, capture ApproovService.getPinningDiagnostics() metadata in your app logging:

• Android: fetch the metadata immediately before the first protected request and verify isInterceptorPresent and isPinnerPresent. If either is false, call ApproovService.updateClientFactory(true) before proceeding.
• iOS: fetch the metadata immediately after the first protected request and inspect sessionsWithoutPinning and unpinnedSessions. This helps detect delegate conflicts, skipped sessions, and missing pinning verification early in development and staging.

On Android, use logcat and filter with adb logcat | grep ApproovService. On iOS, use the Console app for a connected simulator or device and search for ApproovService.

Your Approov onboarding email should contain a link to Live Metrics Graphs. After you run your app with Approov integration you should see results in live metrics within a minute or so.

Next Steps

• Read ARCHITECTURE.md for the service layer's network interception design on iOS and Android, race conditions, interference from third-party SDKs, and the fetchWithApproov alternative.
• Read USAGE.md for detailed instructions on message signing, token binding, custom network mutators, API protection, and secrets protection.
• Read REFERENCE.md for the complete React Native ApproovService interface.
• Read TROUBLESHOOTING.md for platform-specific setup and runtime diagnostics.
• See the Quickstart sample application for a working integration.