Quickstart

The Roam Flutter Plugin makes it quick and easy to build a location tracker for your Flutter app. We provide powerful and customizable tracking modes and features that can be used to collect your users location updates.

Here’s a link to our example app : Example Application

Install the plugin

Add following lines to your applications pubspec.yml:

dependencies:
  roam_flutter: ^0.0.5

Install the plugin using the following command:

flutter pub get

Alternatively, the code editor might support flutter pub get. Check the editor docs for your editor to learn more.

Platform Configuration

iOS

To configure the location services, add following entries to the Info.plist file.

Then, in your project settings, go to Capabilities > Background Modes and turn on background fetch, location updates, remote-notifications.

Then, go to Build Settings in the project targets and change 'Always Embed Swift Standard Libraries' to 'Yes'.

Android

Add below lines in your AndroidManifest.xml file.

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

Initialize SDK

Import the plugin in the main.dart file of your project

import 'package:roam_flutter/roam_flutter.dart';

Initialize the plugin with your sdk key.

Roam.initialize(publishKey:'YOUR-SDK-KEY');   

Creating Users

Once the SDK is initialized, we need to create or get a user to start the tracking and use other methods. Every user created will have a unique GeoSpark identifier which will be used later to login and access developer APIs. We can call it as GeoSpark userId.

Roam.createUser(description:'Joe',callBack: ({user}) {
// do something on create user
print(user);
});

The option user description can be used to update your user information such as name, address or add an existing user ID. Make sure the information is encrypted if you are planning to save personal user information like email or phone number.

You can always set or update user descriptions later using the below code.

Roam.setDescription(description:'Joe');

If you already have a GeoSpark userID which you would like to reuse instead of creating a new user, use the below to get user session.

Roam.getUser(userId:'60181b1f521e0249023652bc',callBack: ({user}) {
// do something on get user
print(user);
});

Request Permissions

Get location permission from the App user on the device. Also check if the user has turned on location services for the device.

Add this to your package's pubspec.yaml file:

dependencies:
  permission_handler: ^5.1.0+2

Now in your Dart code, you can use:

import 'package:permission_handler/permission_handler.dart';

Used the below below method to request location permissions.

Permission.locationAlways.request();

Location Tracking

Start Tracking

Roam.startTracking(trackingMode: 'TRACKING-MODE');

Use the tracking modes while you use the startTracking method Roam.startTracking()

Tracking Modes

Roam has three default tracking modes along with a custom version. They differ based on the frequency of location updates and battery consumption. The higher the frequency, the higher is the battery consumption.

Mode	Battery usage	**Updates every **	**Optimised for/advised for **
Active	6% - 12%	25 ~ 250 meters	Ride Hailing / Sharing
Reactive	3% - 6%	50 ~ 500 meters	On Demand Services
Passive	0% - 1%	100 ~ 1000 meters	Social Apps

// passive tracking
Roam.startTracking(trackingMode: 'passive');
// balanced tracking
Roam.startTracking(trackingMode: 'balanced');
// active tracking
Roam.startTracking(trackingMode: 'active');

Custom Tracking Modes

The SDK also allows you define a custom tracking mode that allows you to customize and build your own tracking modes.

iOS

Roam.startTracking(trackingMode: "custom",customMethods: <CUSTOM_TRACKING_METHOD>);

Example

Map<String, dynamic> fitnessTracking = {
                          "activityType": "fitness",
                          "pausesLocationUpdatesAutomatically": true,
                          "showsBackgroundLocationIndicator": true,
                          "distanceFilter": 10,
                          "useSignificantLocationChanges": false,
                          "useRegionMonitoring": false,
                          "useVisits": false,
                          "desiredAccuracy": "nearestTenMeters"
                        };
Roam.startTracking(trackingMode: "custom",customMethods: fitnessTracking);

You may see a delay if the user's device is in low power mode or has connectivity issues.

Android

In Android, you can set custom tracking to two different tracking options. Once with fixed distance interval and another with time based interval.

Map<String, dynamic> fitnessTracking = {
                          "distanceInterval": 10
                        };
Roam.startTracking(trackingMode: "custom",customMethods: fitnessTracking);

Map<String, dynamic> fitnessTracking = {
                          "timeInterval": 10
                        };
Roam.startTracking(trackingMode: "custom",customMethods: fitnessTracking);

Stop Tracking

To stop the tracking use the below method.

Roam.stopTracking();