Package Exports
- expo-geofencing
- expo-geofencing/build/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (expo-geofencing) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
π§ Expo Geofencing
Production-ready geofencing and activity recognition for Expo React Native with enterprise-grade features including offline support, security, health monitoring, and comprehensive analytics.
β¨ Features
π§ Advanced Geofencing
- Circular & Polygon Geofences: Support for complex shaped regions
- Time-Based Activation: Geofences active only during specific hours/days
- Conditional Rules: Weather, traffic, or custom condition-based triggers
- Hierarchical Geofences: Parent-child relationships with inheritance
- Spatial Indexing: Optimized for thousands of geofences
π Activity Recognition
- Motion Detection: Still, walking, running, driving, cycling
- Confidence Levels: High-accuracy activity classification
- Configurable Intervals: Customizable detection frequency
β‘ Power-Efficient Location
- FusedLocationProvider: Battery-optimized on Android
- Adaptive Accuracy: Dynamic GPS precision based on context
- Background Optimization: Minimal battery impact
π Production-Ready Reliability
- Battery Optimization Handling: Device-specific power management
- Health Monitoring: Continuous service monitoring with alerts
- App Persistence: Anti-kill mechanisms and automatic recovery
- Silent Notifications: Background health checks every 5 minutes
π Offline & Network Recovery
- Offline Geofence Evaluation: Works without internet connectivity
- Event Queuing: Automatic sync when network returns
- Intelligent Batching: Bandwidth optimization
- Retry Logic: Exponential backoff with failure recovery
π Security & Privacy
- End-to-End Encryption: AES encryption for sensitive data
- Privacy Zones: Automatic exclusion of hospitals, government buildings
- Data Anonymization: Differential privacy and precision reduction
- Audit Logging: Immutable trail with integrity verification
π Enterprise Features
- Real-time Webhooks: Instant notifications to external systems
- Analytics & Reporting: Comprehensive insights and data export
- Compliance Ready: GDPR/CCPA compliant with consent management
- Performance Monitoring: System health and delivery statistics
π Quick Start
Installation
npm install expo-geofencingPlugin Configuration
Add the plugin to your app.json or app.config.js:
{
\"expo\": {
\"plugins\": [\"expo-geofencing/plugin\"]
}
}Basic Usage
import ExpoGeofencing from 'expo-geofencing';
import * as Location from 'expo-location';
// Request permissions
await Location.requestForegroundPermissionsAsync();
await Location.requestBackgroundPermissionsAsync();
// Add a geofence
await ExpoGeofencing.addGeofence({
id: 'home',
latitude: 37.7749,
longitude: -122.4194,
radius: 100,
notifyOnEntry: true,
notifyOnExit: true,
});
// Listen for events
const unsubscribe = ExpoGeofencing.addGeofenceListener((event) => {
console.log(`${event.eventType} region: ${event.regionId}`);
});
// Start monitoring with health checks
await ExpoGeofencing.setHealthCheckInterval(5 * 60 * 1000); // 5 minutesπ± Advanced Features
π Battery Optimization (Android)
// Check if battery optimization is enabled
const status = await ExpoGeofencing.checkBatteryOptimization();
if (status.isBatteryOptimized) {
// Show device-specific instructions
console.log(status.deviceInstructions);
// Request to disable optimization
await ExpoGeofencing.requestBatteryOptimizationDisable();
}π₯ Health Monitoring
// Listen for health alerts
ExpoGeofencing.addHealthAlertListener((alert) => {
console.log(`Health Alert: ${alert.title}`);
if (alert.title.includes('Permission Denied')) {
// Handle permission issues
}
});
// Force location check for testing
const location = await ExpoGeofencing.forceLocationCheck();πΊοΈ Polygon Geofences
import { PolygonGeofenceManager } from 'expo-geofencing';
const polygonManager = new PolygonGeofenceManager();
// Add complex shaped geofence
polygonManager.addGeofence({
id: 'shopping-center',
type: 'polygon',
vertices: [
{ latitude: 37.7749, longitude: -122.4194 },
{ latitude: 37.7759, longitude: -122.4184 },
{ latitude: 37.7739, longitude: -122.4174 }
],
notifyOnEntry: true,
notifyOnExit: true,
timeRules: [{
id: 'business-hours',
startTime: '09:00',
endTime: '17:00',
daysOfWeek: [1, 2, 3, 4, 5], // Monday-Friday
isActive: true
}]
});π Offline Support
import { OfflineManager } from 'expo-geofencing';
const offlineManager = new OfflineManager();
// Add geofences for offline evaluation
offlineManager.addGeofence(geofenceRegion);
// Evaluate location even when offline
const events = offlineManager.evaluateLocation({
latitude: 37.7749,
longitude: -122.4194,
accuracy: 10,
timestamp: Date.now()
});
// Sync when network returns
await offlineManager.syncPendingEvents();π Webhooks Integration
import { WebhookManager } from 'expo-geofencing';
const webhookManager = new WebhookManager();
// Add webhook for real-time notifications
webhookManager.addWebhook({
name: 'Geofence Alerts',
url: 'https://api.example.com/webhooks/geofence',
method: 'POST',
events: ['geofence.enter', 'geofence.exit'],
authConfig: {
type: 'bearer',
credentials: { token: 'your-api-token' }
},
retryConfig: {
maxRetries: 3,
backoffStrategy: 'exponential'
}
});π Analytics & Data Management
import { DataManager } from 'expo-geofencing';
const dataManager = new DataManager({
encryptData: true,
retentionDays: 30,
anonymizeData: true
});
// Generate analytics
const analytics = await dataManager.generateAnalytics();
console.log('Total events:', analytics.summary.totalEvents);
// Export data for compliance
const csvData = await dataManager.exportData('csv', {
start: Date.now() - 30 * 24 * 60 * 60 * 1000, // Last 30 days
end: Date.now()
});π Security & Privacy
import { SecurityManager } from 'expo-geofencing';
const securityManager = new SecurityManager({
encryptionEnabled: true,
privacyZonesEnabled: true,
dataAnonymization: true
});
// Add privacy zone around hospital
securityManager.addPrivacyZone({
name: 'Hospital Privacy Zone',
type: 'hospital',
center: { latitude: 37.7749, longitude: -122.4194 },
radius: 200,
bufferZone: 50
});
// Process location with privacy protection
const result = securityManager.processLocation({
latitude: 37.7749,
longitude: -122.4194,
accuracy: 10
});π οΈ API Reference
Core Methods
// Geofence Management
addGeofence(region: GeofenceRegion): Promise<void>
removeGeofence(regionId: string): Promise<void>
removeAllGeofences(): Promise<void>
// Activity Recognition
startActivityRecognition(intervalMs: number): Promise<void>
stopActivityRecognition(): Promise<void>
// Location Updates
startLocationUpdates(options: LocationUpdateOptions): Promise<void>
stopLocationUpdates(): Promise<void>
// Event Listeners
addGeofenceListener(callback: (event: GeofenceEvent) => void): () => void
addActivityListener(callback: (result: ActivityRecognitionResult) => void): () => void
addHealthAlertListener(callback: (alert: HealthAlert) => void): () => void
// Health & Monitoring
setHealthCheckInterval(intervalMs: number): Promise<void>
forceLocationCheck(): Promise<LocationData>
getServiceStatus(): Promise<SystemStatus>
// Android-specific
checkBatteryOptimization(): Promise<BatteryOptimizationStatus>
requestBatteryOptimizationDisable(): Promise<boolean>
openLocationSettings(): Promise<void>
// iOS-specific
checkSystemStatus(): Promise<SystemStatus>
requestPermissions(): Promise<boolean>TypeScript Interfaces
interface GeofenceRegion {
id: string;
latitude: number;
longitude: number;
radius: number;
notifyOnEntry: boolean;
notifyOnExit: boolean;
}
interface ActivityRecognitionResult {
activity: 'still' | 'walking' | 'running' | 'driving' | 'cycling' | 'unknown';
confidence: number;
timestamp: number;
}
interface GeofenceEvent {
regionId: string;
eventType: 'enter' | 'exit';
timestamp: number;
latitude: number;
longitude: number;
}
interface HealthAlert {
type: string;
title: string;
message: string;
timestamp: number;
severity: 'low' | 'medium' | 'high' | 'critical';
}π Requirements
- Expo SDK: 49.0.0+
- React Native: 0.72.0+
- Node.js: 16.0.0+
- Android: API level 21+ (Android 5.0+)
- iOS: iOS 13.0+
π Permissions
Android
ACCESS_FINE_LOCATION: Location-based featuresACCESS_BACKGROUND_LOCATION: Background geofencingACTIVITY_RECOGNITION: Activity detectionWAKE_LOCK: Background processingFOREGROUND_SERVICE: Persistent monitoring
iOS
NSLocationWhenInUseUsageDescription: Location accessNSLocationAlwaysAndWhenInUseUsageDescription: Background locationNSMotionUsageDescription: Activity recognition- Background mode:
locationfor background geofencing
ποΈ Platform Support
- β Android: Full support using Google Play Services
- β iOS: Full support using Core Location and Core Motion
- β Web: Not supported (native services required)
π Documentation
π― Use Cases
Healthcare
- HIPAA-compliant patient tracking
- Hospital privacy zones
- Emergency response geofencing
Retail & Marketing
- Store entry/exit tracking
- Promotional campaign triggers
- Customer analytics
Logistics & Fleet
- Vehicle tracking with offline capability
- Route optimization
- Delivery confirmation
Smart Cities
- Public transportation alerts
- Environmental monitoring
- Emergency services coordination
Security & Compliance
- Restricted area monitoring
- Audit trail generation
- Regulatory compliance reporting
π§ Troubleshooting
Android Issues
Geofencing not working
- Ensure Google Play Services is installed
- Check battery optimization settings
- Verify location permissions
App getting killed
- Disable battery optimization for your app
- Check device-specific power management settings
- Enable "Don't optimize" in battery settings
iOS Issues
Background location not working
- Ensure "Always" location permission
- Enable background app refresh
- Check iOS location privacy settings
Activity recognition failing
- Verify motion permissions granted
- Check device compatibility
- Ensure iOS 13.0+ for background tasks
General Issues
Poor location accuracy
- Check GPS signal strength
- Adjust location update options
- Monitor health alerts for accuracy warnings
High battery usage
- Increase health check intervals
- Use lower accuracy for non-critical features
- Monitor battery usage analytics
π’ Enterprise Support
For enterprise deployments requiring:
- Custom integrations
- Extended support
- Professional services
- Volume licensing
Contact: support@expo-geofencing.dev
π€ Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Acknowledgments
- Built with Expo Modules API
- Powered by Google Play Services on Android
- Uses Core Location on iOS
- Inspired by the React Native community
π Comparison with Alternatives
| Feature | expo-geofencing | expo-location | Other Libraries |
|---|---|---|---|
| Circular Geofences | β | β | β οΈ |
| Polygon Geofences | β | β | β |
| Activity Recognition | β | β | β |
| Offline Support | β | β | β |
| Health Monitoring | β | β | β |
| Battery Optimization | β | β | β |
| Security Features | β | β | β |
| Enterprise Ready | β | β | β οΈ |
| Webhook Integration | β | β | β |
| Analytics & Reporting | β | β | β |
Made with β€οΈ for the Expo and React Native community