@capgo/capacitor-mock-location-detector

Detect simulated GPS locations using layered, App Store-safe checks on iOS and Android.

Snapshot

• Plugin name: @capgo/capacitor-mock-location-detector
• One-line value: Multi-layer GPS spoofing and developer tooling detection for Capacitor apps
• Maintainer: Capgo
• Status: beta

Problem & Scope

Why this plugin exists

Tools like PoKeep and iMyFone AnyTo can spoof device location. A single flag such as iOS isSimulatedBySoftware is not reliable against every spoofing method. This plugin combines multiple independent signals so your app can make better fraud-prevention decisions.

What it does

• Runs layered checks: system mock flags, developer options, known mock apps, movement heuristics, and motion correlation
• Returns a scored LocationIntegrityResult with per-check details
• Supports continuous monitoring with locationIntegrityChanged events
• Opens the best-effort settings screen so users can disable developer/mock tooling themselves

What it does not do

• Cannot programmatically disable Developer Mode or mock location settings (not allowed by iOS/Android)
• Cannot guarantee 100% detection against every future spoofing tool
• On iOS, Apple provides no public API to read the Developer Mode toggle directly

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | On demand |

Install

npm install @capgo/capacitor-mock-location-detector
npx cap sync

Setup

iOS

Add location usage descriptions to your app Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We verify your location has not been spoofed.</string>

Optional: declare URL schemes for companion spoof apps you want to detect:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>anyto</string>
  <string>fakegps</string>
</array>

Android

Ensure your app requests runtime location permissions. The plugin declares coarse/fine location permissions in its manifest merge.

Usage

import { MockLocationDetector } from '@capgo/capacitor-mock-location-detector';

const result = await MockLocationDetector.analyze({
  requestLocationSample: true,
  minDetectedChecks: 1,
});

if (result.isSimulated) {
  console.warn('Possible GPS spoofing detected', result.checks);
}

// Guide the user — apps cannot disable developer mode automatically
await MockLocationDetector.openDeveloperSettings();

Run a single check layer:

const mockFlag = await MockLocationDetector.runCheck({
  check: 'system_mock_flag',
});

Start monitoring:

await MockLocationDetector.addListener('locationIntegrityChanged', (event) => {
  console.log('Integrity changed', event.riskScore, event.checks);
});

await MockLocationDetector.startMonitoring({ intervalMs: 30000 });

Check layers

| Check ID | iOS | Android | Description | | --- | --- | --- | --- | | system_mock_flag | ✅ | ✅ | OS mock/simulation flag on the current location fix | | developer_options | — | ✅ | Android developer options enabled | | developer_mode_indicators | ✅ | ✅ | Indirect developer/debug build heuristics | | mock_location_app | ✅ | ✅ | Known spoof app packages / URL schemes | | adb_enabled | — | ✅ | USB debugging enabled | | mock_provider_settings | — | ✅ | Apps granted mock-location permission | | location_anomaly | ✅ | ✅ | Impossible movement speed / teleport heuristic | | motion_correlation | ✅ | — | GPS movement without matching accelerometer activity | | simulator | ✅ | ✅ | Simulator/emulator environment |

Capgo Links

• Plugin docs URL: https://capgo.app/docs/plugins/mock-location-detector/
• Website/docs repo: https://github.com/Cap-go/website

• getCapabilities()
• analyze(...)
• runCheck(...)
• openDeveloperSettings()
• startMonitoring(...)
• stopMonitoring()
• addListener('locationIntegrityChanged', ...)
• getPluginVersion()
• Interfaces
• Type Aliases

Detect simulated GPS locations and developer tooling that commonly enables spoofing apps.

This plugin combines multiple independent checks because no single OS flag is reliable against tools such as PoKeep or iMyFone AnyTo. On iOS, Apple does not provide a public API to read the Developer Mode toggle directly; the plugin uses App Store-safe heuristics instead.

Apps cannot programmatically disable Developer Mode or mock location settings. Use {@link MockLocationDetectorPlugin.openDeveloperSettings} to guide users to the relevant settings.

getCapabilities()

getCapabilities() => Promise<MockLocationDetectorCapabilities>

Returns: Promise<MockLocationDetectorCapabilities>

analyze(...)

analyze(options?: AnalyzeOptions | undefined) => Promise<LocationIntegrityResult>

| Param | Type | | ------------- | --------------------------------------------------------- | | options | AnalyzeOptions |

Returns: Promise<LocationIntegrityResult>

runCheck(...)

