> For the complete documentation index, see [llms.txt](https://docs.talsec.app/freerasp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talsec.app/freerasp/freerasp/integration/capacitor.md).

# Capacitor

{% hint style="success" %}
Example: <https://github.com/talsec/Free-RASP-Capacitor/tree/main/example>
{% endhint %}

## 📝 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 **>=36**. 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) or higher.

{% code title="variables.gradle" %}

```gradle
ext {
    minSdkVersion 23
 }
```

{% endcode %}

#### Raise Kotlin version

Since freeRASP 2.0.0, it is necessary to raise version of Kotlin in your project.&#x20;

* From the root of your project, go to `android` **>** `build.gradle` (or equivalent).
* In `buildscript.ext`, update kotlin\_version to at least **2.0.0** or higher.

```groovy
buildscript {
    ext {
        kotlin_version = '2.0.0'
    }
```

#### Enable Screenshot and Screen Recording Detection

To [detect screenshots](/freerasp/freerasp/wiki/threat-detection/screen-capture.md#screenshot-detection) and [screen recordings ](/freerasp/freerasp/wiki/threat-detection/screen-capture.md#screen-recording-detection), add the following permissions to your `AndroidManifest.xml` file inside the `<manifest>` root tag:

```xml
 <uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />
 <uses-permission android:name="android.permission.DETECT_SCREEN_RECORDING" />
```

{% hint style="warning" %}
Screenshot Detection is supported **on Android 14 (API level 34) and higher**. \
\
Screen Recording Detection is supported **on Android 15 (API level 35) and higher**.\
\
Application of **FLAG\_SECURE** on Android Window or calling `blockScreenCapture(true)` disables this callback.
{% endhint %}

To utilize active protection, you can use&#x20;

```jsx
import { blockScreenCapture } from 'capacitor-freerasp';
await blockScreenCapture(true);
```

To receive whether the screen capture is blocked, you can use

```jsx
import { isScreenCaptureBlocked } from 'capacitor-freerasp';
const response = await isScreenCaptureBlocked();
```

For more details about all these screen capture methods, see [Screen Capture](/freerasp/freerasp/wiki/threat-detection/screen-capture.md).

### iOS

freeRASP ships both a CocoaPods podspec and a Swift Package Manager manifest. Which one gets used is determined entirely by which package manager your Capacitor iOS project itself uses — there is no freeRASP-specific configuration.

{% hint style="info" %}
**Swift Package Manager prerequisites**

* iOS Deployment Target **15.0+** (higher than the CocoaPods path, which supports 13.0+)
  {% endhint %}

{% tabs %}
{% tab title="CocoaPods" %}
This is the default when you run `npx cap add ios` (or for an existing `ios` project). Just sync as usual:

```bash
npx cap sync ios
```

{% endtab %}

{% tab title="Swift Package Manager" %}
If your iOS project was created with Capacitor's Swift Package Manager support:

```bash
npx cap add ios --packagemanager SPM
```

`npx cap sync ios` automatically adds `CapacitorFreerasp` as a local Swift Package dependency in `CapApp-SPM/Package.swift` — no manual wiring needed.

{% hint style="warning" %}
Switching an existing CocoaPods-based `ios` project to SPM (or back) is a Capacitor project-level migration, not a freeRASP-specific step. See [Capacitor's iOS documentation](https://capacitorjs.com/docs/ios) for details.
{% endhint %}
{% endtab %}
{% endtabs %}

***

## 📦 Install the plugin

Install the plugin using your preferred package manager

{% code title="npm" %}

```bash
$ npm install capacitor-freerasp
```

{% endcode %}

Synchronize the project files across native platforms

{% code title="npm" %}

```bash
$ npx cap sync
```

{% endcode %}

***

## ⚙️ 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](/freerasp/freerasp/integration/capacitor/api.md#freeraspconfig).

For Android apps, you must get your expected signing certificate hashes in Base64 form. You can go through[ this manual](/freerasp/freerasp/wiki/getting-signing-certificate-hash.md) to learn how to sign your app in more detail, including manual signing and using Google's Play app signing.&#x20;

In the the entry point to your app, import freeRASP and add the code below.&#x20;

{% code title="App.ts" %}

```typescript
import { startFreeRASP } from 'capacitor-freerasp';

// app configuration
const config = {
  androidConfig: {
    packageName: 'com.capacitor.example',
    certificateHashes: ['mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k='], // replace with your release (!) signing certificate hash(es)
    supportedAlternativeStores: ['com.sec.android.app.samsungapps'],
  },
  iosConfig: {
    appBundleId: 'com.capacitor.example',
    appTeamId: 'yourTeamID',
  },
  watcherMail: 'your_email_address@example.com', // for Security Reports, Talsec Portal, Updates
  isProd: true,
  killOnBypass: true,
};
```

{% endcode %}

{% hint style="info" %}
**Configuration Parameters**

* **`isProd`** - a boolean flag that determines whether the freeRASP integration is in the Dev or Release version. If you want to learn more about `isProd`, visit this [wiki section](/freerasp/freerasp/wiki/prod-flag.md).
* **`killOnBypass`** - a boolean flag that enables the freeRASP in-SDK reaction to kill the application if it detects any unwanted manipulation with the callback mechanisms.
* **`watcherMail`** - By providing your watcherMail, you consent to receive security reports, product updates, and other essential communications from Talsec. [Learn more](/freerasp/freerasp/wiki/role-of-watchermail.md) about the role of `watcherMail`.
  {% endhint %}

***

## 👷 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](/freerasp/freerasp/wiki/threat-detection.md) 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:

<pre class="language-typescript"><code class="lang-typescript">// reactions for detected threats
const actions = {
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-1">privilegedAccess</a>: () => {
    console.log('privilegedAccess');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-2">debug</a>: () => {
    console.log('debug');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-3">simulator</a>: () => {
    console.log('simulator');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-4">appIntegrity</a>: () => {
    console.log('appIntegrity');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-5">unofficialStore</a>: () => {
    console.log('unofficialStore');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-6">hooks</a>: () => {
    console.log('hooks');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-7">deviceBinding</a>: () => {
    console.log('deviceBinding');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-8">secureHardwareNotAvailable</a>: () => {
    console.log('secureHardwareNotAvailable');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-9">systemVPN</a>: () => {
    console.log('systemVPN');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-10">passcode</a>: () => {
    console.log('passcode');
  },
  // iOS only
  <a data-footnote-ref href="#user-content-fn-7">deviceID</a>: () => {
    console.log('deviceID');
  },
  // Android only
  <a data-footnote-ref href="#user-content-fn-11">obfuscationIssues</a>: () => {
    console.log('obfuscationIssues');
  },
  // Android only
  <a data-footnote-ref href="#user-content-fn-12">devMode</a>: () => {
    console.log('devMode');
  },
  // Android only
  <a data-footnote-ref href="#user-content-fn-13">adbEnabled</a>: () => {
    console.log('adbEnabled');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-14">screenshot</a>: () => {
    console.log('screenshot');
  },
  // Android &#x26; iOS
  <a data-footnote-ref href="#user-content-fn-15">screenRecording</a>: () => {
    console.log('screenRecording');
  },
  // Android only
  <a data-footnote-ref href="#user-content-fn-16">multiInstance</a>: () => {
    console.log('multiInstance');
  },
  // Android &#x26; iOS
  timeSpoofing: () => {
    console.log('timeSpoofing');
  },
  // Android only
  locationSpoofing: () => {
    console.log('locationSpoofing');
  },
  // Android only
  unsecureWifi: () => {
    console.log('unsecureWifi');
  },
  // Android only
  automation: () => {
    console.log('automation');
  },
  // Android only
  bootloader: () => {
    console.log('bootloader');
  },
};
</code></pre>

## 👷 RASP Execution State Listener

freeRASP can also notify apps when initial checks are done using the raspExecutionStateActions callback:

{% code title="App.jsx/App.tsx" %}

```typescript
  const raspExecutionStateActions = {
    allChecksFinished: () => {
      console.log('All checks finished');
    }
  };
```

{% endcode %}

***

## 🛡️ Start freeRASP

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

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

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

{% hint style="info" %}
For the version you’re integrating, you can find the specific **dSYMs** for debugging in [Releases](https://github.com/talsec/Free-RASP-Capacitor/releases).
{% endhint %}

***

## 🌁 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:

```gradle
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](/freerasp/freerasp/wiki/source-code-obfuscation.md).

***

## 🆔 (Optionally) Set External ID

The `externalId` allows you to send a custom identifier (such as a User ID) to the [Talsec Portal](https://my.talsec.app/). This identifier will be visible in the Dashboard, enabling you to correlate security incidents with specific users in your system.

```typescript
import { storeExternalId } from 'capacitor-freerasp';

const yourCustomData = "user_123-456";
const result = await storeExternalId(yourCustomData);

if (result) {
    console.log("External ID successfully set.");
} else {
    console.log("Failed to set External ID. Check if it contains allowed characters.");
}
```

{% hint style="info" %}
**Requirements**

* **Allowed characters**: Only alphanumeric characters (a-z, A-Z, 0-9) and the following special characters: +, \_, -, /, :, =.
* If the ID contains any other characters, the method returns `false` and the value is not stored.
  {% endhint %}

***

## ☢️ (Optionally) Integrate freeMalwareDetection

**freeMalwareDetection** is a powerful feature designed to enhance the security of your Android application by quickly and efficiently **scanning for malicious or suspicious applications** (e.g. Android malware) based on **various blacklists and security policies**.&#x20;

It helps to detect apps with **suspicious package names, hashes, or potentially dangerous permissions**.

Visit the [freeMalwareDetection](https://docs.talsec.app/freemalwaredetection) repository to learn more about this feature! For the integration, refer to the [integration guide](https://docs.talsec.app/freemalwaredetection/integration-guide/malware-detection-configuration) for the Capacitor platform.

***

## 🖥️ Check Talsec Portal

Check out [Data Visualisation Portal](/freerasp/freerasp/data-visualisation-portal.md) and register using your [watcherMail](/freerasp/freerasp/wiki/role-of-watchermail.md) to see your data. If you integrated the SDK successfully, the application will be present **after a few hours**. The visualisations will be active later due to the bucketing mechanism.

{% hint style="warning" %}
You have to use the **same email for the Portal** as you used for the **watcherMail** parameter.
{% endhint %}

[^1]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/detecting-rooted-or-jailbroken-devices>

[^2]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/debugger-detection>

[^3]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/emulator-detection>

[^4]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/app-tampering-detection>

[^5]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/detecting-unofficial-installation>

[^6]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/hook-detection>

[^7]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/device-binding-detection>

[^8]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/secure-hardware-detection-keystore-keychain-secure-storage-check>

[^9]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/system-vpn-detection>

[^10]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/passcode>

[^11]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/missing-obfuscation-detection-android-devices-only>

[^12]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/developer-mode-detection-android-devices-only>

[^13]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/adb-enabled-detection-android-devices-only>

[^14]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/screen-capture#screenshot-detection>

[^15]: Learn more: <https://docs.talsec.app/freerasp/wiki/threat-detection/screen-capture#screen-recording-detection>

[^16]: Learn more: [https://docs.talsec.app/freerasp/wiki/threat-detection/multi-instance-detection](https://docs.talsec.app/freerasp/wiki/threat-detection/multi-instance-detection-android-devices-only)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.talsec.app/freerasp/freerasp/integration/capacitor.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.