{"id":25933194,"url":"https://github.com/roam-ai/roam-ios","last_synced_at":"2025-10-09T16:12:23.463Z","repository":{"id":37880214,"uuid":"354786044","full_name":"roam-ai/roam-ios","owner":"roam-ai","description":"iOS Location SDK. High accuracy and battery efficient location SDK for iOS by Roam.ai","archived":false,"fork":false,"pushed_at":"2025-10-09T06:35:04.000Z","size":600278,"stargazers_count":17,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-09T06:51:04.060Z","etag":null,"topics":["background-location","ios-sdk","location-sdk","location-tracker","roam"],"latest_commit_sha":null,"homepage":"https://roam.ai","language":"Objective-C","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-05T09:43:43.000Z","updated_at":"2025-10-09T06:33:24.000Z","dependencies_parsed_at":"2023-02-12T04:02:09.122Z","dependency_job_id":"301e4272-f684-4a25-ba5d-342d33964cc2","html_url":"https://github.com/roam-ai/roam-ios","commit_stats":{"total_commits":113,"total_committers":5,"mean_commits":22.6,"dds":0.5486725663716814,"last_synced_commit":"84540668403fab9a7faabd30c463c342bf1ed562"},"previous_names":[],"tags_count":84,"template":false,"template_full_name":null,"purl":"pkg:github/roam-ai/roam-ios","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roam-ai","download_url":"https://codeload.github.com/roam-ai/roam-ios/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roam-ai%2Froam-ios/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001762,"owners_count":26083171,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","ios-sdk","location-sdk","location-tracker","roam"],"created_at":"2025-03-04T00:52:25.881Z","updated_at":"2025-10-09T16:12:23.450Z","avatar_url":"https://github.com/roam-ai.png","language":"Objective-C","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[![Pod version](https://badge.fury.io/co/roam-ios.svg)](https://badge.fury.io/co/roam-ios) [![CocoaPod Publish](https://github.com/roam-ai/roam-ios/actions/workflows/publish.yml/badge.svg?branch=0.0.1)](https://github.com/roam-ai/roam-ios/actions/workflows/publish.yml)\n\n# Official Roam iOS SDK\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) to get your API Keys. \n\n## Quickstart\nThe Roam iOS SDK makes it quick and easy to build a location tracker for your iOS app. We provide powerful and customizable tracking modes and features that can be used to collect your users’ location updates.\n\n### Requirements\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 iOS application.\n- [x] The Roam iOS SDK requires Xcode 10.0 or later and it compatible with apps targeting iOS version 10 and above.\n\n### Xcode Setup\n\nTo integrate the Roam SDK, you need a Roam account.\n\n1. Go to Xcode \u003e File \u003e New Project\n\n2. 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\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  \n  \n\n### Include the SDK for iOS in an Existing Application\n\nThere are several ways to integrate the Roam Mobile SDK for iOS into your own project:\n\n- [x] Swift Package Manager\n- [x] CocoaPods\n- [ ] Carthage (Will be added soon)\n- [x] Dynamic Frameworks\n\n#### Swift Package Manager Installation\n\n1. Swift Package Manager is distributed with Xcode. To start adding the AWS SDK to your iOS project, open your project in Xcode and select File \u003e Swift Packages \u003e Add Package Dependency.\n\n![image](https://user-images.githubusercontent.com/19217956/123749908-9259f480-d8d3-11eb-8193-1a02d940a298.png)\n\n2. Enter the URL for the Roam SDK for iOS Swift Package Manager GitHub repo (https://github.com/roam-ai/roam-ios) into the search bar and click Next.\n\n![Screenshot 2021-06-29 at 12 17 45 PM](https://user-images.githubusercontent.com/19217956/123750283-0d230f80-d8d4-11eb-9bfc-7f2004b612c5.png)\n\n3. You'll see the repository rules for which version of the SDK you want Swift Package Manager to install. Choose the first rule, Version, and select Up to Next Minor as it will use the latest compatible version of the dependency that can be detected from the main branch, then click Next.\n\n![Screenshot 2021-06-29 at 12 20 11 PM](https://user-images.githubusercontent.com/19217956/123750579-612df400-d8d4-11eb-918a-48799fa7999b.png)\n\n4. Select all that are appropriate, then click Finish.\n\n![Screenshot 2021-06-29 at 12 22 38 PM](https://user-images.githubusercontent.com/19217956/123750894-b8cc5f80-d8d4-11eb-9bdc-e809ad706702.png)\n\nYou can always go back and modify which SPM packages are included in your project by opening the Swift Packages tab for your project: Click on the Project file in the Xcode navigator, then click on your project's icon, then select the Swift Packages tab.\n\n\n#### CocoaPods Installation\n\nFollow the steps below to add the SDK to the project using CocoaPods. Add the below to the `Podfile`\n\n```\npod 'roam-ios'\n```\n\nThen run `pod install`.\n\nThis will add the Roam SDK and its dependencies to your project. The Roam SDK depends on `CoreLocation`, `AWSMobileClient` and `AWSIoT` for fetching locations and its transmission to our servers. The SDK supports iOS 10 and above.\n\n#### Manual Installation\n\nIf you’re not familiar with using Cocoapods or prefer manual installation, we’ve added a ZIP file to the SDK. Use this link to download the [Roam.zip](https://github.com/roam-ai/roam-ios/releases/download/0.2.0-beta.2/Roam.xcframework.zip) file.\n\nUnzip the file and add the Roam `Roam.framework` to your Xcode project by dragging the file into your Project Navigator.\n\nYou can do this by selecting the project file in the navigator on the left side of the Xcode window, and then navigating to the Linked Frameworks and Libraries section. From there, click the “+” button to add the Roam framework. You will also want to add the following frameworks from this [link](https://github.com/aws-amplify/aws-sdk-ios).\n\n```\nAWSAuthCore.xcframework\nAWSCognitoIdentityProvider.xcframework\nAWSCognitoIdentityProviderASF.xcframework\nAWSCore.xcframework\nAWSIoT.xcframework\nAWSMobileClientXCF.xcframework\n```\nMake sure the the added frameworks under Linked Frameworks and Libraries section are selected as `Embed \u0026 Sign`\n\n![Screenshot 2021-06-25 at 8 45 56 PM](https://user-images.githubusercontent.com/19217956/123446788-d8bf0300-d5f6-11eb-96e2-d88e432c209c.png)\n\n### Initialize SDK\n\nAdd the following code in `AppDelegate` file. This code imports the SDK and allows the SDK to use other methods.\n\n```swift\nimport Roam\n```\n\nAfter import, add the below code under `application(_:didFinishLaunchingWithOptions:) `in your `AppDelegate` file. The SDK must be initialized before calling any of the other SDK methods using your project's publishable key.\n\n```swift\nRoam.initialize(\"YOUR-SDK-KEY-GOES-HERE\")\n```\n\n### Creating Users\n\nOnce the SDK is initialised, you 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 to login and access developer APIs. We call this Roam `user_Id`.\n\n```swift\nRoam.createUser(\"YOUR-USER-DESCRIPTION-GOES-HERE\") {(RoamUser, Error) in\n            // Access Roam user data below\n            // RoamUser?.userId\n            // RoamUser?.description\n            // RoamUser?.locationListener\n            // RoamUser?.eventsListener\n            // RoamUser?.locationEvents\n            // RoamUser?.geofenceEvents\n            // RoamUser?.tripsEvents\n            // RoamUser?.nearbyEvents\n            \n            // Access error code \u0026 message below\n            // Error?.code\n            // Error?.message\n        }\n```\n\nThe option *user description* can be used to update 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 information like an email or phone number.\n\nYou can always set or update user descriptions later using the below code.\n\n```swift\nRoam.setDescription(\"SET-USER-DESCRIPTION-HERE\")\n```\n\n### Get User\n\nIf you already have a Roam `user_ID` which you would like to reuse instead of creating a new user, use the code below to get a user session.\n\n```swift\nRoam.getUser(\"YOUR-ROAM-USER-ID\") {(RoamUser, Error) in\n            // Access Roam user data below\n            // RoamUser?.userId\n            // RoamUser?.description\n            // RoamUser?.locationListener\n            // RoamUser?.eventsListener\n            // RoamUser?.locationEvents\n            // RoamUser?.geofenceEvents\n            // RoamUser?.tripsEvents\n            // RoamUser?.nearbyEvents\n            \n            // Access error code \u0026 message below\n            // Error?.code\n            // Error?.message\n        }\n```\n\n### Request Permissions\n\nBefore you start location tracking, you need to get permission from the user for your application to access locations.\n\n1. Import `CoreLocation` at the top of the `AppDelegate` file.\n\n   ```swift\n   import CoreLocation\n   ```\n2. Make the below class declaration for Location Manager and add this line before the return statement in `application(_:didFinishLaunchingWithOptions:)` With this line, you ask users to allow the app to access location data both in the background and the foreground.\n\n   ```swift\n   let locationManager = CLLocationManager()\n   locationManager.requestLocation()\n   ```\n\n### SDK Configurations\n\n#### Accuracy Engine\n\nFor enabling accuracy engine for Passive, Active, and Balanced tracking.\n\n```swift\nRoam.enableAccuracyEngine()\n```\n\nFor Custom tracking mores, you can pass the desired accuracy values in integers ranging from 25-150m.\n\n```swift\nRoam.enableAccuracyEngine(50)\n```\nTo disable accuracy engine\n\n```swift\nRoam.disableAccuracyEngine()\n```\n\n#### Offline Location Tracking\n\nTo modify the offline location tracking configuration, which will enabled by default. \n\n```swift\nRoam.offlineLocationTracking(true)\n```\n\n\n### Location Tracking\n\n#### Start Tracking\n\nUse the below tracking modes while you use the startTracking method `Roam.startTracking`\n\n#### Tracking Modes\n\nYou can now start tracking your users. Roam has three default tracking modes along with a custom version. They are different based on the frequency of location updates and battery consumption. The higher the frequency, the higher the battery consumption.\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```swift\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 which allows you to customize and build your own tracking mode as per your requirement.\n\n| **Type**          | **Unit** | **Unit Range** |\n| ----------------- | -------- | -------------- |\n| Distance Interval | Meters   | 1m ~ 2500m     |\n\n**Distance between location updates example code:**\n\n```swift\n// Define a custom tracking method\nlet trackingMethod = RoamTrackingCustomMethods()\n\n// Update the settings for the created method as per need\ntrackingMethod.activityType = .fitness\ntrackingMethod.pausesLocationUpdatesAutomatically = true\ntrackingMethod.showsBackgroundLocationIndicator = true\ntrackingMethod.useSignificant = false\ntrackingMethod.useRegionMonitoring = false\ntrackingMethod.useVisits = false\ntrackingMethod.accuracyFilter = 10\ntrackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters\n\n// Update the distance intervel as per the use case in meters\ntrackingMethod.distanceFilter = 10\n\n// Start the tracking with the above created custom tracking method\nRoam.startTracking(.custom, options: trackingMethod)\n```\n\n**Time between location updates example code:**\n\n```swift\n// Define a custom tracking method\nlet trackingMethod = RoamTrackingCustomMethods()\n\n// Update the settings for the created method as per need\ntrackingMethod.activityType = .fitness\ntrackingMethod.pausesLocationUpdatesAutomatically = true\ntrackingMethod.showsBackgroundLocationIndicator = true\ntrackingMethod.useSignificant = false\ntrackingMethod.useRegionMonitoring = false\ntrackingMethod.useVisits = false\ntrackingMethod.accuracyFilter = 10\ntrackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters\n\n// Update the time intervel as per the use case in seconds\ntrackingMethod.updateInterval = 10\n\n// Start the tracking with the above created custom tracking method\nRoam.startTracking(.custom, options: trackingMethod)\n```\n\n#### Stop Tracking\n\nTo stop the tracking use the below method.\n\n```swift\nRoam.stopTracking()\n```\n\n### Publish Messages\n\nIt will publish location data and these data will be sent to roam-ios servers for further processing and data will be saved in our database servers.\n\n```swift\nlet locationData = RoamPublish()\nRoam.publishSave(locationData)\n```\n\nTo stop publishing the location data to other clients.\n\n```swift\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```swift\nRoam.subscribe(TYPE, \"ROAM-USER-ID\")\n```\n\n#### UnSubscribe\n\n```swift\nRoam.unsubscribe(TYPE, \"ROAM-USER-ID\")\n```\n\n| **Type**               | **Description**                                              |\n| ---------------------- | ------------------------------------------------------------ |\n| RoamSubscribe.Events   | Subscribe to your own events.                                |\n| RoamSubscribe.Location | Subscribe to your own location (or) other user's location updates. |\n| RoamSubscribe.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 toggle the location and event listener to `true`. 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```swift\nRoam.toggleListener(Events: true, Locations: true) {(RoamUser, Error) in\n            // Access Roam user data below\n            // RoamUser?.userId\n            // RoamUser?.description\n            // RoamUser?.locationListener\n            // RoamUser?.eventsListener\n            // RoamUser?.locationEvents\n            // RoamUser?.geofenceEvents\n            // RoamUser?.tripsEvents\n            // RoamUser?.nearbyEvents\n            \n            // Access error code \u0026 message below\n            // Error?.code\n            // Error?.message\n        }\n```\n\nOnce the listener toggles are set to true, to listen to location updates create a class that implements RoamDelegate and then call Roam.delegate.\n\nSet your `RoamDelegate` in a code path that will be initialized and executed in the background. For example, make your AppDelegate implement GeoSparkDelegate, not a ViewController. AppDelegate will be initialized in the background, whereas a ViewController may not be.\n\n```swift\nimport UIKit\nimport Roam\nimport CoreLocation\n\n@main\nclass AppDelegate: UIResponder, UIApplicationDelegate, RoamDelegate {\n    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -\u003e Bool {\n        Roam.delegate = self\n        Roam.initialize(\"YOUR-SDK-KEY-GOES-HERE\")\n        return true\n    }\n    func didUpdateLocation(_ location: RoamLocation) {\n        // Do something with the user location\n    }\n    func didReceiveEvents(_ events: RoamEvents) {\n        // Do smoething with user events\n    }\n    func didReceiveUserLocation(_ location: RoamLocationReceived) {\n        // Do something with location of other users' subscribed location\n    }\n```\n\n## Example\nSee a Swift example app in `Example/`.\nTo run the example app, clone this repository, add your sdk \"YOUR-SDK-KEY\" key in `AppDelegate.swift`, and build 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froam-ai%2Froam-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froam-ai%2Froam-ios/lists"}