runCheck(options: RunCheckOptions) => Promise<LocationCheckResult>

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | RunCheckOptions |

Returns: Promise<LocationCheckResult>

openDeveloperSettings()

openDeveloperSettings() => Promise<void>

startMonitoring(...)

startMonitoring(options?: MonitoringOptions | undefined) => Promise<void>

Start background integrity monitoring on native platforms.

Pair with {@link MockLocationDetectorPlugin.addListener} to receive locationIntegrityChanged events while the app is in the foreground.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | MonitoringOptions |

stopMonitoring()

stopMonitoring() => Promise<void>

Stop monitoring and release native location listeners.

addListener('locationIntegrityChanged', ...)

addListener(eventName: 'locationIntegrityChanged', listenerFunc: (event: LocationIntegrityChangedEvent) => void) => Promise<PluginListenerHandle>

Listen for integrity updates while {@link MockLocationDetectorPlugin.startMonitoring} is active.

| Param | Type | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | | eventName | 'locationIntegrityChanged' | Must be 'locationIntegrityChanged'. | | listenerFunc | (event: LocationIntegrityChangedEvent) => void | |

Returns: Promise<PluginListenerHandle>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns: Promise<PluginVersionResult>

Interfaces

MockLocationDetectorCapabilities

| Prop | Type | | ------------------------------ | ------------------------------------------------------------------------------- | | platform | LocationIntegrityPlatform | | availableChecks | LocationCheckId[] | | supportsMonitoring | boolean | | canOpenDeveloperSettings | boolean |

LocationIntegrityResult

| Prop | Type | | -------------------- | ----------------------------------------------------------------------------------- | | isSimulated | boolean | | confidence | LocationIntegrityConfidence | | riskScore | number | | platform | LocationIntegrityPlatform | | checks | LocationCheckResult[] | | developerMode | DeveloperModeResult | | locationSample | LocationSample | null | | recommendation | string |

LocationCheckResult

| Prop | Type | | --------------- | ------------------------------------------------------------------------------- | | id | LocationCheckId | | name | string | | platform | LocationIntegrityPlatform | | available | boolean | | detected | boolean | | message | string | | metadata | { [key: string]: unknown; } |

DeveloperModeResult

| Prop | Type | | ---------------------------- | ---------------------------------- | | detected | boolean | | canDetectDeveloperMode | boolean | | checks | LocationCheckResult[] |

LocationSample

| Prop | Type | | --------------- | ------------------- | | latitude | number | | longitude | number | | accuracy | number | | altitude | number | | speed | number | | timestamp | number |

AnalyzeOptions

| Prop | Type | | --------------------------------- | ------------------------------ | | checks | LocationCheckId[] | | requestLocationSample | boolean | | locationTimeoutMs | number | | minDetectedChecks | number | | additionalMockAppPackages | string[] | | additionalMockAppUrlSchemes | string[] |

RunCheckOptions

| Prop | Type | | ----------- | ----------------------------------------------------------- | | check | LocationCheckId |

MonitoringOptions

| Prop | Type | Description | Default | | ---------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | intervalMs | number | How often to re-run checks while monitoring is active. Minimum 5000 ms. Defaults to 30000. | 30000 | | emitOnlyOnChange | boolean | When true, locationIntegrityChanged is emitted only when isSimulated, confidence, riskScore, or triggered check IDs change. The first event after {@link MockLocationDetectorPlugin.startMonitoring} always fires. | true |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

LocationIntegrityChangedEvent

Payload emitted by {@link MockLocationDetectorPlugin.addListener} when monitoring detects a new integrity snapshot.

Register the listener before calling {@link MockLocationDetectorPlugin.startMonitoring}:

| Prop | Type | Description | | ------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | reason | 'interval' | 'location_update' | 'manual' | Why this snapshot was emitted. - manual — first snapshot right after monitoring starts - interval — periodic re-check (intervalMs) - location_update — device location changed while monitoring (native only) |

PluginVersionResult

| Prop | Type | | ------------- | ------------------- | | version | string |

Type Aliases

LocationIntegrityPlatform

'ios' | 'android' | 'web'

LocationCheckId

Individual integrity checks exposed by the plugin.

'system_mock_flag' | 'developer_options' | 'developer_mode_indicators' | 'mock_location_app' | 'adb_enabled' | 'mock_provider_settings' | 'location_anomaly' | 'motion_correlation' | 'simulator'

LocationIntegrityConfidence

'none' | 'low' | 'medium' | 'high'