{"id":25933115,"url":"https://github.com/roam-ai/roam-flutter","last_synced_at":"2025-03-04T00:52:12.424Z","repository":{"id":37861054,"uuid":"334058899","full_name":"roam-ai/roam-flutter","owner":"roam-ai","description":"Flutter Location SDK. High accuracy and battery efficient location SDK for iOS and Android by Roam.ai","archived":false,"fork":false,"pushed_at":"2024-11-01T09:35:38.000Z","size":282,"stargazers_count":17,"open_issues_count":6,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-01T10:25:22.236Z","etag":null,"topics":["background-location","flutter","location-sdk","location-tracker","roam"],"latest_commit_sha":null,"homepage":"https://roam.ai","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roam-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-29T06:33:07.000Z","updated_at":"2024-05-17T12:02:37.000Z","dependencies_parsed_at":"2024-11-01T10:21:58.602Z","dependency_job_id":"eed2c61b-ba9e-419f-9e11-07b51a902eef","html_url":"https://github.com/roam-ai/roam-flutter","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-flutter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-flutter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-flutter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-flutter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roam-ai","download_url":"https://codeload.github.com/roam-ai/roam-flutter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241763740,"owners_count":20016162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["background-location","flutter","location-sdk","location-tracker","roam"],"created_at":"2025-03-04T00:52:11.996Z","updated_at":"2025-03-04T00:52:12.407Z","avatar_url":"https://github.com/roam-ai.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://roam.ai\" target=\"_blank\" align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/geosparks/roam-flutter/blob/master/logo.png?raw=true\" width=\"180\"\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n\u003c/p\u003e\n\n[![pub package](https://img.shields.io/pub/v/roam_flutter.svg)](https://pub.dartlang.org/packages/roam_flutter)\n[![Pub.dev Publish](https://github.com/roam-ai/roam-flutter/actions/workflows/dart.yml/badge.svg?branch=master)](https://github.com/roam-ai/roam-flutter/actions/workflows/dart.yml)\n\n# Official Roam Flutter SDK\n\nThis is the official Roam Flutter SDK developed and maintained by Roam B.V\n\nNote: Before you get started [signup to our dashboard](https://roam.ai) to get your API Keys.\n\n# Quick Start\n\nThe Roam Flutter Plugin makes it quick and easy to build a\nlocation tracker for your Flutter app. We provide powerful and\ncustomizable tracking modes and features that can be used to collect\nyour users location updates.\n\nHere’s a link to our example app : [Example Application](https://github.com/roam-ai/roam-flutter/tree/master/example)\n\n## Install the plugin\n\nAdd following lines to your applications pubspec.yml:\n\n```dart\ndependencies:\n  roam_flutter: ^0.1.7\n```\n\nInstall the plugin using the following command:\n\n```dart\nflutter pub get\n```\n\nAlternatively, the code editor might support flutter pub get. Check the editor docs for your editor to learn more.\n\n## Platform Configuration\n\n**iOS**\n\nTo configure the location services, add following entries to the\n**Info.plist** file.\n\n![](https://gblobscdn.gitbook.com/assets%2F-LSIY5fR7w61d6wHf6iI%2F-LWA3HF19_HBBEZj1hrU%2F-LWA55gjYBsLYYd8f_Oi%2F4.png?alt=media\u0026token=4feb38a5-d013-43ab-81a6-7b69f96e09c4)\n\nThen, in your project settings, go to `Capabilities \u003e Background Modes`\nand turn on background fetch, location updates, remote-notifications.\n\n![](https://gblobscdn.gitbook.com/assets%2F-LSIY5fR7w61d6wHf6iI%2F-LWA3HF19_HBBEZj1hrU%2F-LWA5AepQh8EoHoIB3xS%2F3.png?alt=media\u0026token=9436cc91-33b6-4126-8629-c610d80bb281)\n\nThen, go to Build Settings in the project targets and change 'Always\nEmbed Swift Standard Libraries' to 'Yes'.\n\n**Android**\n\nAdd below lines in your `AndroidManifest.xml` file.\n\n```xml\n    \u003cuses-permission android:name=\"android.permission.INTERNET\"/\u003e\n    \u003cuses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.ACCESS_BACKGROUND_LOCATION\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.RECEIVE_BOOT_COMPLETED\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.SYSTEM_ALERT_WINDOW\" /\u003e\n```\n\n## Initialize SDK\n\nImport the plugin in the main.dart file of your project\n\n```dart\nimport 'package:roam_flutter/roam_flutter.dart';\n```\n\nInitialize the plugin with your `sdk key`.\n\n```dart\nRoam.initialize(publishKey:'YOUR-SDK-KEY');\n```\n\n## Creating Users\n\nOnce the SDK is initialized, we need to _create_ or _get a user_ to\nstart the tracking and use other methods. Every user created will have a\nunique Roam identifier which will be used later to login and access\ndeveloper APIs. We can call it as Roam userId.\n\n```dart\nRoam.createUser(description:'Joe',callBack: ({user}) {\n// do something on create user\nprint(user);\n});\n```\n\nThe option _user description_ can be used to update your user\ninformation such as name, address or add an existing user ID. Make sure\nthe information is encrypted if you are planning to save personal user\ninformation like email or phone number.\n\nYou can always set or update user descriptions later using the below\ncode.\n\n```dart\nRoam.setDescription(description:'Joe');\n```\n\nIf you already have a Roam userID which you would like to reuse\ninstead of creating a new user, use the below to get user session.\n\n```dart\nRoam.getUser(userId:'60181b1f521e0249023652bc',callBack: ({user}) {\n// do something on get user\nprint(user);\n});\n```\n\n## Request Permissions\n\nGet location permission from the App user on the device. Also check if\nthe user has turned on location services for the device.\n\nAdd this to your package's pubspec.yaml file:\n\n```dart\ndependencies:\n  permission_handler: ^5.1.0+2\n```\n\nNow in your Dart code, you can use:\n\n```dart\nimport 'package:permission_handler/permission_handler.dart';\n```\n\nUsed the below below method to request location permissions.\n\n```dart\nPermission.locationAlways.request();\n```\n\n## Location Tracking\n\n### Start Tracking\n\n```dart\nRoam.startTracking(trackingMode: 'TRACKING-MODE');\n```\n\nUse the tracking modes while you use the startTracking method\n`Roam.startTracking()`\n\n### **Tracking Modes**\n\nRoam has three default tracking modes along with a custom version.\nThey differ based on the frequency of location updates and battery\nconsumption. The higher the frequency, the higher is the battery\nconsumption.\n\n\u003cdiv class=\"table-wrap\"\u003e\n\n|          |                   |                    |                                |\n| -------- | ----------------- | ------------------ | ------------------------------ |\n| **Mode** | **Battery usage** | **Updates every ** | **Optimised for/advised for ** |\n| Active   | 6% - 12%          | 25 ~ 250 meters    | Ride Hailing / Sharing         |\n| Balanced | 3% - 6%           | 50 ~ 500 meters    | On Demand Services             |\n| Passive  | 0% - 1%           | 100 ~ 1000 meters  | Social Apps                    |\n\n\u003c/div\u003e\n\n```dart\n// passive tracking\nRoam.startTracking(trackingMode: 'passive');\n// balanced tracking\nRoam.startTracking(trackingMode: 'balanced');\n// active tracking\nRoam.startTracking(trackingMode: 'active');\n```\n\n### Custom Tracking Modes\n\nThe SDK also allows you define a custom tracking mode that allows you to\ncustomize and build your own tracking modes.\n\n**iOS**\n\n```dart\nRoam.startTracking(trackingMode: \"custom\",customMethods: \u003cCUSTOM_TRACKING_METHOD\u003e);\n```\n\nExample\n\n```dart\nMap\u003cString, dynamic\u003e fitnessTracking = {\n                          \"activityType\": \"fitness\",\n                          \"pausesLocationUpdatesAutomatically\": true,\n                          \"showsBackgroundLocationIndicator\": true,\n                          \"distanceFilter\": 10,\n                          \"useSignificantLocationChanges\": false,\n                          \"useRegionMonitoring\": false,\n                          \"useVisits\": false,\n                          \"desiredAccuracy\": \"nearestTenMeters\"\n                        };\nRoam.startTracking(trackingMode: \"custom\",customMethods: fitnessTracking);\n```\n\nYou may see a delay if the user's device is in low power mode or has\nconnectivity issues.\n\n**Android**\n\nIn Android, you can set custom tracking to two different tracking options. Once with fixed distance interval and another with time based interval.\n\n```dart\nMap\u003cString, dynamic\u003e fitnessTracking = {\n                          \"distanceInterval\": 10\n                        };\nRoam.startTracking(trackingMode: \"custom\",customMethods: fitnessTracking);\n```\n\n```dart\nMap\u003cString, dynamic\u003e fitnessTracking = {\n                          \"timeInterval\": 10\n                        };\nRoam.startTracking(trackingMode: \"custom\",customMethods: fitnessTracking);\n```\n\n### Stop Tracking\n\nTo stop the tracking use the below method.\n\n```dart\nRoam.stopTracking();\n```\n\n## Location Listener\n\nTo receive locations in dart use the below method.\n\n```dart\nRoam.onLocation((location) {\n                      print(jsonEncode(location));\n                    });\n```\n\n## SDK Methods\n\n- Please visit our [Developer Center](https://github.com/roam-ai/roam-flutter/wiki/SDK-Methods) for instructions on other SDK methods.\n\n## Contributing\n\n- For developing the SDK, please visit our [CONTRIBUTING.md](https://github.com/roam-ai/roam-flutter/blob/master/CONTRIBUTING.md) to get started.\n\n## Need Help?\n\nIf you have any problems or issues over our SDK, feel free to create a github issue or submit a request on [Roam Help](https://geosparkai.atlassian.net/servicedesk/customer/portal/2).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-flutter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froam-ai%2Froam-flutter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-flutter/lists"}