官方 Roam iOS SDK

这是由 Roam B.V 开发和维护的官方 Roam iOS SDK。

注意：在开始之前，请注册我们的仪表板获取您的 API 密钥。

快速开始

Roam iOS SDK 使您能快速轻松地为您的 iOS 应用构建位置追踪器。我们提供强大且可定制的跟踪模式和功能，可用于收集您用户的地理位置更新。

要求

要使用 Roam SDK，您需要以下内容：注册一个免费的 Roam 账户。无需信用卡。

创建一个项目，并将 iOS 应用添加到该项目中。
您需要在项目设置中使用 SDK_KEY 来初始化 SDK。
现在您准备好将 SDK 集成到您的 iOS 应用中了。
Roam iOS SDK 需要 Xcode 10.0 或更高版本，且与目标 iOS 版本 10 及以上版本的应用兼容。

Xcode 设置

为了集成 Roam SDK，您需要一个 Roam 账户。

前往 Xcode > 文件 > 新建项目
配置信息属性列表文件 Info.plist，使用包含有关您的应用程序数据的 XML 片段。您需要在 Info.plist 文件中添加 NSLocationWhenInUseUsageDescription 的字符串，以便在请求前景位置权限期间提示用户。对于后台位置跟踪，您还需要在同一个 Info.plist 文件中添加 NSLocationAlwaysUsageDescription 和 NSLocationAlwaysAndWhenInUseUsageDescription 字符串。
```
<key>NSLocationWhenInUseUsageDescription</key>
<string>Add description for foreground only location usage.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Add description for background location usage. iOS 10 and below"</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Add description for background location usage. iOS 11 and above</string>
```
接下来，您需要在“项目设置” > “功能” > “后台模式”下启用 Background fetch 和 Location updates。

将 iOS SDK 包含到现有应用程序中

有几种方法可以将 Roam 移动 SDK 集成到您自己的项目中

Swift 包管理器
CocoaPods
Carthage（即将添加）
动态框架

Swift 包管理器安装

Swift 包管理器随 Xcode 发布。要开始将 AWS SDK 添加到您的 iOS 项目，请在 Xcode 中打开您的项目，选择文件 > Swift 包 > 添加包依赖项。

将 Roam SDK for iOS Swift Package Manager GitHub 仓库的 URL（https://github.com/roam-ai/roam-ios）输入到搜索栏中，然后单击下一步。

您将看到 SDK 的仓库规则，用于选择您想要 Swift Package Manager 安装的 SDK 版本。选择第一条规则，版本，选择“下次小版本更新”，因为它将使用从主分支检测到的最兼容的依赖项的最新版本，然后单击下一步。

选择所有合适的选项，然后单击完成。

您可以随时通过打开项目中Swift Packages标签来修改哪些SPM包包含在您的项目中。在Xcode导航器中单击项目文件，然后单击您的项目图标，然后选择Swift Packages标签。

CocoaPods Installation

按照以下步骤使用CocoaPods将SDK添加到项目中。在Podfile中添加以下内容：

pod 'roam-ios'

然后运行pod install。

这将添加Roam SDK及其依赖到您的项目中。Roam SDK依赖于CoreLocation、AWSMobileClient和AWSIoT来获取位置并将其传输到我们的服务器。SDK支持iOS 10及以上版本。

Manual Installation

如果您不熟悉使用CocoaPods或更喜欢手动安装，我们已将ZIP文件添加到SDK中。使用此链接下载Roam.zip文件。

解压该文件，并将Roam Roam.framework文件夹拖动到您的Xcode项目导航器中，添加到项目中。

您可以通过在Xcode窗口左侧的导航器中选择项目文件，然后转到“Linked Frameworks and Libraries”部分来完成此操作。从那里，单击“+”按钮添加Roam框架。您还希望添加以下框架，请参阅链接。

AWSAuthCore.xcframework
AWSCognitoIdentityProvider.xcframework
AWSCognitoIdentityProviderASF.xcframework
AWSCore.xcframework
AWSIoT.xcframework
AWSMobileClientXCF.xcframework

确保在“Linked Frameworks and Libraries”部分中选定的框架都被设置为Embed & Sign。

Initialize SDK

在AppDelegate文件中添加以下代码。这段代码导入SDK并允许SDK使用其他方法。

import Roam

导入后，在AppDelegate文件中的application(_:didFinishLaunchingWithOptions:)下添加以下代码。SDK必须在调用项目中使用您的发布密钥的任何其他SDK方法之前进行初始化。

