@approov/react-native-approov
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.6 • Public • Published

    Approov Quickstart: React Native

    This quickstart is written specifically for Android and iOS apps that are implemented using React Native and the React Native Networking, including any networking based on the XMLHttpRequest API so including frisbee and axios. Support is also provided for rn-fetch-blob. If this is not your situation then check if there is a more relevant quickstart guide available.

    This quickstart provides the basic steps for integrating Approov into your app. A more detailed step-by-step guide using a Shapes App Example is also available.

    To follow this guide you should have received an onboarding email for a trial or paid Approov account.

    CHECK INTEGRATION COMPATIBILITY

    The Approov npm package provides a special check command to see if the app is ready for integration. Execute this using npx in the top level directory of your app:

    npx @approov/react-native-approov check
    

    Note, although the npx command may ask to install the package it is not permanently added to your app.

    The output provides a checklist and reports any issues. Fix any errors reported, such as version updates or extra permissions. On Android, for example, the minimum SDK is 21, and the additional ACCESS_NETWORK_STATE permission is required. Please read this section of the reference documentation if targeting Android 11 (API level 30) or above.

    Once all issues are fixed, you should rerun your app to verify it is working as before. You are now ready to add Approov protection.

    ADDING THE APPROOV PACKAGE

    Add the Approov package to your existing App with the following command:

    npm install @approov/react-native-approov
    

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

    pod install
    

    ACTIVATING APPROOV

    In order to use Approov you must include it as a component that wraps your application components. This automatically deals with initializing Approov when the app is started. Import using the following:

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

    This defines an ApproovProvider component and the ApproovService which allows you to make certain calls to Approov from your application.

    You should define an initially empty function that is called just before Approov is initialized. You may wish to include certain ApproovService calls in this in the future:

    const approovSetup = () => {
    };

    You must now wrap your application with the ApproovProvider component. For instance, if your app's components (typically defined in App.js) are currently:

    return (
      <View>
        <Button onPress={callAPI} title="Press Me!" />
      </View>
    );

    This should be changed to the following:

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

    The <enter-your-config-string-here> is a custom string that configures your Approov account access. This will have been provided in your Approov onboarding email.

    CHECKING IT WORKS

    Once the initialization is called, it is possible for any network requests to have Approov tokens or secret substitutions made. Initially you won't have set which API domains to protect, so the requests will be unchanged. It will have called Approov though and made contact with the Approov cloud service. You will see ApproovService logging indicating UNKNOWN_URL (Android) or unknown URL (iOS).

    You may use the ApproovMonitor component (also imported from @approov/react-native-approov) inside the ApproovProvider. This will output console logging on the state of the Approov initialization.

    On Android, you can see logging using logcat output from the device. You can see the specific Approov output using adb logcat | grep ApproovService. On iOS, look at the console output from the device using the Console app from MacOS. This provides console output for a connected simulator or physical device. Select the device and search for ApproovService to obtain specific logging related to Approov.

    Your Approov onboarding email should contain a link allowing you to access Live Metrics Graphs. After you've run your app with Approov integration you should be able to see the results in the live metrics within a minute or so. At this stage you could even release your app to get details of your app population and the attributes of the devices they are running upon.

    NEXT STEPS

    To actually protect your APIs there are some further steps. Approov provides two different options for protection:

    • API PROTECTION: You should use this if you control the backend API(s) being protected and are able to modify them to ensure that a valid Approov token is being passed by the app. An Approov Token is short lived crytographically signed JWT proving the authenticity of the call.

    • SECRETS PROTECTION: If you do not control the backend API(s) being protected, and are therefore unable to modify it to check Approov tokens, you can use this approach instead. It allows app secrets, and API keys, to be protected so that they no longer need to be included in the built code and are only made available to passing apps at runtime.

    Note that it is possible to use both approaches side-by-side in the same app, in case your app uses a mixture of 1st and 3rd party APIs.

    See FAQ for answers to common questions about the integration and troubleshooting.

    See REFERENCE for a complete list of all of the Approov related methods.

    RN-FETCH-BLOB

    Support is provided for the rn-fetch-blob networking stack. However, to use this a special fork of the package must be used. This is available at @approov/rn-fetch-blob. You will need to uninstall the standard package and install the special one as follows:

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

    Install

    npm i @approov/react-native-approov

    DownloadsWeekly Downloads

    165

    Version

    3.0.6

    License

    MIT

    Unpacked Size

    14.8 MB

    Total Files

    349

    Last publish

    Collaborators

    • johannesschneiders
    • skiph
    • jexh
    • paulos.approov
    • richardmtaylor