/

iOS Configuration API

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

Token Setup

Before configuring protections, set up your ByteHide Project Token. You have three options:

Configure BYTEHIDE_TOKEN in your Xcode scheme:

  1. Edit Scheme > Run > Arguments > Environment Variables
  2. Add: BYTEHIDE_TOKEN = your-project-token

Option B: Info.plist

Add to your Info.plist:

XML
<key>ByteHideMonitor</key>
<dict>
    <key>APIToken</key>
    <string>${BYTEHIDE_TOKEN}</string>
</dict>

Then configure the BYTEHIDE_TOKEN environment variable (same as Option A).

Option C: JSON Configuration File

Include the token in a monitor-config.json file (see JSON Configuration below).

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 token is validated and configuration is embedded
  2. At runtime, Monitor auto-initializes using +load() (before main())
  3. Applies protections configured in your dashboard
  4. Periodically syncs for configuration updates

Setup:

Configure your token (see above) and build:

Bash
xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release

No code changes needed. Monitor initializes automatically.

Option B: JSON Configuration

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

Create monitor-config.json in your project root:

JSON
{
  "apiToken": "bh_YourToken",
  "logLevel": "info",
  "enableConsoleLogs": true,
  "enableFileLogs": false,
  "protections": [
    {
      "type": "DebuggerDetection",
      "action": "close",
      "intervalMs": 5000
    },
    {
      "type": "JailbreakDetection",
      "action": "close",
      "intervalMs": 5000
    },
    {
      "type": "SimulatorDetection",
      "action": "log",
      "intervalMs": 5000
    },
    {
      "type": "ClockTampering",
      "action": "log",
      "intervalMs": 5000
    },
    {
      "type": "MemoryDumpDetection",
      "action": "close",
      "intervalMs": 5000
    },
    {
      "type": "ProcessInjection",
      "action": "close",
      "intervalMs": 5000
    }
  ]
}

Monitor loads this file automatically. No code required.

Option C: Programmatic Configuration

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

Swift

Swift
import ByteHideMonitor

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions:
                       [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        BHMMonitor.configure { config in
            // Token (optional if already embedded)
            config.useToken("bh_YourToken")

            // Set log level
            config.logLevel(.info)

            // Register a custom action
            config.registerCustomAction("notify") { threat in
                print("ALERT: \(threat.threatDescription ?? "Unknown threat")")
                // Send notification, log to analytics, etc.
            }

            // Enable all protections with a default action
            config.enableAllProtections(.log, intervalMs: 5000)

            // Or configure individual protections
            config.enableProtection(.debuggerDetection, action: .close, intervalMs: 5000)
            config.enableProtection(.jailbreakDetection, customAction: "notify", intervalMs: 5000)
        }

        return true
    }
}

Objective-C

OBJC
#import <ByteHideMonitor/ByteHideMonitor.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [BHMMonitor configure:^(BHMMonitorConfiguration *config) {
        // Token
        [config useToken:@"bh_YourToken"];

        // Set log level
        [config logLevel:BHMLogLevelInfo];

        // Register a custom action
        [config registerCustomAction:@"notify" handler:^(BHMThreatContext *threat) {
            NSLog(@"ALERT: %@", threat.threatDescription);
        }];

        // Enable all protections
        [config enableAllProtections:BHMActionTypeLog intervalMs:5000];

        // Or configure individual protections
        [config enableProtection:BHMProtectionModuleTypeDebuggerDetection
                         action:BHMActionTypeClose
                     intervalMs:60000];
    }];

    return YES;
}

@end

Available Action Types

TypeDescriptionRecommended Use
noneDetect only, take no actionTesting, initial analysis
logLog the incidentProduction monitoring
closeClose the application immediatelyMaximum security
eraseWipe sensitive data and closeCritical data (finance, health)
customExecute your custom handlerBusiness-specific logic

Combine cloud/JSON configuration with programmatic overrides:

Swift
BHMMonitor.configure { config in
    // Base config is already loaded from cloud or monitor-config.json

    // Override only what you need
    config.registerCustomAction("criticalAlert") { threat in
        sendPushNotification("Security Alert", threat.threatDescription ?? "Unknown threat")
        exit(1)
    }

    // Add extra protection with custom action
    config.enableProtection(.memoryDumpDetection, customAction: "criticalAlert", intervalMs: 60000)
}

Configuration loading order:

  1. Monitor loads from monitor-config.json (if present in bundle)
  2. If no JSON file, fetches configuration from cloud (dashboard)
  3. Applies programmatic configuration (if Monitor.configure is called)
  4. Programmatic configuration overrides automatic configuration

Auto-Initialization

Monitor for iOS auto-initializes automatically using the Objective-C +load() method, which executes before main().

How it works:

  • During build: The token is validated and configuration is embedded in the app bundle
  • During execution: Monitor initializes automatically before your code runs, validating the app signature and activating configured protections

No additional code is required unless you use Option C (programmatic configuration).

Previous
JSON Configuration
Next
Logging