Roam.initialize("YOUR-SDK-KEY-GOES-HERE")

创建用户

SDK 初始化后，您需要创建或获取一个用户开始跟踪并使用其他方法。每个创建的用户都将有一个唯一的 Roam 标识符，该标识符用于登录和访问开发者 API。我们称之为 Roam user_Id。

Roam.createUser("YOUR-USER-DESCRIPTION-GOES-HERE") {(RoamUser, Error) in
            // Access Roam user data below
            // RoamUser?.userId
            // RoamUser?.description
            // RoamUser?.locationListener
            // RoamUser?.eventsListener
            // RoamUser?.locationEvents
            // RoamUser?.geofenceEvents
            // RoamUser?.tripsEvents
            // RoamUser?.nearbyEvents
            
            // Access error code & message below
            // Error?.code
            // Error?.message
        }

“用户描述”选项可用来更新用户信息，如姓名、地址或添加现有用户 ID。如果您打算保存个人资料信息（如电子邮件或电话号码），请确保信息已被加密。

您可以使用下面的代码随时设置或更新用户描述。

Roam.setDescription("SET-USER-DESCRIPTION-HERE")

获取用户

如果您已经有一个 Roam user_ID 是您要重用的，而不是创建新用户，请使用下面的代码来获取用户会话。

Roam.getUser("YOUR-ROAM-USER-ID") {(RoamUser, Error) in
            // Access Roam user data below
            // RoamUser?.userId
            // RoamUser?.description
            // RoamUser?.locationListener
            // RoamUser?.eventsListener
            // RoamUser?.locationEvents
            // RoamUser?.geofenceEvents
            // RoamUser?.tripsEvents
            // RoamUser?.nearbyEvents
            
            // Access error code & message below
            // Error?.code
            // Error?.message
        }

请求权限

在开始位置跟踪之前，您需要请求用户同意您的应用程序访问位置信息。

在 AppDelegate 文件顶部导入 CoreLocation。
```
import CoreLocation
```
为位置管理器声明以下类，并在 application(_:didFinishLaunchingWithOptions:) 的返回语句之前添加此行代码。这一行代码会要求用户允许应用程序在后台和前台访问位置数据。
```
let locationManager = CLLocationManager()
locationManager.requestLocation()
```

SDK 配置

精确度引擎

为启用被动、主动和平衡跟踪的精确度引擎。

Roam.enableAccuracyEngine()

对于自定义跟踪，您可以传递25-150米范围内的整数作为所需的精确度值。

Roam.enableAccuracyEngine(50)

禁用精确度引擎

Roam.disableAccuracyEngine()

离线位置跟踪

要修改默认启用的离线位置跟踪配置。

Roam.offlineLocationTracking(true)

位置跟踪

开始跟踪

使用以下跟踪模式的同时使用 startTracking 方法 Roam.startTracking

跟踪模式

现在您可以开始跟踪您的用户。Roam提供了三种默认跟踪模式，以及一个自定义版本。它们根据位置更新的频率和电池消耗不同。频率越高，电池消耗越大。

模式	电池使用	每	优化/建议用于
主动	6% - 12%	25 ~ 250米	出租车/共享出行
平衡	3% - 6%	50 ~ 500米	叫车服务
被动	0% - 1%	100 ~ 1000米	社交应用

//active tracking
Roam.startTracking(RoamTrackingMode.active)
// balanced tracking
Roam.startTracking(RoamTrackingMode.balanced)
// passive tracking
Roam.startTracking(RoamTrackingMode.passive)

自定义跟踪模式

SDK还提供了一个自定义跟踪模式，允许您根据需求自定义并构建自己的跟踪模式。

类型	单位	单位范围
距离间隔	米	1m ~ 2500m

位置更新间的距离示例代码

// Define a custom tracking method
let trackingMethod = RoamTrackingCustomMethods()

// Update the settings for the created method as per need
trackingMethod.activityType = .fitness
trackingMethod.pausesLocationUpdatesAutomatically = true
trackingMethod.showsBackgroundLocationIndicator = true
trackingMethod.useSignificant = false
trackingMethod.useRegionMonitoring = false
trackingMethod.useVisits = false
trackingMethod.accuracyFilter = 10
trackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters

// Update the distance intervel as per the use case in meters
trackingMethod.distanceFilter = 10

