> 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/cordova.md).

# Cordova

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

## 📝 Prerequisites

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

### Android

The Android implementation uses Kotlin serialization plugin; following line has to be added to the plugins block in `platforms/android/build.gradle`:

{% code title="platforms/android/build.gradle" %}

```gradle
plugins {
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.7.10'
}
```

{% endcode %}

freeRASP requires `minSdkVersion` level of **>=23,** `targetSdkVersion` level of **>=31,** `compileSdkVersion` level of **>=34, and Kotlin support**.&#x20;

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

Add the following lines to the `config.xml` file in your project root directory.

{% code title="config.xml" %}

```xml
<preference name="GradlePluginKotlinEnabled" value="true" />
<preference name="GradlePluginKotlinCodeStyle" value="official" />
<preference name="GradlePluginKotlinVersion" value="2.0.0" />
<preference name="android-minSdkVersion" value="23" />
<preference name="android-targetSdkVersion" value="31" />
<preference name="android-compileSdkVersion" value="34" />
```

{% endcode %}

Then run the following command to apply the preferences:

{% code title="bash" %}

```bash
$ cordova prepare android
```

{% endcode %}

#### 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 permission to your Android Manifest (via `config.xml`):

```xml
 <platform name="android">
  <config-file target="AndroidManifest.xml" parent="/*">
   <uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />
   <uses-permission android:name="android.permission.DETECT_SCREEN_RECORDING" />
  </config-file>
</platform>
```

{% 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
await talsec.blockScreenCapture(true);
```

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

```jsx
const response = await talsec.isScreenCaptureBlocked();
```

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

### iOS

{% hint style="success" %}
**Skip this step if you are using `"cordova-ios"`: `"^8.0.0"` or newer**
{% endhint %}

freeRASP plugin uses Swift. Install the following plugin to support Swift in your project.

{% code title="bash" %}

```bash
$ cordova plugin add cordova-plugin-add-swift-support --save
```

{% endcode %}

***

## 📦 Install the plugin

Install the plugin using Cordova CLI

{% code title="bash" %}

```bash
cordova plugin add cordova-talsec-plugin-freerasp
```

{% 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/cordova/api.md#talsecconfig).

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="index.js / main.ts" %}

```javascript
/* global cordova, talsec */

const config = {
    androidConfig: {
        packageName: 'com.example.helloapp',
        certificateHashes: ['mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k='],  // replace with your release (!) signing certificate hash(es)
        supportedAlternativeStores: ['com.sec.android.app.samsungapps'],
    },
    iosConfig: {
        appBundleIds: 'com.example.helloapp',
        appTeamId: 'your_team_ID'
    },
    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/isprod-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-javascript" data-title="index.js / main.ts"><code class="lang-javascript">// reactions to 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');
    },
};
</code></pre>

## 👷 RASP Execution State Listener

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

{% code title="index.js/main.ts" %}

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

{% endcode %}

***

## 🛡️ Start freeRASP

freeRASP can be started after the Cordova initialization is completed, for example, inside the `onDeviceReady` function in the `index.js`.

{% code title="index.js / main.ts" %}

```javascript
import { Talsec } from 'cordova-talsec-plugin-freerasp'; // import of type declaration

declare var talsec: Talsec; // interface declaration for .ts projects

talsec.start(config, actions, raspExecutionStateActions)
    .then(() => {
        console.log('Talsec initialized.');
    })
    .catch((error) => {
        console.log('Error during Talsec initialization: ', error);
    });
```

{% endcode %}

{% 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-Cordova/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"
        }
    }
}
```

Additionally, create or extend `proguard-rules.pro` in `android/app` folder and exclude Cordova’s specific classes that rely on package names from being obfuscated:

{% code title="proguard-rules.pro" %}

```
-keep class org.apache.cordova.** {*;}
-keep public class * extends org.apache.cordova.CordovaPlugin
-flattenpackagehierarchy
```

{% endcode %}

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 { Talsec } from 'cordova-talsec-plugin-freerasp';

declare var talsec: Talsec;

const yourCustomData = "user_123-456";
const result = await talsec.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 Cordova 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.