/

Android Configuration API

Monitor offers three configuration options for Android: Cloud (zero-config), JSON file, and Programmatic API. You can also combine them for a hybrid approach.

Configuration Options Overview

OptionBest ForCode RequiredOffline Support
Cloud (Zero-Config)Most projectsNoneNo (fetches from API)
JSON FileOffline / auditable configNoneYes
Programmatic APICustom actions / dynamic logicYesYes

Option A: Cloud Configuration (Zero-Config)

The simplest approach. Monitor fetches its configuration automatically from your ByteHide dashboard.

How it works:

  1. During build, the Gradle plugin embeds your token in the APK
  2. At runtime, Monitor connects to the ByteHide API
  3. Downloads the active configuration from your dashboard
  4. Applies the configured protections
  5. Periodically syncs for hot updates (no rebuild needed)

Setup:

Set your token as an environment variable and build:

Bash
export BYTEHIDE_API_TOKEN="your-token-here"
./gradlew assembleRelease

No code changes needed. Monitor initializes automatically.

Gradle Plugin Options

You can configure the Gradle plugin in your build.gradle.kts:

Kotlin
bytehideMonitor {
    apiToken = "your-token-here"        // Or use BYTEHIDE_API_TOKEN env var
    enableConfig = true                  // Download cloud config (default: true)
    failOnLicenseError = true            // Fail build on license issues (default: true)
    verbose = false                      // Enable verbose logging (default: false)
}

The token is resolved in this order: explicit apiToken > BYTEHIDE_API_TOKEN environment variable > bytehide.api.token system property.

Option B: JSON Configuration

Define protections locally in a JSON file. Ideal for offline environments or when you need version-controlled configuration.

Create monitor-config.json in src/main/assets/:

JSON
{
  "projectToken": "your-token-here",
  "logging": {
    "level": "info",
    "console": true,
    "file": {
      "enabled": true,
      "path": "logs/monitor.log"
    }
  },
  "protections": [
    {
      "type": "DebuggerDetection",
      "enabled": true,
      "action": "close"
    },
    {
      "type": "JailbreakDetection",
      "enabled": true,
      "action": "close"
    },
    {
      "type": "EmulatorDetection",
      "enabled": true,
      "action": "log"
    },
    {
      "type": "ClockTampering",
      "enabled": true,
      "action": "log"
    },
    {
      "type": "MemoryDumpDetection",
      "enabled": true,
      "action": "close"
    },
    {
      "type": "VirtualMachineDetection",
      "enabled": true,
      "action": "close"
    },
    {
      "type": "ProcessInjection",
      "enabled": true,
      "action": "close"
    },
    {
      "type": "NetworkTampering",
      "enabled": true,
      "action": "log"
    },
    {
      "type": "ContainerDetection",
      "enabled": true,
      "action": "log"
    },
    {
      "type": "RemoteDesktop",
      "enabled": true,
      "action": "log"
    },
    {
      "type": "LicenseBinding",
      "enabled": true,
      "action": "close"
    },
    {
      "type": "CloudMetadata",
      "enabled": true,
      "action": "log"
    }
  ]
}

Monitor loads this file automatically. No code required.

Available On-Premise Modules

See all 13 available protection modules in the Protection Modules page. All modules work on both mobile and desktop platforms.

Option C: Programmatic Configuration

Configure Monitor directly in code for maximum control, custom actions, and dynamic logic.

Kotlin