// Start the tracking with the above created custom tracking method
Roam.startTracking(.custom, options: trackingMethod)

位置更新间的时时间间示例代码

// Define a custom tracking method
let trackingMethod = RoamTrackingCustomMethods()

// Update the settings for the created method as per need
trackingMethod.activityType = .fitness
trackingMethod.pausesLocationUpdatesAutomatically = true
trackingMethod.showsBackgroundLocationIndicator = true
trackingMethod.useSignificant = false
trackingMethod.useRegionMonitoring = false
trackingMethod.useVisits = false
trackingMethod.accuracyFilter = 10
trackingMethod.desiredAccuracy = .kCLLocationAccuracyNearestTenMeters

// Update the time intervel as per the use case in seconds
trackingMethod.updateInterval = 10

// Start the tracking with the above created custom tracking method
Roam.startTracking(.custom, options: trackingMethod)

停止跟踪

要停止跟踪，请使用以下方法。

Roam.stopTracking()

发布消息

它将发布位置数据，这些数据将被发送到 roam-ios 服务器以进行进一步处理，并将保存到我们的数据库服务器中。

let locationData = RoamPublish()
Roam.publishSave(locationData)

停止将位置数据发布给其他客户端。

Roam.stopPublishing()

订阅消息

现在已经启用了位置监听器，请使用以下方法订阅您自己的或其他用户的地理位置更新和事件。

取消订阅

Roam.unsubscribe(TYPE, "ROAM-USER-ID")

类型	描述
RoamSubscribe.Events	订阅您自己的事件。
RoamSubscribe.Location	订阅您自己的位置（或）其他用户的位置更新。
RoamSubscribe.Both	订阅您自己的事件和位置（或）其他用户的位置更新。

监听器

现在已经设置了位置跟踪，您可以订阅位置和事件，并在设备本地或直接发送到您的后端服务器上使用这些数据。

为此，您需要将位置和事件监听器设置为 true。默认情况下，状态将设置为 false，需要将其设置为 true 以将位置和事件更新流式传输到同一设备或其他设备。

Roam.toggleListener(Events: true, Locations: true) {(RoamUser, Error) in
            // Access Roam user data below
            // RoamUser?.userId
            // RoamUser?.description
            // RoamUser?.locationListener
            // RoamUser?.eventsListener
            // RoamUser?.locationEvents
            // RoamUser?.geofenceEvents
            // RoamUser?.tripsEvents
            // RoamUser?.nearbyEvents
            
            // Access error code & message below
            // Error?.code
            // Error?.message
        }

一旦将监听器切换设置为 true，要监听位置更新，请创建一个实现 RoamDelegate 的类，然后调用 Roam.delegate。

将在背景中初始化和执行的代码路径中设置您的 RoamDelegate。例如，让您的 AppDelegate 实现 GeoSparkDelegate，而不是 ViewController。AppDelegate 将在后台初始化，而 ViewController 可能不会。

import UIKit
import Roam
import CoreLocation

@main
class AppDelegate: UIResponder, UIApplicationDelegate, RoamDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Roam.delegate = self
        Roam.initialize("YOUR-SDK-KEY-GOES-HERE")
        return true
    }
    func didUpdateLocation(_ location: RoamLocation) {
        // Do something with the user location
    }
    func didReceiveEvents(_ events: RoamEvents) {
        // Do smoething with user events
    }
    func didReceiveUserLocation(_ location: RoamLocationReceived) {
        // Do something with location of other users' subscribed location
    }

示例

在 Example/ 中看到一个 Swift 示例应用。要运行示例应用，克隆此存储库，在 AppDelegate.swift 中添加您的 sdk "YOUR-SDK-KEY" 键，并构建应用。

需要帮助？

如果您在我们的 SDK 上遇到任何问题或问题，请随时创建 GitHub 问题或在该页面上提交请求：Roam 帮助。

roam-ios 0.1.26

roam-ios 0.1.26

roam-ios 0.1.26

官方 Roam iOS SDK

快速开始

要求

Xcode 设置

将 iOS SDK 包含到现有应用程序中

Swift 包管理器安装

CocoaPods Installation

Manual Installation

Initialize SDK

创建用户

获取用户

请求权限

SDK 配置

精确度引擎

离线位置跟踪

位置跟踪

开始跟踪

跟踪模式

自定义跟踪模式

停止跟踪

发布消息

订阅消息

订阅

取消订阅

监听器

示例

需要帮助？