{"id":25933170,"url":"https://github.com/roam-ai/roam-android","last_synced_at":"2025-03-04T00:52:23.506Z","repository":{"id":42328398,"uuid":"356277871","full_name":"roam-ai/roam-android","owner":"roam-ai","description":"Android Location SDK. High accuracy and battery efficient location SDK for Android by Roam.ai","archived":false,"fork":false,"pushed_at":"2025-02-19T11:19:41.000Z","size":17768,"stargazers_count":15,"open_issues_count":2,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-19T12:23:58.994Z","etag":null,"topics":["android-sdk","background-location","library","location","location-sdk","maven","roam"],"latest_commit_sha":null,"homepage":"https://roam.ai","language":"Java","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":null,"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-04-09T13:18:55.000Z","updated_at":"2025-02-19T11:13:32.000Z","dependencies_parsed_at":"2024-08-28T13:35:13.864Z","dependency_job_id":"940f6ca3-2e5c-4a0e-941f-79149a73f9fa","html_url":"https://github.com/roam-ai/roam-android","commit_stats":null,"previous_names":[],"tags_count":78,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roam-ai","download_url":"https://codeload.github.com/roam-ai/roam-android/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241763741,"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":["android-sdk","background-location","library","location","location-sdk","maven","roam"],"created_at":"2025-03-04T00:52:22.932Z","updated_at":"2025-03-04T00:52:23.486Z","avatar_url":"https://github.com/roam-ai.png","language":"Java","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# Official Roam Android SDK\nThis is the official [Roam](https://roam.ai) Android 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## Featured Apps\n\n\u003ca href=\"https://hugoapp.com\"\u003e\u003cimg src=\"https://i.imgur.com/xRqznN9.png\" width=\"100\"\u003e\u003c/a\u003e\n\u003ca href=\"https://handy.la\"\u003e\u003cimg src=\"https://i.imgur.com/EDGcldE.png\" width=\"100\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pickerexpress.com\"\u003e\u003cimg src=\"https://media.giphy.com/avatars/Picker_ec/lNLRCBxHo8BJ.png\" width=\"100\"\u003e\u003c/a\u003e\n\n\n\n## Quickstart\n\nThe Roam Android SDK makes it quick and easy to build a location tracker for your Android app. We provide powerful and customizable tracking modes and features.\n\n### **Requirements**\n\nTo use the Roam SDK, the following things are required:\n\n- [x] Get yourself a free [Roam Account](https://playground.geospark.co/). No credit card required.\n- [x] Create a project and add an Android app to the project.\n- [x] You need the `PUBLISHABLE_KEY` in your project settings which you’ll need to initialize the SDK.\n- [x] Now you’re ready to integrate the SDK into your Android application.\n- [x] The Roam Android SDK requires Android Studio 2.0 or later and is compatible with apps targeting Android SDK Version 16 or above.\n\n### Android Studio Setup\n\nTo use the Android SDK in a project, add the SDK as a build dependency and sync the project.\n\n1. Go to Android Studio \u003e New Project \u003e Minimum SDK\n\n2. Select API 16: Android 4.1.0 (Jelly Bean) or higher and create a project\n\n### Gradle Installation\n\nAdd the following to the build script `{repositories {}}` section of the `build.gradle` (Project)file\n\n```java\nmavenCentral()\n```\n\n\nInstall the SDK to your project via `Gradle` in Android Studio, add the maven below in your project `build.gradle` file.\n\n```java\nrepositories {\n    maven {\n        url 'https://com-roam-android.s3.amazonaws.com/'\n    }\n}\n```\n\nadd the dependencies below in your `app build.gradle` file.\n\n```\ndependencies {\n    implementation 'com.roam.sdk:roam-android:0.1.35'\n}\n```\n\nThen sync Gradle.\n\n### Manual Installation\n\n[Download](https://github.com/roam-ai/roam-android/releases/download/0.1.35/Roam.zip) and unzip Roam SDK\n\n1. Open Android Studio and add the SDK `Roam.aar` as a module using File \u003e New \u003e New Module \u003e Import .JAR/.AAR Package.\n2. Once Gradle is finished click File \u003e Project Structure again.\n3. Click on the Dependencies tab \u003e click App \u003e click the “+” icon in the top left in Declared Dependencies section \u003e select Module Dependency \u003e click on Roam-release \u003e press Ok and wait for Gradle to sync again and include the dependencies separately and sync your project.\n4. Wait for Gradle to sync again and include the dependencies separately and sync your project.\n\n```java\ndependencies {\n    implementation 'com.google.android.gms:play-services-location:17.0.0'\n    implementation 'com.squareup.retrofit2:retrofit:2.6.2'\n    implementation 'com.squareup.retrofit2:converter-gson:2.1.0'\n    implementation 'org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.4'\n    implementation 'org.eclipse.paho:org.eclipse.paho.android.service:1.1.1'\n}\n```\n\n### Initialize SDK\n\nBefore initializing the SDK, the below must be imported.\n\n```java\nimport com.roam.sdk.Roam;\n```\n\nAfter import, add the below code under the Application class `onCreate()` method. The SDK must be initialised before calling any of the other SDK methods.\n\n```java\nRoam.initialize(this, \"YOUR-SDK-KEY-GOES-HERE\");\n```\n\n### Creating Users\n\nOnce 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.\n\n```java\nRoam.createUser(\"YOUR-USER-DESCRIPTION-GOES-HERE\", new RoamCallback() {\n            @Override\n            public void onSuccess(RoamUser roamUser) {\n                // Access Roam user data below\n                // roamUser.getUserId();\n                // roamUser.getDescription();\n                // roamUser.getEventListenerStatus();\n                // roamUser.getLocationListenerStatus();\n                // roamUser.getLocationEvents();\n                // roamUser.getGeofenceEvents();\n                // roamUser.getMovingGeofenceEvents();\n                // roamUser.getTripsEvents();\n            }\n\n            @Override\n            public void onFailure(RoamError roamError) {\n                // Access error code \u0026 message below\n                // roamError.getCode();\n                // roamError.getMessage();\n            }\n        });\n```\n\nThe 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.\n\nYou can always set or update user descriptions later using the below code.\n\n```java\nRoam.setDescription(\"SET-USER-DESCRIPTION-HERE\");\n```\n\n### Get User\n\nIf 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.\n\n```java\nRoam.getUser(\"YOUR-ROAM-USER-ID\", new RoamCallback() {\n            @Override\n            public void onSuccess(RoamUser roamUser) {\n                // Access Roam user data below\n                // roamUser.getUserId();\n                // roamUser.getDescription();\n                // roamUser.getEventListenerStatus();\n                // roamUser.getLocationListenerStatus();\n                // roamUser.getLocationEvents();\n                // roamUser.getGeofenceEvents();\n                // roamUser.getMovingGeofenceEvents();\n                // roamUser.getTripsEvents();\n            }\n\n            @Override\n            public void onFailure(RoamError roamError) {\n                // Access error code \u0026 message below\n                // roamError.getCode();\n                // roamError.getMessage();\n            }\n        });\n```\n\n### Request Permission\n\n To request the location for devices running both below/above Android 10.\n\n```java\nif (!Roam.checkLocationServices()) {\n       Roam.requestLocationServices(this);\n} else if (!Roam.checkLocationPermission()) {\n       Roam.requestLocationPermission(this);\n} else if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.Q \u0026\u0026 !Roam.checkBackgroundLocationPermission()) {\n       Roam.requestBackgroundLocationPermission(this);\n}\n```\n\n### SDK Configurations\n\n#### Accuracy Engine\n\nFor enabling accuracy engine for Passive, Active, and Balanced tracking.\n\n```java\nRoam.enableAccuracyEngine();\n```\n\nFor Custom tracking mores, you can pass the desired accuracy values in integers ranging from 25-150m.\n\n```java\nRoam.enableAccuracyEngine(50);\n```\nTo disable accuracy engine\n\n```java\nRoam.disableAccuracyEngine();\n```\n\n#### Offline Location Tracking\n\nTo modify the offline location tracking configuration, which will enabled by default. \n\n```java\nRoam.offlineLocationTracking(true);\n```\n\n#### Allow Mock Location Tracking\n\nTo allow mock location tracking during development, use the below code. This will be disabled by default. \n\n```java\nRoam.allowMockLocation(true);\n```\n\n### Location Tracking\n\n#### Start Tracking\n\nUse the tracking modes while you use the startTracking method `Roam.startTracking`\n\n#### **Tracking Modes**\n\nRoam 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. You must use [foreground service](https://developer.android.com/about/versions/oreo/background-location-limits) for continuous tracking.\n\n| **Mode** | **Battery usage** | **Updates every** | **Optimised for/advised for** |\n| -------- | ----------------- | ----------------- | ----------------------------- |\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```java\n// active tracking\nRoam.startTracking(RoamTrackingMode.ACTIVE);\n// balanced tracking\nRoam.startTracking(RoamTrackingMode.BALANCED);\n// passive tracking\nRoam.startTracking(RoamTrackingMode.PASSIVE);\n```\n\n#### Custom Tracking Modes\n\nThe SDK also provides a custom tracking mode that allows you to customize and build your own tracking modes.\n\n| **Type**          | **Unit** | **Unit Range** |\n| ----------------- | -------- | -------------- |\n| Distance Interval | Meters   | 1m ~ 2500m     |\n| Time Interval     | Seconds  | 10s ~ 10800s   |\n\n**Distance between location updates example code:**\n\n```java\n// Define a custom tracking method with desired distance interval, stop duration and accuracy\nRoamTrackingMode trackingMode = new RoamTrackingMode.Builder(\u003cDISTANCE-FILTER-IN-METERS\u003e, \u003cSTOP-INTERVAL-IN-SECONDS\u003e)\n                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)\n                .build();\n// Start the tracking with the above created custom tracking method\nRoam.startTracking(trackingMode);\n```\n\n**Time between location updates example code:**\n\n```java\n// Define a custom tracking method with desired time interval and accuracy\nRoamTrackingMode trackingMode = new RoamTrackingMode.Builder(\u003cTIME-INTERVAL-IN-SECONDS\u003e)\n                .setDesiredAccuracy(RoamTrackingMode.DesiredAccuracy.HIGH)\n                .build();\n// Start the tracking with the above created custom tracking method\nRoam.startTracking(trackingMode);\n```\n\nYou may see a delay if the user's device is in low power mode or has connectivity issues.\n\n#### Stop Tracking\n\nTo stop the tracking use the below method.\n\n```java\nRoam.stopTracking();\n```\n\n### **Publish Messages**\n\nIt will publish location data and these data will be sent to Roam servers for further processing and data will be saved in our database servers.\n\n```java\nRoamPublish locationData = new RoamPublish.Builder().build();\nRoam.publishAndSave(locationData);\n```\n\nTo stop publishing locations.\n\n```java\nRoam.stopPublishing();\n```\n\n### Subscribe Messages\n\nNow that you have enabled the location listener, use the below method to subscribe to your own or other user's location updates and events.\n\n#### Subscribe\n\n```java\nRoam.subscribe(TYPE, \"ROAM-USER-ID\");\n```\n\n#### UnSubscribe\n\n```java\nRoam.unSubscribe(TYPE, \"USER-ID\");\n```\n\n| **Type**                | **Description**                                              |\n| ----------------------- | ------------------------------------------------------------ |\n| Roam.Subscribe.EVENTS   | Subscribe to your own events.                                |\n| Roam.Subscribe.LOCATION | Subscribe to your own location (or) other user's location updates. |\n| Roam.Subscribe.BOTH     | Subscribe to your own events and location (or) other user's location updates. |\n\n### Listeners\n\nNow that the location tracking is set up, you can subscribe to locations and events and use the data locally on your device or send it directly to your own backend server.\n\nTo do that, you need to set the location and event listener to `true` using the below method. By default the status will set to `false` and needs to be set to `true` in order to stream the location and events updates to the same device or other devices.\n\n```java\nRoam.toggleListener(true, true, new RoamCallback() {\n            @Override\n            public void onSuccess(RoamUser roamUser) {\n\t        // Access Roam user data below\n                // roamUser.getUserId();\n                // roamUser.getDescription();\n                // roamUser.getEventListenerStatus();\n                // roamUser.getLocationListenerStatus();\n                // roamUser.getLocationEvents();\n                // roamUser.getGeofenceEvents();\n                // roamUser.getMovingGeofenceEvents();\n                // roamUser.getTripsEvents();\n            }\n\n            @Override\n            public void onFailure(RoamError roamError) {\n\t        // Access error code \u0026 message below\n                // roamError.getCode();\n                // roamError.getMessage();\n            }\n        });\n```\n\nOnce the listener toggles are set to true, to listen to location updates and events, create a class that extends GeoSparkReceiver. Then register the receiver by adding a receiver element to the application element in your manifest.\n\n```java\n\u003capplication\u003e\n        ...\n     \u003creceiver android:name=\".LocationReceiver\"\n                    android:enabled=\"true\"\n                    android:exported=\"false\"\u003e\n         \u003cintent-filter\u003e\n         \u003caction android:name=\"com.roam.android.RECEIVED\"/\u003e\n         \u003c/intent-filter\u003e\n     \u003c/receiver\u003e\n         ...\n\u003c/application\u003e\n```\n\nThen add the code to the receiver.\n\n```java\npublic class LocationReceiver extends RoamReceiver {\n\n    @Override\n    public void onLocationUpdated(Context context, RoamLocation roamLocation) {\n        super.onLocationUpdated(context, roamLocation);\n        // receive own location updates here\n\t// do something with location data using location\n\t// roamLocation.getLocation().getLatitude() \n\t// roamLocation.getLocation().getLongitude());\n    }\n    \n    @Override\n    public void onLocationReceived(Context context, RoamLocationReceived roamLocationReceived) {\n        // receive other user's location updates here\n\t// do something with location\n    }\n\n    @Override\n    public void onEventReceived(Context context, RoamEvent roamEvent) {\n\t//access event data here\n    }\n\n    @Override\n    public void onError(Context context, RoamError roamError) {\n    \t// receive error message here\n    \t// roamError.getMessage());\n    }\n\n}\n```\n\n## Documentation\n\nSee the full documentation [here](https://docs.roam.ai/android).\n\n## Example\nSee a Android example app in `Example/`.\nTo run the example app, clone this repository, add your sdk \"YOUR-SDK-KEY\" key in `MainActivity.java`, and run the app.\n\n## Need Help?\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\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froam-ai%2Froam-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-android/lists"}