Kotlin
import android.app.Application
import com.bytehide.monitor.Monitor
import com.bytehide.monitor.core.action.ActionType
import com.bytehide.monitor.core.protection.ProtectionModuleType
import com.bytehide.monitor.core.logging.LogLevel
import android.util.Log

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Monitor.configure { config ->
            // Token (optional if already embedded via Gradle)
            config.useToken("bh_YourTokenHere")

            // Register a custom action
            config.registerCustomAction("notify") { threat ->
                Log.w("ByteHideMonitor", "ALERT: ${threat.description}")
                // Send notification, log to analytics, alert backend, etc.
            }

            // Configure logging
            config.configureLogging { logging ->
                logging.enableConsole()
                logging.enableFileLogging("monitor.log")
                logging.setMinimumLevel(LogLevel.INFO)
            }

            // Enable all on-premise protections with a default action
            config.enableAllProtections(ActionType.CUSTOM, 60000)

            // Or configure individual protections
            config.addProtection(
                ProtectionModuleType.DEBUGGER_DETECTION,
                ActionType.CLOSE,
                60000
            )

            config.addProtection(
                ProtectionModuleType.JAILBREAK_DETECTION,
                "notify",  // Use custom action
                60000
            )
        }
    }

    override fun onTerminate() {
        super.onTerminate()
        Monitor.shutdown()
    }
}

Java

Java
import android.app.Application;
import com.bytehide.monitor.Monitor;
import com.bytehide.monitor.core.action.ActionType;
import com.bytehide.monitor.core.protection.ProtectionModuleType;
import android.util.Log;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        Monitor.configure(config -> {
            // Token (optional if already embedded via Gradle)
            config.useToken("bh_YourTokenHere");

            // Register a custom action
            config.registerCustomAction("notify", threat -> {
                Log.w("ByteHideMonitor", "ALERT: " + threat.getDescription());
            });

            // Enable all on-premise protections
            config.enableAllProtections(ActionType.CUSTOM, 60000);

            // Or configure individual protections
            config.addProtection(
                ProtectionModuleType.DEBUGGER_DETECTION,
                ActionType.CLOSE,
                60000
            );
        });
    }

    @Override
    public void onTerminate() {
        super.onTerminate();
        Monitor.shutdown();
    }
}

Register your Application class in AndroidManifest.xml:

XML
<application android:name=".MyApplication">
    <!-- your activities -->
</application>

Available Action Types

TypeDescriptionRecommended Use
NONEDetect only, take no actionTesting, initial analysis
LOGLog the incidentProduction monitoring
BLOCKBlock the request or operationCloud / web API protection
CLOSEClose the application immediatelyMaximum security
ERASEWipe sensitive data and closeCritical data (finance, health)
CUSTOMExecute your custom handlerBusiness-specific logic

Custom Action Example

Kotlin
config.registerCustomAction("myAction") { threat ->
    // 1. Log the incident
    analytics.trackSecurityThreat(threat.threatType, threat.description)

    // 2. Notify the user
    showSecurityWarning(threat.description)

    // 3. Alert the backend
    securityApi.reportThreat(threat)

    // 4. Take action based on confidence
    when (threat.confidence) {
        in 0.8..1.0 -> {
            // High confidence: close app
            exitProcess(1)
        }
        in 0.5..0.8 -> {
            // Medium confidence: limit functionality
            disableSensitiveFeatures()
        }
        else -> {
            // Low confidence: log only
            Log.i("Security", "Possible threat: ${threat.description}")
        }
    }
}

Combine cloud/JSON configuration with programmatic overrides for maximum flexibility:

Kotlin
Monitor.configure { config ->
    // Base config is already loaded from cloud or monitor-config.json

    // Override only what you need
    config.registerCustomAction("criticalAlert") { threat ->
        sendPushNotification("Security Alert", threat.description)
        exitProcess(1)
    }

    // Add extra protection with custom action
    config.addProtection(
        ProtectionModuleType.MEMORY_DUMP_DETECTION,
        "criticalAlert",
        60000
    )
}

Configuration loading order:

  1. Embedded encrypted configuration (injected by Gradle plugin from cloud)
  2. Plain monitor-config.json in assets (for development / offline)
  3. Programmatic configuration via Monitor.configure (overrides the above)

Cloud protection modules

The Java SDK currently supports on-premise protection modules (mobile and desktop). Cloud protection modules (SQL Injection, XSS, Path Traversal, etc.) for web API monitoring will be available soon.

Previous
JSON Configuration
Next
Logging