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

# Unity

{% hint style="warning" %}
🚨 **freeRASP for Unity – Early Release \[6/2025]**

We’re excited to introduce **freeRASP for Unity** as a new flavor of our runtime protection library. As it’s still fresh, you may encounter some **integration issues** that need to be ironed out.

We’d love to hear about your experience—good or bad. Please [open an issue on GitHub](https://github.com/talsec/Free-RASP-Unity-POC) or write us directly at **<support@talsec.app>**. Your feedback helps us make it better!
{% endhint %}

{% hint style="success" %}
**Example:** <https://github.com/talsec/Free-RASP-Unity-POC>
{% endhint %}

## 📝 Prerequisites

Ensure your development environment meets the following requirements:

* Unity Editor version **6 or higher**.
* Minimum Android SDK level **23 or higher.**

## Integration Tutorials

{% hint style="info" %}
**Note on Video Tutorials**

These videos demonstrate the end-to-end integration workflow using older SDK versions. Review them to understand the core concepts, then proceed to the **Installation and Initialization** section below to implement the current release.
{% endhint %}

### Android Workflow

{% embed url="<https://www.youtube.com/watch?v=rIAr4f_E3QE>" %}

### iOS Workflow

{% embed url="<https://youtu.be/3trxP4U7_s4>" %}

## Installation and Initialization

{% stepper %}
{% step %}

### Download the Plugin

Download the latest `freeRASP.unitypackage` file from the [GitHub Release page](https://github.com/talsec/Free-RASP-Unity-POC/releases).
{% endstep %}

{% step %}

### Import the Package

Open your Unity project. Right-click the **Assets** folder in the Project window and select **Import Package** -> **Custom Package** to import the downloaded file.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfiMqcnthBIq_-zyJjvb-2yuFV5BrTX65Q4nFd9Nj0s9m5mU0oD0Um3j5UQXXRLqGH5F1YJ5EG2RFHOEeDay2dm_FXb5qoyJj8dTtbhg-epJMAUVzMeBsP34T7Vk7QW30eclS9StA?key=zt_Rbp4WG0yuMNV-x20yvg" alt=""><figcaption><p>Editor - Import Package</p></figcaption></figure>
{% endstep %}

{% step %}

### Initialize the Plugin

Create an empty GameObject in your primary Scene, or select an existing one. Create a script named `Game.cs` and drag it from the Project window onto your GameObject in the Hierarchy or Inspector window. Unity automatically calls the `Start()` method when the Scene loads. Implement the `TalsecConfig` object and initialize the freeRASP plugin within this method.

{% hint style="info" %}
**Required Configuration Values**

* **packageName**: Your Android application package name (e.g., `com.example.app`).
* **signingCertificateHashBase64**: The Base64-encoded hash of your app's signing certificate. Read the [signing certificate guide](https://docs.talsec.app/freerasp/wiki/getting-signing-certificate-hash) for instructions on manual signing and Google Play App Signing.
* **supportedAlternativeStores**: A list of alternative distribution stores (e.g., Samsung Galaxy Store). Leave empty if distributing exclusively via Google Play.
* **appBundleIds**: Your iOS app bundle identifier (e.g., `com.example.app`).
* **appTeamId**: Your Apple Developer Team ID, located in the Apple Developer Portal under Membership.
* **watcherMailAddress**: The email address for receiving security reports. This must exactly match your Talsec Portal registration email.
* **isProd**: Set to `true` for production builds and `false` for development builds.
  {% endhint %}

```csharp
using UnityEngine;

public class Game : MonoBehaviour, ThreatDetectedCallback, RASPStatusCallback
{
    void Start()
    {
        var config = new TalsecConfig
        {
            watcherMailAddress = "your_mail@example.com",
            isProd = true,
            androidConfig = new AndroidConfig
            {
                packageName = "com.example.app",
                signingCertificateHashBase64 = new string[] { "your_hash_here" },
                supportedAlternativeStores = new string[] { "com.sec.android.app.samsungapps" }
            },
            iosConfig = new IOSConfig
            {
                appBundleIds = new string[] { "com.example.app" },
                appTeamId = "TEAM ID"
            }
        };

        TalsecPlugin.Instance.setThreatDetectedCallback(this);
        TalsecPlugin.Instance.setRASPStatusCallback(this);
        TalsecPlugin.Instance.initTalsec(config);
    }
}
```

{% endstep %}

{% step %}

### Threat Handling

freeRASP evaluates the device environment and application binary for integrity violations. When a check detects an anomaly, the system triggers the corresponding method within the `ThreatDetectedCallback` interface.

{% hint style="info" %}
**Platform-Specific Callbacks**

The `ThreatDetectedCallback` interface is shared across platforms, but certain checks evaluate OS-specific states:

* **Android-only**: `onMultiInstance`, `onUnsecureWiFi`, `onLocationSpoofing`, `onADBEnabled`, `onObfuscationIssues`
* **iOS-only**: `onPasscodeChange`, `onDeviceID`
  {% endhint %}

```csharp
public void onPrivilegedAccess() 
{ 
    Debug.Log("Unity - Root/Jailbreak detected");
}

public void onAppIntegrity() 
{ 
    Debug.Log("Unity - Tamper detected"); 
}

public void onDebug() 
{ 
    Debug.Log("Unity - Debugger detected"); 
}

public void onSimulator() 
{ 
    Debug.Log("Unity - Emulator/Simulator detected"); 
}

public void onObfuscationIssues() 
{ 
    Debug.Log("Unity - Obfuscation issues detected"); 
}

public void onScreenshot() 
{ 
    Debug.Log("Unity - Screenshot detected"); 
}

public void onScreenRecording() 
{ 
    Debug.Log("Unity - Screen recording detected"); 
}

public void onUnofficialStore() 
{ 
    Debug.Log("Unity - Untrusted installation source detected"); 
}

public void onHooks() 
{ 
    Debug.Log("Unity - Hook detected"); 
}

public void onDeviceBinding() 
{ 
    Debug.Log("Unity - Device binding detected"); 
}

public void onPasscode() 
{ 
    Debug.Log("Unity - Unlocked device detected"); 
}

public void onPasscodeChange() 
{ 
    Debug.Log("Unity - Passcode change detected"); 
}

public void onDeviceID() 
{ 
    Debug.Log("Unity - Device ID detected"); 
}

public void onSecureHardwareNotAvailable() 
{ 
    Debug.Log("Unity - Hardware backed keystore not available"); 
}

public void onDevMode() 
{ 
    Debug.Log("Unity - Developer mode detected"); 
}

public void onADBEnabled() 
{ 
    Debug.Log("Unity - ADB enabled detected"); 
}

public void onSystemVPN() 
{ 
    Debug.Log("Unity - System VPN detected"); 
}

public void onMultiInstance() 
{ 
    Debug.Log("Unity - Multi instance detected"); 
}

public void onUnsecureWiFi() 
{ 
    Debug.Log("Unity - Unsecure WiFi detected"); 
}

public void onTimeSpoofing() 
{ 
    Debug.Log("Unity - Time spoofing detected"); 
}

public void onLocationSpoofing() 
{ 
    Debug.Log("Unity - Location spoofing detected"); 
}
```

{% hint style="info" %}
Your application must implement these callbacks to execute security mitigations. For example, your app can:

* Terminate the application process.
* Restrict access to sensitive views or features.
* Clear locally stored user session data.
* Send a telemetry event to your backend.
  {% endhint %}
  {% endstep %}

{% step %}

### Execution State Handling

freeRASP evaluates security checks in periodic cycles. When the system completes a full scan cycle without interruption, it triggers the `onAllChecksFinished` method within the `RASPStatusCallback` interface.

```csharp
public void onAllChecksFinished()
{
    Debug.Log("Unity - All checks finished");
}
```

{% hint style="info" %}
Your application can use this callback to unblock UI components or log scan completion.
{% endhint %}
{% endstep %}
{% endstepper %}

## Platform-Specific Setup

freeRASP utilizes native Android and iOS libraries to execute runtime security checks. You must configure platform-specific build settings to link these native dependencies correctly. Complete the Android Gradle configurations before compiling your final Android package, and complete the iOS framework setup after exporting your Unity project to Xcode.

### Android Setup

{% stepper %}
{% step %}

### Add Maven Repositories

Define the Talsec Maven repositories in your Gradle configuration to resolve the freeRASP Android dependencies. Add the following to your `settings.gradle` located in your Unity project at `Assets/Plugins/Android/settings.gradle`.&#x20;

```kt
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)

    repositories {
        google()
        mavenCentral()

        maven { url 'https://jitpack.io' }
        maven { url 'https://europe-west3-maven.pkg.dev/talsec-artifact-repository/freerasp' }

        flatDir {
            dirs "${project(':unityLibrary').projectDir}/libs"
        }
    }
}
```

{% endstep %}

{% step %}

### Add Permissions

Some callbacks require additional permissions to function. In your Unity project, locate or create `Assets/Plugins/Android/AndroidManifest.xml` and add the relevant permissions inside the `<manifest>` root tag.

{% hint style="info" %}
Some permissions also require a runtime request from the user.
{% endhint %}

#### Screenshot and Screen Recording Detection

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

{% hint style="info" %}
Screenshot detection requires Android 14 (API level 34) or higher.

Screen Recording detection requires Android 15 (API level 35) or higher.\
\
Application of **FLAG\_SECURE** on Android Window or calling `blockScreenCapture(true)` disables this callback.
{% endhint %}

#### Location Spoofing Detection

```xml
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
```

#### Unsecure WiFi Detection

```xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
```

{% endstep %}
{% endstepper %}

### iOS Setup

{% stepper %}
{% step %}

### Export the Project to Xcode

In Unity, navigate to **File → Build Settings**. Select **iOS** as the target platform and click **Switch Platform**. Then click **Build** to export the project as an Xcode project.
{% endstep %}

{% step %}

### Download the Talsec Framework

Download the native `TalsecRuntime.xcframework` asset from the freeRASP iOS GitHub Releases page.

<p align="center"><a href="https://github.com/talsec/Free-RASP-Unity-POC/releases/download/untagged-e717d71e660b9ca18589/Talsec.freeRASP.-.iOS.6.14.2.zip" class="button primary">Download TalsecRuntime.xcframework</a></p>
{% endstep %}

{% step %}

### Add the Framework to Xcode

Copy the `TalsecRuntime.xcframework` into your Xcode Application folder. Drag and drop the `TalsecRuntime.xcframework` into your `.xcworkspace` tree in Xcode.
{% endstep %}

{% step %}

### Link the Binary

Navigate to **Target -> Build Phases -> Link Binary With Libraries** and add the `TalsecRuntime` framework.
{% endstep %}

{% step %}

### Embed and Sign

Navigate to **General -> Frameworks, Libraries, and Embedded Content** and set the `TalsecRuntime` framework status to Embed & Sign.
{% endstep %}
{% endstepper %}

## 🖥️ 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 %}


---

# 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/unity.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.