geofencing_api 2.0.0 copy "geofencing_api: ^2.0.0" to clipboard
geofencing_api: ^2.0.0 copied to clipboard

This plugin is used to implement circular and polygon geofencing service.

This plugin is used to implement circular and polygon geofencing service.

Caution

It does not use the geofencing api implemented in the platform. Therefore, battery efficiency cannot be guaranteed. Instead, this plugin can provide more accurate and real-time geofencing by navigating your location while your app is alive.

Features #

  • Can create a circular type geofence.
  • Can create a polygon type geofence.
  • Can listen to geofence status changes in real-time.
  • Can listen to location changes in real-time.
  • Can request or check location permission.

Getting started #

To use this plugin, add geofencing_api as a dependency in your pubspec.yaml file. For example:

dependencies:
  geofencing_api: ^2.0.0
copied to clipboard

After adding the plugin to your flutter project, we need to declare the platform-specific permissions to use for this plugin to work properly.

🐤 Android #

Since the geofencing service works based on location, we need to declare location permission.

Open the AndroidManifest.xml file and declare permission between the <manifest> and <application> tags.

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
copied to clipboard

🐤 iOS #

Open the ios/Runner/Info.plist file and declare description within the <dict> tag.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to collect location data.</string>
copied to clipboard

🐤 Background Mode #

To perform geofencing in the background, declare permissions and descriptions.

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
copied to clipboard
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Used to collect location data in the background.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Used to collect location data in the background.</string>
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>location</string>
</array>
copied to clipboard

Then use flutter_foreground_task to implement a background geofencing service.

demo: https://github.com/Dev-hwang/flutter_foreground_task_example/tree/main/geofencing_service

How to use #

  1. Request location permission. To start the geofencing service, the permission result must be always or whileInUse.
Future<bool> requestLocationPermission({bool background = false}) async {
  if (!await Geofencing.instance.isLocationServicesEnabled) {
    // Location services is disabled.
    return false;
  }

  LocationPermission permission =
      await Geofencing.instance.getLocationPermission();
  if (permission == LocationPermission.denied) {
    // Android: ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION
    // iOS 12-: NSLocationWhenInUseUsageDescription or NSLocationAlwaysAndWhenInUseUsageDescription
    // iOS 13+: NSLocationWhenInUseUsageDescription
    permission = await Geofencing.instance.requestLocationPermission();
  }

  if (permission == LocationPermission.denied ||
      permission == LocationPermission.deniedForever) {
    // Location permission has been ${permission.name}.
    return false;
  }

  // Web: Only allow whileInUse permission.
  if (kIsWeb || kIsWasm) {
    return true;
  }

  // Android: You must request location permission one more time to access background location.
  // iOS 12-: You can request always permission through the above request.
  // iOS 13+: You can only request whileInUse permission. When the app enters the background,
  // a prompt will appear asking for always permission.
  if (Platform.isAndroid &&
      background &&
      permission == LocationPermission.whileInUse) {
    // You need a clear explanation of why your app's feature needs access to background location.
    // https://developer.android.com/develop/sensors-and-location/location/permissions#request-background-location

    // Android: ACCESS_BACKGROUND_LOCATION
    permission = await Geofencing.instance.requestLocationPermission();

    if (permission != LocationPermission.always) {
      // Location permission must always be granted to collect location in the background.
      return false;
    }
  }

  return true;
}
copied to clipboard
  1. Set up the geofencing service.
  • interval: The millisecond interval at which to update the geofence status. This value may be delayed by device platform limitations. The default is 5000.
  • accuracy: The accuracy of the geofencing service in meters. The default is 100.
  • statusChangeDelay: The status change delay in milliseconds. GeofenceStatus.enter and GeofenceStatus.exit events may be called frequently when the location is near the boundary of the geofence. If the option value is too large, real-time geofencing is not possible, so use it carefully. The default is 10000.
  • allowsMockLocation: Whether to allow mock location. The default is false.
  • printsDebugLog: Whether to print debug logs in plugin. The default is true.
