{"id":25676408,"url":"https://github.com/roam-ai/roam-reactnative","last_synced_at":"2026-03-04T02:06:28.250Z","repository":{"id":37414692,"uuid":"348591983","full_name":"roam-ai/roam-reactnative","owner":"roam-ai","description":"React Native Location SDK. High accuracy and battery efficient location SDK for iOS and Android by Roam.ai","archived":false,"fork":false,"pushed_at":"2025-02-12T12:17:08.000Z","size":5306,"stargazers_count":31,"open_issues_count":17,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-23T13:34:44.690Z","etag":null,"topics":["gps","javascript","location","npm","react-native","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":"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-03-17T05:37:54.000Z","updated_at":"2025-02-14T01:14:33.000Z","dependencies_parsed_at":"2023-02-12T04:03:08.452Z","dependency_job_id":"d21b1250-b1a9-4e44-b823-a84f85f620da","html_url":"https://github.com/roam-ai/roam-reactnative","commit_stats":{"total_commits":174,"total_committers":11,"mean_commits":"15.818181818181818","dds":0.7413793103448276,"last_synced_commit":"487d0af403aa869ecc71eb177a598860115ac61e"},"previous_names":["geosparks/roam-reactnative"],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-reactnative","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-reactnative/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-reactnative/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-reactnative/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roam-ai","download_url":"https://codeload.github.com/roam-ai/roam-reactnative/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250440572,"owners_count":21431020,"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":["gps","javascript","location","npm","react-native","roam"],"created_at":"2025-02-24T14:26:29.781Z","updated_at":"2026-03-04T02:06:28.244Z","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-reactnative/blob/master/logo.png?raw=true\" width=\"180\"\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n\u003c/p\u003e\n\n[![npm version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=js\u0026type=6\u0026v=0.0.38\u0026x2=0)](https://badge.fury.io/js/roam-reactnative)\n[![Npm Publish](https://github.com/geosparks/roam-reactnative/actions/workflows/main.yml/badge.svg?branch=0.0.1)](https://github.com/geosparks/roam-reactnative/actions/workflows/main.yml)\n\n# Official Roam React Native SDK\n\nThis is the official [Roam](https://roam.ai) iOS SDK developed and maintained by Roam B.V\n\nNote: Before you get started [signup to our dashboard](https://roam.ai/dashboard/signup) to get your API Keys.\n\n## Featured Apps\n\n\u003ca href=\"https://sprintcrowd.com\"\u003e\u003cimg src=\"https://sprintcrowd.com/wp-content/uploads/2020/08/sc-logo_400.png\" width=\"100\"\u003e\u003c/a\u003e\n\u003ca href=\"https://letstransport.in\"\u003e\u003cimg src=\"https://i.imgur.com/pDIb2BK.png\" width=\"100\"\u003e\u003c/a\u003e\n\n# Quick Start\n\nThe Roam React Native SDK makes it quick and easy to build a location tracker for your React Native app. We provide powerful and customizable tracking modes and features that can be used to collect your users location updates.\n\n### Requirements\n\nTo use the Roam SDK, the following things are required:\nGet yourself a free Roam Account. No credit card required.\n\n- [x] Create a project and add an iOS app to the project.\n- [x] You need the SDK_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 React Native application.\n\n# Add the Roam React Native SDK to your app\n\nIn your project directory, install from npm or yarn, and then link it.\n\n```bash\n//npm\nnpm install --save roam-reactnative\n\n//yarn\nyarn add roam-reactnative\n```\n\nIf using React Native version of 0.60 or greater, autolinking is now done automatically so you can skip this step.\n\n```\n//React Native\nreact-native link roam-reactnative\n\n//Expo\nexpo install roam-reactnative\n```\n\nMinimum supported versions\n\n```\nreact-native: 0.41.2\nreact: 15.4.2\n```\n\nBefore making any changes to your javascript code, you would need to integrate and initialize Roam SDK in your Android and iOS applications.\n\n### Android\n\n1. Add the following to the build script `{repositories {}}` section of the `build.gradle` (Project)file\n\n   ```java\n   mavenCentral()\n   ```\n\n2. Install the SDK to your project via `Gradle` in Android Studio, add the maven below in your project `build.gradle` file.\n\n   ```java\n   repositories {\n       maven {\n           url 'https://com-roam-android.s3.amazonaws.com/'\n       }\n   }\n   ```\n\n3. Add the dependencies below in your `app build.gradle` file. Then sync Gradle.\n\n   ```\n   dependencies {\n       implementation 'com.roam.sdk:roam-android:0.1.42-beta.2'\n   }\n   ```\n\n4. Before initializing the SDK, the below must be imported in your Main Activity.\n\n   ```java\n   import com.roam.sdk.Roam;\n   ```\n\n5. After 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\n   Roam.initializeSimplifiedSDK(this, \"YOUR-SDK-KEY-GOES-HERE\");\n   ```\n\n### iOS\n\n1. Run `cd ios` \u0026\u0026 `pod install`\n2. Then, configure the information property list file `Info.plist` with an XML snippet that contains data about your app. You need to add strings for `NSLocationWhenInUseUsageDescription` in the `Info.plist` file to prompt the user during location permissions for foreground location tracking. For background location tracking, you also need to add a string for `NSLocationAlwaysUsageDescription` and `NSLocationAlwaysAndWhenInUseUsageDescription` in the same` Info.plist` file.\n\n   ```xml\n   \u003ckey\u003eNSLocationWhenInUseUsageDescription\u003c/key\u003e\n   \u003cstring\u003eAdd description for foreground only location usage.\u003c/string\u003e\n   \u003ckey\u003eNSLocationAlwaysUsageDescription\u003c/key\u003e\n   \u003cstring\u003eAdd description for background location usage. iOS 10 and below\"\u003c/string\u003e\n   \u003ckey\u003eNSLocationAlwaysAndWhenInUseUsageDescription\u003c/key\u003e\n   \u003cstring\u003eAdd description for background location usage. iOS 11 and above\u003c/string\u003e\n   ```\n\n   ![Screenshot 2021-06-25 at 8 40 46 PM](https://user-images.githubusercontent.com/19217956/123445597-aa8cf380-d5f5-11eb-9188-15ad742f11a8.png)\n\n3. Next you need to enable`Background fetch` and` Location updates` under `Project Setting` \u003e `Capabilities` \u003e `Background Modes`.\n\n   ![Screenshot 2021-06-25 at 8 38 24 PM](https://user-images.githubusercontent.com/19217956/123445386-74e80a80-d5f5-11eb-85d6-e06ef4300734.png)\n\n4. Import Roam into your `AppDelegate` file.\n\n   ```objective-c\n   #import \u003cRoam/Roam.h\u003e\n   ```\n\n5. Initialize the SDK in your `AppDelegate` class before calling any other Roam methods under this `application:didFinishLaunchingWithOptions:`\n\n   ```objective-c\n   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions\n   {\n     [Roam initialize:@\"YOUR-PUBLISHABLE-KEY\" :NULL :NULL];\n   }\n   ```\n\n### Manual Linking\n\n1. Open the iOS module files, located inside `node_modules/roam-reactnative/ios/`.\n2. Open the app workspace file `(AppName.xcworkspace)` in Xcode.\n3. Move the `RNRoam.h` and `RNRoam.m` files to your project. When shown a popup window, select `Create groups`.\n\n# Finally, lets do some javascript\n\n## Import module\n\nFirst, import the module.\n\n```javascript\nimport Roam from \"roam-reactnative\";\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```javascript\nRoam.createUser(\n  \"SET-USER-DESCRIPTION-HERE\",\n  (success) =\u003e {\n    // do something on success\n  },\n  (error) =\u003e {\n    // do something on error\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```javascript\nRoam.setDescription(\"SET-USER-DESCRIPTION-HERE\");\n```\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```javascript\nRoam.getUser(\n  \"ROAM-USER-ID\",\n  (success) =\u003e {\n    // do something on success\n  },\n  (error) =\u003e {\n    // do something on error\n  },\n);\n```\n\n## Request Permissions\n\nGet location permission from the App user on the device. Also check if the user has turned on location services for the device.\n\n```javascript\n// Call this method to check Location Permission for Android \u0026 iOS\nRoam.checkLocationPermission( status =\u003e {\n// do something with status\n});\n\n​// Call this method to request Location Permission for Android \u0026 iOS\nRoam.requestLocationPermission();\n```\n\n### Android\n\n```javascript\n// Call this method to check Location services for Android\nRoam.checkLocationServices( status =\u003e {\n// do something with status\n});\n​// Call this method to request Location services for Android\nRoam.requestLocationServices();\n```\n\nIn case of devices running above Anroid 10, you would need to get background location permissions to track locations in background.\n\n```javascript\n// Call this method to check background location permission for Android\nRoam.checkBackgroundLocationPermission((status) =\u003e {\n  // do something with status\n});\n// Call this method to request background location Permission for Android\nRoam.requestBackgroundLocationPermission();\n```\n\n### SDK Configurations\n\n#### Accuracy Engine\n\nFor enabling accuracy engine for Passive, Active, and Balanced tracking.\n\n```javascript\nRoam.enableAccuracyEngine();\n```\n\nFor Custom tracking mores, you can pass the desired accuracy values in integers ranging from 25-150m.\n\n```javascript\nRoam.enableAccuracyEngine(50);\n```\n\nTo disable accuracy engine\n\n```javascript\nRoam.disableAccuracyEngine();\n```\n\n#### Offline Location Tracking\n\nTo modify the offline location tracking configuration, which will enabled by default.\n\n```javascript\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```javascript\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```javascript\nRoam.startTracking(TrackingMode);\n```\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```javascript\n// active tracking\nRoam.startTracking(\"ACTIVE\");\n// balanced tracking\nRoam.startTracking(\"BALANCED\");\n// passive tracking\nRoam.startTracking(\"PASSIVE\");\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#### Android\n\n| **Type**          | **Unit** | **Unit Range** |\n| ----------------- | -------- | -------------- |\n| Distance Interval | Meters   | 1m ~ 2500m     |\n| Time Interval     | Seconds  | 10s ~ 10800s   |\n\n**Android: Distance between location updates:**\n\n```javascript\n//Update location based on distance between locations.\nRoam.startTrackingDistanceInterval(\n  \"DISTANCE IN METERS\",\n  \"STATIONARY DURATION IN SECONDS\",\n  Roam.DesiredAccuracy.HIGH,\n);\n```\n\nHere, the `DISTANCE IN METERS` refers to distance interval for location tracking and `STATIONARY DURATION IN SECONDS` refers to duration for which location update is determined as stationary.\n\nBelow is the example for distance based tracking with distance interval as 10m and stationary duration as 2 minutes.\n\n```javascript\n//Update location based on distance between locations.\nRoam.startTrackingDistanceInterval(10, 120, Roam.DesiredAccuracy.HIGH);\n```\n\n**Android: Time between location updates:**\n\n```javascript\n//Update location based on time interval.\nRoam.startTrackingTimeInterval(\n  \"INTERVAL IN SECONDS\",\n  Roam.DesiredAccuracy.HIGH,\n);\n```\n\nHere, the `INTERVAL IN SECONDS` refers to time interval for location tracking.\n\nBelow is the example for time based tracking with time interval as 10s.\n\n```javascript\n//Update location based on time interval.\nRoam.startTrackingTimeInterval(10, Roam.DesiredAccuracy.HIGH);\n```\n\n#### iOS\n\nWe have a single method for iOS which can perfrom both time and distance based tracking based on the input parameters.\n\n```javascript\n// Update location on distance interval\nRoam.startTrackingCustom(\n  allowBackground,\n  pauseAutomatic,\n  activityType,\n  desiredAccuracy,\n  showBackIndicator,\n  distanceFilter,\n  accuracyFilter,\n  updateInterval,\n);\n```\n\n**iOS: Distance between location updates:**\n\nHere, the `distanceFilter` refers to distance interval for location tracking which should be in meters. To achieve distance based tracking, the `updateInterval` value should be 0.\n\nBelow is the example for distance based tracking with distance interval as 20 meters.\n\n```javascript\nRoam.startTrackingCustom(\n  true, // allowBackground\n  false, // pauseAutomatic\n  Roam.ActivityType.FITNESS, // activityType\n  Roam.DesiredAccuracyIOS.BEST, // desiredAccuracy\n  true, // showBackIndicator\n  20, // distanceFilter\n  10, // accuracyFilter\n  0, // updateInterval\n);\n```\n\n**iOS: Time between location updates:**\n\n```javascript\n// Update location on time interval\nRoam.startTrackingCustom(\n  allowBackground,\n  pauseAutomatic,\n  activityType,\n  desiredAccuracy,\n  showBackIndicator,\n  distanceFilter,\n  accuracyFilter,\n  updateInterval,\n);\n```\n\nHere, the `updateInterval` refers to time interval for location tracking which should be in seconds. To achieve time based tracking, the `distanceFilter` value should be 0.\n\nBelow is the example for time based tracking with time interval as 120s.\n\n```javascript\nRoam.startTrackingCustom(\n  true, // allowBackground\n  false, // pauseAutomatic\n  Roam.ActivityType.FITNESS, // activityType\n  Roam.DesiredAccuracyIOS.BEST, // desiredAccuracy\n  true, // showBackIndicator\n  0, // distanceFilter\n  10, // accuracyFilter\n  120, // updateInterval\n);\n```\n\n### Update Location When Stationary\n\nBy using this method updateLocationWhenStationary , location will update every x seconds when device goes to stationary state.\n\nNote: It will work on all tracking modes ie. active, passive, balance and distance based custom tracking except time based custom tracking.\n\n```javascript\nRoam.updateLocationWhenStationary(interval);\n```\n\nFor example, to update location every 60s when the user becomes stationary, use the below code.\n\n```javascript\nRoam.updateLocationWhenStationary(60);\n```\n\n## Stop Tracking\n\nTo stop the tracking use the below method.\n\n```javascript\nRoam.stopTracking();\n```\n\n## Publish Messages\n\nIt will both publish location data and these data will be sent to Roam servers for further processing and data will be saved in our database servers.\nWe will now have an option to send meta-data as a parameter along with location updates in the below json format.\n\n```javascript\nRoam.publishAndSave(metadataJSON);\n```\n\nExample\n\n```javascript\n//Metadata is not mandatory\nlet metadataJSON = { METADATA: { 1: true, 2: true, 3: true } };\n\nRoam.publishAndSave(metadataJSON);\noptional;\nRoam.publishAndSave(null);\n```\n\n## Stop Publishing\n\nIt will stop publishing the location data to other clients.\n\n```javascript\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```javascript\nRoam.subscribe(TYPE, \"USER-ID\");\n```\n\n| **Type** | **Description**                                                               |\n| -------- | ----------------------------------------------------------------------------- |\n| LOCATION | Subscribe to your own location (or) other user's location updates.            |\n| EVENTS   | Subscribe to your own events.                                                 |\n| BOTH     | Subscribe to your own events and location (or) other user's location updates. |\n\n### UnSubscribe\n\n```javascript\nRoam.unSubscribe(TYPE, \"USER-ID\");\n```\n\nYou can pass `user_id` as empty string to unsubscribe from all the users.\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```javascript\nRoam.toggleListener(\n  true,\n  true,\n  (success) =\u003e {\n    // do something on success\n  },\n  (error) =\u003e {\n    // do something on error\n  },\n);\n```\n\nOnce the listener toggles are set to true, to listen to location updates and events.\n\nNote: The location data received will be an array with either single or multiple location data.\n\n```javascript\nRoam.startListener(\"location\", (location) =\u003e {\n  // do something on location received\n  console.log(\"Location\", location);\n  // Console Output:\n  // [{\"activity\": \"S\", \"location\": {\"accuracy\": 22.686637856849305, \"altitude\": 288.10509490966797, \"latitude\": 10.356502722371895, \"longitude\": 78.00075886670541, \"speed\": -1}, \"recordedAt\": \"2022-03-22T11:18:04.928Z\", \"timezone\": \"+0530\", \"userId\": \"6239b06506df1f5c1c375353\"},{..}...]\n});\n```\n\nYou can also configure batch setting for the location receiver. To set the batch configuration, you need to pass batch count and batch window.\n\n```javascript\nRoam.setBatchReceiverConfig(NETWORK_STATE, BATCH_COUNT, BATCH_WINDOW, success =\u003e {\n // do something on success\n //success.batchCount,\n //success.batchWindow,\n //success.networkState\n},\nerror =\u003e {\n// do something on error\n//error.code\n//error.message\n}););\n```\n\n| **Type**      | **Description**                         |\n| ------------- | --------------------------------------- |\n| NETWORK_STATE | online (or) offline (or) both           |\n| BATCH_COUNT   | Integer value from 1-1000. Default as 1 |\n| BATCH_WINDOW  | Integer value. Default as 0             |\n\nYou can get the current configured settings with the below code.\n\n```javascript\nRoam.getBatchReceiverConfig(\n  (success) =\u003e {\n    // do something on success\n    //success.batchCount,\n    //success.batchWindow,\n    //success.networkState\n  },\n  (error) =\u003e {\n    // do something on error\n    //error.code\n    //error.message\n  },\n);\n```\n\nYou can reset the batch configuration to default values with the below code.\n\n```javascript\nRoam.resetBatchReceiverConfig(\n  (success) =\u003e {\n    // do something on success\n    //success.batchCount,\n    //success.batchWindow,\n    //success.networkState\n  },\n  (error) =\u003e {\n    // do something on error\n    //error.code\n    //error.message\n  },\n);\n```\n\n## Documentation\n\nPlease visit our [Developer Center](https://github.com/geosparks/roam-reactnative/wiki) for instructions on other SDK methods.\n\n## Contributing\n\n- For developing the SDK, please visit our [CONTRIBUTING.md](https://github.com/geosparks/roam-reactnative/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).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-reactnative","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froam-ai%2Froam-reactnative","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-reactnative/lists"}