Flutter Plugin

Setup the Woosmap Geofencing SDK using the Flutter Plugin

The Woosmap Geofencing SDK allows you to monitor Geofences, track your user’s location and connect with the Woosmap Search and Distance APIs.

Find Geofencing Flutter package release notes in the Changelog section of the pub.dev website.

Install the Woosmap Geofencing Flutter plugin

Prerequisites

Before you begin, ensure you have installed and setup Flutter platform on your machine. See this get-started.

Installation

Add Woosmap Geofencing flutter plugin to your project using this command line:

Shell
        flutter pub add geofencing_flutter_plugin

Adding the platform

For iOS

  • info.plist: Please check info.plist updated with the following keys:
    • NSLocationAlwaysAndWhenInUseUsageDescription
    • NSLocationAlwaysUsageDescription
    • NSLocationWhenInUseUsageDescription
    • UIBackgroundModes
xml
        <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Used to test the library</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Used to test the library</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to test the library</string>
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>location</string>
</array>

Supported Platforms

  • iOS (Plugin supports iOS 15 and higher)
  • Android (Plugin supports Android 33 and higher)

App closed limitations Because of the Flutter framework, callbacks are not triggered when the application is closed. Locations and geofence events are well stored in the device, and you can retrieve them through getter methods included in this plugin.

Modules

  • GeofencingFlutterPlugin: Woosmap contains methods to monitor location and regions.

Objects(Read Only)

  • Location: Represents the location object
  • POI: Represents Point of Interest
  • Region: Represents a geographical region/Geofence

Types

  • ProfileSource: Represents tracking profile source. It can either be ProfileSource.local or ProfileSource.external
  • RegionType: Represents the type of the region. Possible values are RegionType.circle and RegionType.isochrone

Usage

dart
        import 'package:geofencing_flutter_plugin/geofencing_flutter_plugin.dart';

final geofencingFlutterPlugin = GeofencingFlutterPlugin();
...

Check and request permissions

Before initializing the SDK, you must request for required location permissions.

To check if the user grants location permissions call getPermissionsStatus method.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.getPermissionsStatus();

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: ${error.message}');
});

Parameter status will be a string, one of:

  • GRANTED_BACKGROUND: The user has been granted location access even when the app is not running in foreground.
  • GRANTED_FOREGROUND: Location access is granted only while a user uses the app.
  • DENIED: Location access is denied.
  • UNKNOWN: Without providing or denying any permission, it will return unknown.

Please note: Plugin will not work as expected if location access is denied.

Requesting location access To request location access call requestPermissions method of the plugin. This will result in displaying location access permission dialog. This method accepts a boolean parameter background. If this parameter is true, the plugin will ask for background location access. The code snippet below asks for background location access.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.requestPermissions(background);

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: ${error.message}');
});

Check Bluetooth permissions

In order to get beacon-fencing running on Android devices you need to make sure that all the Bluetooth related permissions are granted to the plugin.

To check if the Bluetooth permissions are granted by the user call getBLEPermissionsStatus method.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.getBLEPermissionsStatus();
returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: ${error.message}');
});

Parameter status will be a string, one of:

  • GRANTED : User has granted bluetooth access.
  • DENIED: Bluetooth access is denied.
  • BACKGROUND_LOCATION_DENIED: Background location access is denied. You first need to request background location permission.

Requesting Bluetooth permissions

To request Bluetooth access call requestBLEPermissions method of the plugin. This will result in displaying Bluetooth access permission dialog.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.requestBLEPermissions();
returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: ${error.message}');
});

Note: For beacon-fencing to work you will also need to request background location access. To request background location access please invoke requestPermissions method of the plugin with background parameter enabled.

Initializing the plugin

Plugin can be initialized by simply calling initialize method.

dart
        Map<String, String> woosmapSettings = {
    "privateKeyWoosmapAPI": "<<WOOSMAP_KEY>>",
    "trackingProfile": "liveTracking"
};

Future<String?> returnVal = geofencingFlutterPlugin.initialize(woosmapSettings);

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: $error');
});

Both configuration options privateKeyWoosmapAPI and trackingProfile are optional. You can also initialize the plugin by passing a null configuration.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.initialize();

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: $error');
});

You can also set the Woosmap API key later by calling setWoosmapApiKey method.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.setWoosmapApiKey("<<WOOSMAP_KEY>>");

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: ${error.message}');
});

Tracking

Once you have initialized plugin and user has authorised location permissions, you can start tracking the user’s location.

To start tracking, call:

dart
        Future<String?> returnVal = geofencingFlutterPlugin.startTracking('liveTracking');

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: ${error.message}');
});

To stop tracking, call:

dart
        Future<String?> returnVal = geofencingFlutterPlugin.stopTracking();

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: ${error.message}');
});

Method startTracking accepts only following tracking profiles

  • liveTracking
  • passiveTracking
  • optimalPassiveTracking
  • visitsTracking
  • beaconTracking

Notifications on Android devices

Geofencing SDK uses foreground service on Android when using liveTracking and optimalPassiveTracking profile. The SDK needs to show an ongoing notification in order to work properly while tracking using these profiles.

You need to make sure that permission to post notification is granted before initiating tracking with liveTracking and optimalPassiveTracking.

To request permission invoke requestNotificationPermissions method.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.requestNotificationPermissions();

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: ${error.message}');
});

Customize notifications on Android devices

Notifications on Android devices can be customized using following configuration options. These options should be passed wile initializing the plugin.

  • androidNotificationTitle: Title of the notification.
  • androidNotificationText: Content text of the notification.
  • androidNotificationIconName: Set the notification icon name from Android drawable or mipmap folder.
  • androidNotificationIconUrl: Set the notification icon fron Flutter assets by providing the asset path.
dart
        WoosmapGeofencingOptions options = WoosmapGeofencingOptions(
          androidNotificationText: "Notification Title goes here",
          androidNotificationTitle: "Notification Description goes here",
          androidNotificationIconName: "assets/ic_alarm.png");

Future<String?> returnVal = geofencingFlutterPlugin.initialize(options);

Location

To listen to the location, call watchLocation method. After successful invocation of the method, you’ll need to call getWatchLocationStream method which will return a stream of Location object. Once you obtain stream call listen method of the stream.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.watchLocation();

returnVal.then((value){
    //Get the location stream    
    watchLocationStream = geofencingFlutterPlugin.getWatchLocationStream();
    //Listen to the stream
    watchLocationStream.listen((location){
        //Location updates will be received here.
        if (location != null) {
            debugPrint(location.locationDescription);
        } else {
            debugPrint("Location is null");
        }
    });
}).catchError((error) {
    debugPrint('An error occurred: $error');
});

To stop getting location updates

Call clearLocationWatch method to remove all locations in the local db.

dart
        Future<String?> returnVal = geofencingFlutterPlugin.clearLocationWatch();

returnVal.then((value){
    debugPrint(value!);
}).catchError((error) {
    debugPrint('An error occurred: $error');
});
‹ Find nearest POIs Start a tracking profile ›
Was this helpful?