void setupGeofencing() {
  Geofencing.instance.setup(
    interval: 5000,
    accuracy: 100,
    statusChangeDelay: 10000,
    allowsMockLocation: false,
    printsDebugLog: true,
  );
}
copied to clipboard
  1. Create geofence regions. Use the .circular or .polygon constructor.
  • id: The unique id of the geofence region.
  • data: The data of the geofence region.
  • loiteringDelay: The delay between GeofenceStatus.enter and GeofenceStatus.dwell in milliseconds. The default is 30000.
  • center: The center coordinates of the geofence. (circular)
  • radius: The radius of the geofence. This value should be 10 meters or greater. (circular)
  • polygon: The polygon coordinates of the geofence. This value must have size 3 or greater. (polygon)
final Set<GeofenceRegion> _regions = {
  GeofenceRegion.circular(
    id: 'circular_region',
    data: {
      'name': 'National Museum of Korea',
    },
    center: const LatLng(37.523085, 126.979619),
    radius: 250,
    loiteringDelay: 60 * 1000,
  ),
  GeofenceRegion.polygon(
    id: 'polygon_region',
    data: {
      'name': 'Gyeongbokgung Palace',
    },
    polygon: [
      const LatLng(37.583696, 126.973739),
      const LatLng(37.583441, 126.979361),
      const LatLng(37.582506, 126.980198),
      const LatLng(37.579054, 126.979490),
      const LatLng(37.576112, 126.979061),
      const LatLng(37.576503, 126.974126),
      const LatLng(37.580959, 126.973568),
    ],
    loiteringDelay: 60 * 1000,
  ),
};
copied to clipboard
  1. Start the geofencing service. You can add geofence regions before starting the service using the regions parameter.
void startGeofencing() async {
  Geofencing.instance.addGeofenceStatusChangedListener(_onGeofenceStatusChanged);
  Geofencing.instance.addGeofenceErrorCallbackListener(_onGeofenceError);
  
  // You can add listeners as needed.
  Geofencing.instance.addLocationChangedListener(LocationChanged);
  Geofencing.instance.addLocationServicesStatusChangedListener(LocationServicesStatusChanged);
  
  await Geofencing.instance.start(regions: _regions);
}

Future<void> _onGeofenceStatusChanged(
  GeofenceRegion geofenceRegion,
  GeofenceStatus geofenceStatus,
  Location location,
) async {
  final String regionId = geofenceRegion.id;
  final String statusName = geofenceStatus.name;
  print('region(id: $regionId) $statusName');
}

void _onGeofenceError(Object error, StackTrace stackTrace) {
  print('error: $error\n$stackTrace');
}
copied to clipboard
  1. You can add or remove regions even after the service starts.
void addRegions() {
  Geofencing.instance.addRegion(GeofenceRegion);
  Geofencing.instance.addRegions(Set<GeofenceRegion>);
}

void removeRegions() {
  Geofencing.instance.removeRegion(GeofenceRegion);
  Geofencing.instance.removeRegions(Set<GeofenceRegion>);
  Geofencing.instance.removeRegionById(String);
  Geofencing.instance.clearAllRegions();
}
copied to clipboard
  1. You can pause or resume the service.
void pauseGeofencing() {
  Geofencing.instance.pause();
}

void resumeGeofencing() {
  Geofencing.instance.resume();
}
copied to clipboard
  1. Stop the geofencing service. If you want to keep added regions, set keepsRegions to true.
void stopGeofencing() async {
  Geofencing.instance.removeGeofenceStatusChangedListener(_onGeofenceStatusChanged);
  Geofencing.instance.removeGeofenceErrorCallbackListener(_onGeofenceError);
  Geofencing.instance.removeLocationChangedListener(LocationChanged);
  Geofencing.instance.removeLocationServicesStatusChangedListener(LocationServicesStatusChanged);
  
  await Geofencing.instance.stop(keepsRegions: true);
}
copied to clipboard

More Documentation #

Go here to learn about the models provided by this plugin.

Go here to migrate to the new version.

Support #

If you find any bugs or issues while using the plugin, please register an issues on GitHub. You can also contact us at hwj930513@naver.com.

15
likes
160
points
342
downloads

Publisher

verified publisherpravera.me

Weekly Downloads

2024.07.31 - 2025.02.12

This plugin is used to implement circular and polygon geofencing service.

Repository (GitHub)

Documentation

API reference

License

MIT (license)

Dependencies

fl_location, flutter, flutter_web_plugins, meta, plugin_platform_interface, vector_math

More

Packages that depend on geofencing_api