@capgo/capacitor-mock-location-detector

Detect fake GPS and location spoofing in your Capacitor app with layered, App Store safe checks on iOS and Android. Protect check-ins, deliveries and location-based rewards.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-mock-location-detector in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-mock-location-detector to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Full analysis: analyze() returns isSimulated, a confidence level, a riskScore and the triggered checks.
• Single checks: runCheck() for the mock flag, mock location apps, developer options, ADB, simulator, location anomalies and motion correlation.
• Monitoring: startMonitoring() and the locationIntegrityChanged event when the verdict changes.
• Capabilities: getCapabilities() lists the checks the platform supports.
• Developer settings: openDeveloperSettings() on Android.
• Platforms: iOS and Android. Not available on web.

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

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

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>

Returns: Promise<LocationIntegrityResult>

runCheck(...)

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

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.

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.

Returns: Promise<PluginListenerHandle>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns: Promise<PluginVersionResult>

Interfaces

MockLocationDetectorCapabilities

LocationIntegrityResult

LocationCheckResult

DeveloperModeResult

LocationSample

AnalyzeOptions

RunCheckOptions

MonitoringOptions

PluginListenerHandle

LocationIntegrityChangedEvent

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

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

PluginVersionResult

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'