Debug Mode

Enable debug mode during development to see verbose native logs, hear system sounds on key events, and receive onDebug events in JavaScript.

Enable Debug Mode

Set debug: true in your configuration. Optionally enable debugSounds: true for audio feedback.

import { addListener, configure, start } from '@bglocation/react-native';

await configure({
  distanceFilter: 15,
  desiredAccuracy: 'high',
  heartbeatInterval: 15,
  debug: true,         // enable verbose logs
  debugSounds: true,   // play system sounds on events (iOS)
});

// Listen for debug messages
addListener('onDebug', (event) => {
  console.log(`[DEBUG ${new Date(event.timestamp).toISOString()}] ${event.message}`);
});

await start();

What Debug Mode Does

Feature	iOS	Android
Verbose native logs	os_log (visible in Console.app)	Logcat (filter: BGLocation)
onDebug events to JS	Yes	Yes
System sounds	When debugSounds: true	When debugSounds: true
Dynamic notification	N/A (blue pill indicator)	Coordinates, counters, status in notification

DebugEvent Interface

interface DebugEvent {
  message: string;     // debug log message
  timestamp: number;   // epoch milliseconds
}

Physical Device vs Simulator

Physical Device

Real GPS hardware — actual coordinates and speed
Background execution behaves as in production
Battery optimization and Foreground Service work normally
Required for production-level testing

Simulator / Emulator

iOS Simulator: use Debug > Location > Custom Location or GPX files
Android Emulator: use extended controls > Location
Background behavior may differ from real devices
Useful for API flow testing, not for GPS accuracy testing

Trial Mode Forces Debug

In trial mode (no license key), debug is forced to true automatically so you can inspect plugin behavior while evaluating.

Disable Before Release

Always set debug: false (or omit it) in production builds. Debug mode increases battery consumption, generates excessive logs, and may expose internal information in the notification.