🪽Capacitor

📝 Prerequisites

The freeRASP has the following prerequisites that must be met before starting.

Android

freeRASP for Android requires a minSdkVersion level of >=23 and a targetSdkVersion level of >=33. Some Capacitor projects, by default, support even lower levels of minimum and target SDKs. This creates an inconsistency we must solve by updating the SDK levels of the application:

• From the root of your project, go to android > variables.gradle (or equivalent).

• In ext, update minSdkVersion to at least 23 (Android 6.0) and compileSdkVersion to at least 33 (Android 13) or higher.

android/variables.gradle

ext {
    minSdkVersion 23
    compileSdkVersion 33
 }

---

📦 Install the plugin

Install the plugin using your preferred package manager

npm

$ npm install capacitor-freerasp

Synchronize the project files across native platforms

npm

$ npx cap sync

---

⚙️ Setup the Configuration for your App

To ensure freeRASP functions correctly, you need to provide the necessary configuration and initialize it. All required values must be filled in for the plugin to operate properly. Use the following template to configure the plugin. Detailed descriptions of the configuration options are provided on the API page.

For Android apps, you must get your expected signing certificate hashes in Base64 form. You can go through this manual to learn how to sign your app in more detail, including manual signing and using Google's Play app signing.

In the the entry point to your app, import freeRASP and add the code below.

App.ts

import { startFreeRASP } from 'capacitor-freerasp';

// app configuration
const config = {
  androidConfig: {
    packageName: 'com.capacitor.example',
    certificateHashes: ['yourSigningCertificateHashBase64'],
    supportedAlternativeStores: ['com.sec.android.app.samsungapps'],
  },
  iosConfig: {
    appBundleId: 'com.capacitor.example',
    appTeamId: 'yourTeamID',
  },
  watcherMail: '[e-mail]',
  isProd: true,
};

---

👷 Handle detected threats

freeRASP executes periodical checks when the application is running. You can handle the detected threats using listeners. For example, you can log the event, show a window to the user or kill the application. See the Threat detection in the wiki to learn more details about the performed checks and their importance for app security.

Threat reactions can be specified inside a JavaScript object, which is then passed into the initialization function:

// reactions for detected threats
const actions = {
  // Android & iOS
  privilegedAccess: () => {
    console.log('privilegedAccess');
  },
  // Android & iOS
  debug: () => {
    console.log('debug');
  },
  // Android & iOS
  simulator: () => {
    console.log('simulator');
  },
  // Android & iOS
  appIntegrity: () => {
    console.log('appIntegrity');
  },
  // Android & iOS
  unofficialStore: () => {
    console.log('unofficialStore');
  },
  // Android & iOS
  hooks: () => {
    console.log('hooks');
  },
  // Android & iOS
  deviceBinding: () => {
    console.log('deviceBinding');
  },
  // Android & iOS
  secureHardwareNotAvailable: () => {
    console.log('secureHardwareNotAvailable');
  },
  // Android & iOS
  systemVPN: () => {
    console.log('systemVPN');
  },
  // Android & iOS
  passcode: () => {
    console.log('passcode');
  },
  // iOS only
  deviceID: () => {
    console.log('deviceID');
  },
  // Android only
  obfuscationIssues: () => {
    console.log('obfuscationIssues');
  },
  // Android only
  devMode: () => {
    console.log('devMode');
  },
};

---

🛡️ Start freeRASP

Pass the configuration and reactions you set up in previous steps into startFreeRASP function.

// returns `true` if freeRASP starts successfully; you can ignore this value
const started = await startFreeRASP(config, actions);

Based on your framework, we recommend:

• In React: Wrap this function in useEffect with an empty dependency array

• In Vue: Call the method inside the mounted property

• In Angular: Call the method inside the ngOnInit method

---

🫣 Enable source code obfuscation

The easiest way to obfuscate your app is via code minification, a technique that reduces the size of the compiled code by removing unnecessary characters, whitespace, and renaming variables and functions to shorter names. It can be configured for Android devices in android/app/build.gradle like so:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

Please note that some other modules in your app may rely on reflection, therefore it may be necessary to add corresponding keep rules into proguard-rules.pro file.

If there is a problem with the obfuscation, freeRASP will notify you about it via obfuscationIssues callback.

Read more about why this is important in the wiki.