poly_geofence_service

Description:

poly geofence service

This plugin is a service that can perform geo-fencing by creating a polygon geofence. It does not use the Geofence API implemented on the platform. Therefore, battery efficiency cannot be guaranteed. Instead, this plugin can provide more accurate and realtime geo-fencing by navigating your location while your app is alive.

Screenshots #



Google Maps
Result









Features #

Complex geo-fencing can be performed by creating polygon geofence.
PolyGeofenceService can perform geo-fencing in real time and catch errors during operation.

Getting started #
To use this plugin, add poly_geofence_service as a dependency in your pubspec.yaml file. For example:
dependencies:
poly_geofence_service: ^4.0.0
copied to clipboard
After adding the poly_geofence_service plugin to the flutter project, we need to specify the platform-specific permissions and services to use for this plugin to work properly.
🐤 Android #
Since geo-fencing operates based on location, we need to add the following permission to the AndroidManifest.xml file. Open the AndroidManifest.xml file and specify it between the <manifest> and <application> tags.
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
copied to clipboard
🐤 iOS #
Like Android platform, geo-fencing is based on location, we need to add the following description. Open the ios/Runner/Info.plist file and specify it inside the <dict> tag.
<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to provide geofence service.</string>
copied to clipboard
How to use #

Create a PolyGeofenceService instance and set options. PolyGeofenceService.instance.setup() provides the following options:


interval: The time interval in milliseconds to check the polygon geofence status. The default is 5000.
accuracy: Geo-fencing error range in meters. The default is 100.
loiteringDelayMs: Sets the delay between PolyGeofenceStatus.ENTER and PolyGeofenceStatus.DWELL in milliseconds. The default is 300000.
statusChangeDelayMs: Sets the status change delay in milliseconds. PolyGeofenceStatus.ENTER and PolyGeofenceStatus.EXIT events may be called frequently when the location is near the boundary of the polygon geofence. Use this option to minimize event calls at this time. If the option value is too large, realtime geo-fencing is not possible, so use it carefully. The default is 10000.
allowMockLocations: Whether to allow mock locations. The default is false.
printDevLog: Whether to show the developer log. If this value is set to true, logs for geofence service activities (start, stop, etc.) can be viewed. It does not work in release mode. The default is false.

// Create a [PolyGeofenceService] instance and set options.
final _polyGeofenceService = PolyGeofenceService.instance.setup(
interval: 5000,
accuracy: 100,
loiteringDelayMs: 60000,
statusChangeDelayMs: 10000,
allowMockLocations: false,
printDevLog: false);
copied to clipboard

Create a PolyGeofence list. PolyGeofence provides the following parameters:


id: Identifier for PolyGeofence.
data: Custom data for PolyGeofence.
polygon: A list of coordinates to create a polygon. The polygon is always considered closed, regardless of whether the last point equals the first or not.

// Create a [PolyGeofence] list.
final _polyGeofenceList = <PolyGeofence>[
PolyGeofence(
id: 'Yongdusan_Park',
data: {
'address': '37-55 Yongdusan-gil, Gwangbokdong 2(i)-ga, Jung-gu, Busan',
'about': 'Mountain park known for its 129m-high observation tower, statues & stone monuments.',
},
polygon: <LatLng>[
const LatLng(35.101727, 129.031665),
const LatLng(35.101815, 129.033458),
const LatLng(35.100032, 129.034055),
const LatLng(35.099324, 129.033811),
const LatLng(35.099906, 129.031927),
const LatLng(35.101080, 129.031534),
],
),
];
copied to clipboard

Register the listener and call PolyGeofenceService.instance.start().

// This function is to be called when the geofence status is changed.
Future<void> _onPolyGeofenceStatusChanged(
PolyGeofence polyGeofence,
PolyGeofenceStatus polyGeofenceStatus,
Location location) async {
print('polyGeofence: ${polyGeofence.toJson()}');
print('polyGeofenceStatus: ${polyGeofenceStatus.toString()}');
}

// This function is to be called when the location has changed.
void _onLocationChanged(Location location) {
print('location: ${location.toJson()}');
}

// This function is to be called when a location services status change occurs
// since the service was started.
void _onLocationServicesStatusChanged(bool status) {
print('isLocationServicesEnabled: $status');
}

// This function is used to handle errors that occur in the service.
void _onError(error) {
final errorCode = getErrorCodesFromError(error);
if (errorCode == null) {
print('Undefined error: $error');
return;
}

print('ErrorCode: $errorCode');
}

@override
void initState() {
super.initState();
WidgetsBinding.instance.addPostFrameCallback((_) {
_polyGeofenceService.addPolyGeofenceStatusChangeListener(_onPolyGeofenceStatusChanged);
_polyGeofenceService.addLocationChangeListener(_onLocationChanged);
_polyGeofenceService.addLocationServicesStatusChangeListener(_onLocationServicesStatusChanged);
_polyGeofenceService.addStreamErrorListener(_onError);
_polyGeofenceService.start(_polyGeofenceList).catchError(_onError);
});
}
copied to clipboard

To add or remove PolyGeofence while the service is running, use the following function:

_polyGeofenceService.addPolyGeofence(Object);
_polyGeofenceService.addPolyGeofenceList(List);
_polyGeofenceService.removePolyGeofence(Object);
_polyGeofenceService.removePolyGeofenceList(List);
_polyGeofenceService.removePolyGeofenceById(String);
_polyGeofenceService.clearPolyGeofenceList();
copied to clipboard

If you want to pause or resume the service, use the function below.

_polyGeofenceService.pause();
_polyGeofenceService.resume();
copied to clipboard

When you are finished using the service, unregister the listener and call PolyGeofenceService.instance.stop().

_polyGeofenceService.removePolyGeofenceStatusChangeListener(_onPolyGeofenceStatusChanged);
_polyGeofenceService.removeLocationChangeListener(_onLocationChanged);
_polyGeofenceService.removeLocationServicesStatusChangeListener(_onLocationServicesStatusChanged);
_polyGeofenceService.removeStreamErrorListener(_onError);
_polyGeofenceService.clearAllListeners();
_polyGeofenceService.stop();
copied to clipboard
Note: When calling the stop function, the listener is not removed, but the added geofence is cleared.
Models #
🐔 LatLng #
A model representing the latitude and longitude of GPS.



Property
Description




latitude
The latitude of GPS.


longitude
The longitude of GPS.



🐔 PolyGeofence #
A model representing a polygon geofence.



Property
Description




id
Identifier for PolyGeofence.


data
Custom data for PolyGeofence.


polygon
A list of coordinates to create a polygon. The polygon is always considered closed, regardless of whether the last point equals the first or not.


status
The status of PolyGeofence.


timestamp
The timestamp when polygon geofence status changes.



🐔 PolyGeofenceStatus #
Defines the status of the polygon geofence.



Value
Description




ENTER
Occurs when entering the geofence area.


EXIT
Occurs when exiting the geofence area.


DWELL
Occurs when the loitering delay elapses after entering the geofence area.



🐔 ErrorCodes #
Error codes that may occur in the service.



Value
Description




ALREADY_STARTED
Occurs when the service has already been started but the start function is called.


LOCATION_SERVICES_DISABLED
Occurs when location services are disabled. When this error occurs, you should notify the user and request activation.


LOCATION_PERMISSION_DENIED
Occurs when location permission is denied.


LOCATION_PERMISSION_PERMANENTLY_DENIED
Occurs when location permission is permanently denied. In this case, the user must manually allow the permission.



Support #
If you find any bugs or issues while using the plugin, please register an issues on GitHub. You can also contact us at [email protected].