/

Android Gradle Setup

Install ByteHide Monitor in your Android project using the Gradle plugin. The plugin is required for Android: it signs and embeds the protection configuration at build time and generates the initialization code automatically.

Requirements

RequirementMinimumRecommended
Android Gradle Plugin7.08.0+
Java1117
Kotlin (if used)1.61.9+
Gradle7.48.0+
minSdk2121

Step 1: Configure Repositories

The plugin is published on Maven Central. Add the standard repositories to your settings.gradle.kts:

Kotlin
// settings.gradle.kts
pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
        google()
    }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}

Repository configuration in settings.gradle.ktsClick to expand

Step 2: Apply the Plugin

Add the Monitor plugin to your app module's build.gradle.kts:

Kotlin
// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("com.bytehide.monitor") version "1.0.1"
}

The plugin automatically adds com.bytehide:monitor-core:1.0.1 as an implementation dependency. No manual dependency needed.

Step 3: Configure the Plugin

Add the monitor block with your project token:

Kotlin
monitor {
    projectToken = "bh_xxxxxxxxxxxx"
}

That's it for a minimal setup. The plugin uses sensible defaults for everything else.

Using a Preset

Presets enable a predefined group of protection modules:

Kotlin
monitor {
    projectToken = "bh_xxxxxxxxxxxx"
    preset = "mobile"
}

  • mobile - Enables Debugger Detection, Clock Tampering, and Jailbreak Detection. Safe baseline for most Android apps.

  • desktop - Everything in mobile plus VM Detection, Emulator Detection, Memory Dump Detection, and License Binding. For desktop JVM apps.

  • null (default) - Uses individual enable* flags as-is. Full manual control.

When using a preset, individual enable* flags set after the preset override it.

Manual Configuration

For full control, configure each protection module individually:

Kotlin
monitor {
    projectToken = "bh_xxxxxxxxxxxx"

    enableDebuggerDetection = true
    enableClockTampering = true
    enableJailbreakDetection = true
    enableVirtualMachineDetection = true
    enableEmulatorDetection = true
    enableMemoryDumpDetection = false
    enableProcessInjection = false
    enableNetworkTampering = false
    enableLicenseBinding = true
    enableTamperingDetection = false
    enableContainerDetection = false
    enableRemoteDesktop = false
    enableCloudMetadata = false

    defaultAction = "log"
    defaultIntervalMs = 30000
}

Monitor Gradle plugin configuration in Android StudioClick to expand

Protection Modules

PropertyTypeDefaultDescription
enableDebuggerDetectionBooleantrueDetect attached debuggers (ADB, JDWP, ptrace)
enableClockTamperingBooleantrueDetect system clock manipulation
enableJailbreakDetectionBooleantrueDetect root/jailbreak (Magisk, SuperSU, Xposed)
enableVirtualMachineDetectionBooleantrueDetect VM environments (VMware, VirtualBox, QEMU)
enableEmulatorDetectionBooleantrueDetect Android emulators (Genymotion, AVD, BlueStacks)
enableMemoryDumpDetectionBooleanfalseDetect memory dumping tools (Frida, Objection)
enableProcessInjectionBooleanfalseDetect process injection attacks
enableNetworkTamperingBooleanfalseDetect MITM proxies, VPNs, SSL interception
enableLicenseBindingBooleantrueValidate license binding to device
enableTamperingDetectionBooleanfalseDetect file/code integrity violations
enableContainerDetectionBooleanfalseDetect Docker, Kubernetes, LXC
enableRemoteDesktopBooleanfalseDetect remote desktop sessions
enableCloudMetadataBooleanfalseDetect cloud metadata endpoints

Behavior

PropertyTypeDefaultDescription
defaultActionString"log"Action when a threat is detected: "log", "close", "erase"
defaultIntervalMsInt30000Detection check interval in milliseconds

Token Resolution

The project token is resolved in priority order:

PrioritySourceExample
1monitor {} DSLprojectToken = "bh_xxx"
2Environment variableBYTEHIDE_API_TOKEN=bh_xxx
3local.propertiesbytehide.api.token=bh_xxx

For teams, use local.properties (already in .gitignore) or an environment variable so the token is never committed.

What the Plugin Does at Build Time

When you run ./gradlew assembleDebug (or any build), the plugin:

  1. Signs the assembly to protect the APK against tampering
  2. Generates a ContentProvider that auto-initializes Monitor when the app starts
  3. Registers the provider in AndroidManifest.xml
  4. Adds INTERNET permission if not already present
  5. Embeds encrypted configuration with your protection settings

All of this happens automatically. No code changes required for basic protection.

Step 4: Build and Verify

Run a build:

Bash
./gradlew assembleDebug

When the build runs successfully, you'll see:

CODE
Configuring ByteHide Monitor...
  API Token: bh_POlhU6...
  Package: com.example.myapp
  Generating MonitorContentProvider...
  Registering provider in AndroidManifest.xml...
  Signing assembly...
  Embedding encrypted resources...
ByteHide Monitor configured successfully

At runtime, filter Logcat by tag ByteHideMonitor to confirm Monitor is running:

CODE
I/ByteHideMonitor: [I001_INIT_START] MonitorLogger initialized with 2 sinks
I/ByteHideMonitor: [I002_INIT_SUCCESS] ByteHideMonitor initialization complete
I/ByteHideMonitor: [I010_API_CONNECTED] Registering device...

ProGuard / R8

The library ships consumer ProGuard rules automatically. No extra configuration needed.

Package Name Detection

The plugin auto-detects your package name from android.namespace or applicationId. If auto-detection fails, set it explicitly:

Kotlin
monitor {
    packageName = "com.example.myapp"
}

Next Steps

Previous
Quick Start
Next
CI/CD