roam_flutter

Description:

roam flutter

Official Roam Flutter SDK #
This is the official Roam Flutter SDK developed and maintained by Roam B.V
Note: Before you get started signup to our dashboard to get your API Keys.
Quick Start #
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.1.6
copied to clipboard
Install the plugin using the following command:
flutter pub get
copied to clipboard
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" />
copied to clipboard
Initialize SDK #
Import the plugin in the main.dart file of your project
import 'package:roam_flutter/roam_flutter.dart';
copied to clipboard
Initialize the plugin with your sdk key.
Roam.initialize(publishKey:'YOUR-SDK-KEY');
copied to clipboard
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 Roam identifier which will be used later to login and access
developer APIs. We can call it as Roam userId.
Roam.createUser(description:'Joe',callBack: ({user}) {
// do something on create user
print(user);
});
copied to clipboard
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');
copied to clipboard
If you already have a Roam 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);
});
copied to clipboard
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
copied to clipboard
Now in your Dart code, you can use:
import 'package:permission_handler/permission_handler.dart';
copied to clipboard
Used the below below method to request location permissions.
Permission.locationAlways.request();
copied to clipboard
Location Tracking #
Start Tracking #
Roam.startTracking(trackingMode: 'TRACKING-MODE');
copied to clipboard
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


Balanced
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');
copied to clipboard
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>);
copied to clipboard
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);
copied to clipboard
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);
copied to clipboard
Map<String, dynamic> fitnessTracking = {
"timeInterval": 10
};
Roam.startTracking(trackingMode: "custom",customMethods: fitnessTracking);
copied to clipboard
Stop Tracking #
To stop the tracking use the below method.
Roam.stopTracking();
copied to clipboard
Location Listener #
To receive locations in dart use the below method.
Roam.onLocation((location) {
print(jsonEncode(location));
});
copied to clipboard
SDK Methods #

Please visit our Developer Center for instructions on other SDK methods.

Contributing #

For developing the SDK, please visit our CONTRIBUTING.md to get started.

Need Help? #
If you have any problems or issues over our SDK, feel free to create a github issue or submit a request on Roam Help.