Quickstart
The Cyprinus 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.

Requirements

To use the Cyprinus SDK, the following things are required:
  • Get yourself a free Cyprinus Account. No credit card required.
  • Create a project and add an iOS app to the project.
  • You need the SDK_KEY in your project settings which you’ll need to initialize the SDK.
  • Now you’re ready to integrate the SDK into your iOS application.
The Cyprinus iOS SDK requires Xcode 10.0 or later and is compatible with apps targeting iOS version 10 and above

Run the example application

The Cyprinus Example repository on GitHub includes example apps that demonstrate the use of the v3 Cyprinus SDK for iOS.
See a Swift example app in Example/.
To run the example app, clone this repository, add your publishable YOUR-PUBLISHABLE-KEY key in AppDelegate.swift, and build the app.
Make sure the bundle_id is the same as the one registered in our Cyprinus Playground dashboard.
GitHub - roam-ai/roam-ios: iOS Location SDK. High accuracy and battery efficient location SDK for iOS by Roam.ai
GitHub

Xcode Setup

To integrate the Cyprinus SDK, you need a Cyprinus account.
  1. 1.
    Go to Xcode > File > New Project
  2. 2.
    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.
    1
    <key>NSLocationWhenInUseUsageDescription</key>
    2
    <string>Add description for foreground only location usage.</string>
    3
    <key>NSLocationAlwaysUsageDescription</key>
    4
    <string>Add description for background location usage. iOS 10 and below"</string>
    5
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    6
    <string>Add description for background location usage. iOS 11 and above</string>
    Copied!
Next you need to enableBackground fetch and Location updates under Project Setting > Capabilities > Background Modes.

SDK Installation

There are several ways to integrate the Cyprinus Mobile SDK for iOS into your own project:
  • Swift Package Manager
  • CocoaPods
  • Carthage (Will be added soon)
  • Dynamic Frameworks

Swift Package Manager Installation

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 > Swift Packages > Add Package Dependency.
Enter the URL for the Cyprinus SDK for iOS Swift Package Manager GitHub repo (https://github.com/roam-ai/roam-ios) into the search bar and click Next.
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.
Select roam-ios, then click Finish.
Screenshot 2021-06-29 at 12 22 38 PM
You 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.

CocoaPods Installation

Follow the steps below to add the SDK to the project using CocoaPods. Add the below to the Podfile
1
pod 'roam-ios'
Copied!
Then run pod install.
This will add the Cyprinus SDK and its dependencies to your project. The Cyprinus SDK depends on CoreLocation, AWSMobileClient and AWSIoT for fetching locations and its transmission to our servers. The SDK supports iOS 10 and above.

Manual Installation

If 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 file.
Unzip the file and add the Cyprinus Roam.framework to your Xcode project by dragging the file into your Project Navigator.
You 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 Cyprinus framework. You will also want to add the following frameworks from this link.
1
AWSAuthCore.xcframework
2
AWSCognitoIdentityProvider.xcframework
3
AWSCognitoIdentityProviderASF.xcframework
4
AWSCore.xcframework
5
AWSIoT.xcframework
6
AWSMobileClientXCF.xcframework
Copied!
Make sure the the added frameworks under Linked Frameworks and Libraries section are selected as Embed & Sign

Initialize SDK

Add the following code in AppDelegate file. This code imports the SDK and allows the SDK to use other methods.
1
import Roam
Copied!
After import, add the below code underapplication(_:didFinishLaunchingWithOptions:) in your AppDelegate file. The SDK must be initialized before calling any of the other SDK methods using your project's publishable key.
1
Roam.initialize("YOUR-SDK-KEY-GOES-HERE")
Copied!

Request Permissions

Before you start location tracking, you need to get permission from the user for your application to access locations.
  1. 1.
    Import CoreLocation at the top of the AppDelegate file.
    1
    import CoreLocation
    Copied!
  2. 2.
    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.
    1
    let locationManager = CLLocationManager()
    2
    locationManager.requestLocation()
    Copied!

Location Tracking

Start Tracking

1
Roam.startSelfTracking(TrackingMode)
Copied!
Use one of the tracking modes while you use the Roam.startSelfTracking method.

Stop Tracking

To stop the tracking use the below method.
1
Roam.stopSelfTracking()
Copied!

Tracking Modes

Adaptive Tracking

Cyprinus 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.
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
1
//active tracking
2
Roam.startSelfTracking(RoamTrackingMode.active)
3
// balanced tracking
4
Roam.startSelfTracking(RoamTrackingMode.balanced)
5
// passive tracking
6
Roam.startSelfTracking(RoamTrackingMode.passive)
Copied!

Distance Interval Tracking

The SDK also provides a custom tracking mode which allows you to customize and build your own tracking mode as per your requirement.
Type
Unit
Unit Range
Distance Interval
Meters
1m ~ 2500m
Distance between location updates example code:
1
// Define a custom tracking method
2
let trackingMethod = RoamTrackingCustomMethods()
3
4
// Update the settings for the created method as per need
5
trackingMethod.activityType = .fitness
6
trackingMethod.pausesLocationUpdatesAutomatically = true
7
trackingMethod.showsBackgroundLocationIndicator = true
8
trackingMethod.useSignificant = false
9
trackingMethod.useRegionMonitoring = false
10
trackingMethod.useVisits = false
11
trackingMethod.accuracyFilter = 10
12
trackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters
13
14
// Update the distance intervel as per the use case in meters
15
trackingMethod.distanceFilter = 10
16
17
// Start the tracking with the above created custom tracking method
18
Roam.startSelfTracking(.custom, options: trackingMethod)
Copied!

Time Interval Tracking

Type
Unit
Unit Range
Time Interval
seconds
1s - 10000s
Time between location updates example code:
1
// Define a custom tracking method
2
let trackingMethod = RoamTrackingCustomMethods()
3
4
// Update the settings for the created method as per need
5
trackingMethod.activityType = .fitness
6
trackingMethod.pausesLocationUpdatesAutomatically = true
7
trackingMethod.showsBackgroundLocationIndicator = true
8
trackingMethod.useSignificant = false
9
trackingMethod.useRegionMonitoring = false
10
trackingMethod.useVisits = false
11
trackingMethod.accuracyFilter = 10
12
trackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters
13
14
// Update the time intervel as per the use case in seconds
15
trackingMethod.updateInterval = 10
16
17
// Start the tracking with the above created custom tracking method
18
Roam.startSelfTracking(.custom, options: trackingMethod)
Copied!

Location Listener

To listen to location updates create a class that implements RoamDeleagate and then call Roam.delegate.
Set your RoamDeleagate in a code path that will be initialized and executed in the background. For example, make your AppDelegate implement RoamDeleagate, not a ViewController. AppDelegate will be initialized in the background, whereas a ViewController may not be.
Note: In self tracking, you can listen to only location, error and offline trips status data since the locations are not being sent to our servers for processing events.
Swift
1
import UIKit
2
import Roam
3
import CoreLocation
4
5
@main
6
class AppDelegate: UIResponder, UIApplicationDelegate, RoamDelegate {
7
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
8
Roam.delegate = self
9
Roam.initialize("YOUR-SDK-KEY-GOES-HERE")
10
return true
11
}
12
func didUpdateLocation(_ location: RoamLocation) {
13
// Do something with the user location
14
}
Copied!
Last modified 4mo ago