MotusSDK 6.1.1

MotusSDK 6.1.1

×

许可 商用
已发布最后发布2023年9月

由 Antonio Pagano、Ezequiel、Edwin Polo、KOBY_VILLALOBOS 维护。

MotusSDK 6.1.1

Motus SDK

Build Status

MotusSDK 提供了访问 Motus iOS 应用核心功能的方法，包括通过手机/平板的 GPS 路程跟踪，SDK 通过 Cocoapods 分发，供希望添加行程跟踪功能的应用使用。

安装

Cocoapods

在 XCode 项目中创建 Podfile

在 XCode 项目目录中创建一个名为 Podfile 的文本文件，或者打开一个终端窗口，并在项目目录中使用 $ pod init 命令创建 Podfile。

将 MotusSDK 依赖项添加到 Podfile 中

其外观可能如下所示

target 'MyApp' do
  pod 'MotusSDK'
end

安装 MotusSDK Pod

打开一个终端窗口，并在 Xcode 项目目录中运行 pod install 命令

$ pod install

运行 pod install 后，打开在 XCode 项目目录中创建的 MyApp.xcworkspace 文件。

配置 SDK 应用权限

Motus SDK 需要配置 位置更新 背景模式，要设置此模式，请进入 XCode 项目设置，在 功能 选项卡内，在 后台模式 中检查 位置更新 复选框。

配置 info.plist

为了使位置和日志记录功能正常工作，请将以下键设置到您的 info.plist 中

  • NSLocationAlwaysUsageDescription

在这里添加一些描述，说明您的应用如何使用位置。

为了这样做，请进入您的 XCode 项目设置，在 信息 选项卡下，在 自定义 iOS 目标属性 中添加上述键及其相应的值。

SDK 使用

配置 AppDelegate

您的应用需要进行一些操作，以确保 Motus 为正常运行，请按照以下说明操作，以确保您的 AppDelegate 已配置为使用 Motus SDK

  • 在 AppDelegate 中导入 MotusSDK
import MotusSDK
  • 将 MotusSDK 对象的实例添加到 AppDelegate
var motus : MotusSDK = MotusSDK.withCredentials("[appId]", secret: "[motus provided secret]")
  • 在 func application(_ application: UIApplication, didFinishLaunchingWithOptions... 方法中对其进行初始化
let config = MotusConfiguration(username: "[username]", groupId: "[userGroupID]")
config.delegate = YourApplicationMotusDelegate()
self.motus.setup(config)

设置将根据传递给它的 MotusConfiguration 初始化 SDK，（请参阅 MotusConfiguration）。

重要：如果您的原因（例如，当您的应用处于后台时，您无法访问加密设置）导致您传递了空状态，则 SDK 将记住您最后传递的设置并使用它们，否则将使用默认值。

这样一来，您的应用就准备好开始使用 Motus SDK 了。从 AppDelegate 中，您可以通过使用 sharedApplication 方法从 UIApplication 的单例方法中获取刚设置好的 Motus SDK 实例，如下所示

let delegate : AppDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
delegate.motus.mileage.trips(responseHandler: { trips, error in
  if error != nil {
    logw("| Sample: \(error!)")
    return
  }

  logw("| Trips from motus -> \(trips)")
})

在上面的示例中，我们调用了当天的行程，此方法将获取您的行程并将其传递给作为参数传递的 responseHandler。

SDK 配置

SDk 允许宿主应用根据自身需求配置设置，例如用来确定停止的时间等配置值。这些值是 SDK 在运行设置时接收到的 MotusConfiguration 对象中的属性。

MotusConfiguration 包含以下对用户体验重要的属性：

username (默认 "")

现行用户的标识。

groupId (默认 "")

现行用户的 groupId。

trackingMode (默认 .Manual)

SDK 支持 3 种跟踪模式 (.Manual, .BusinessHours, .Off)，该属性允许宿主应用定义跟踪模式。

.Manual 模式仅在宿主应用调用 motus.mileage.startTracking 并在宿主应用调用 motus.mileage.stopTracking 之间跟踪行程。

.BusinessHours 将在 MotusConfiguration.businessConfiguration 定义的营业时间内跟踪行程。

.Off 不会跟踪任何行程，并旨在适用于您的应用中可选跟踪行程的情况，除非用户实际跟踪，否则不需要请求跟踪行程所需的权限。

autoStopThreshold (默认 300s)

这是应用将用于确定用户是否停止的时间。

默认情况下，SDK 使用 5 分钟（300 秒）作为停止阈值，但在需要的情况下，配置功能时可以配置此值。

//Inside your application AppDelegate
var config = MotusConfiguration(username: "FINAL_USERNAME", groupId: "[PROVIDED_GROUP_ID]")
config.autoStopThreshold = 600.0
self.motus.setup(config)

businessConfiguration (默认每天 9:00 - 17:00)

当使用 .BusinessHours 跟踪模式时，这是 SDK 将捕获行程的时间，在此时间之外，行程将不会自动捕获，而需要用户手动开始（如果您的应用提供了相应的用户体验）。

要使用 Motus 营业时间，应按以下方式调用设置函数：

//Setting a configuration for a user that works:
//Monday 9:00 A.M. - 12:00 M
//Wednesday 8:00 A.M. - 6:00 P.M.
//Friday 8:00 A.M. - 12:00 M.

var config = MotusConfiguration(username: "FINAL_USERNAME", groupId: "[PROVIDED_GROUP_ID]")
config.trackingMode = .BusinessMode
config.businessConfiguration =  [
  Workday(weekDay: Weekday.Monday, startHour: "09:00", endHour: "12:00" ),
  Workday(weekDay: Weekday.Tuesday, enabled: false ),
  Workday(weekDay: Weekday.Wednesday, startHour: "08:00", endHour: "18:00" ),
  Workday(weekDay: Weekday.Thursday, enabled: false ),
  Workday(weekDay: Weekday.Friday, startHour: "08:00", endHour: "12:00" ),
  Workday(weekDay: Weekday.Saturday, enabled: false ),
  Workday(weekDay: Weekday.Saturday, enabled: false )
]

self.motus.setup(config)

connectPreviousTrip (默认 false)

启用此设置后，如果先前的行程结束位置距离开始位置一英里之内，则会将任何开始行程与其前驱行程连接起来。

commuteDeduction (默认 nil)

这里是宿主应用传递通勤减税配置的地方，即知道行程是否将被标记为通勤的逻辑。

要使用此属性，您可以在配置中实例化一个 CommuteDeduction 对象并传递它，例如

config.commuteDeduction = CommuteDeduction()

通过设置此属性，SDK 将使用 Trip 对象中的 commute 属性标记行程（结束之后）。

delegate (默认 nil)

为了在 SDK 中传达事件，如行程开始或结束，SDK 提供了一个名为 MotusDelegate 的协议。

SDK 预期宿主应用程序传递一个实现此方法的对象，以便 SDK 在 SDk 事件发生时调用对象上的协议方法。

MotusDelegate 为宿主应用提供了一个接口，以便在 SDK 上监听事件并对事件的结果进行操作。

一个简单的代理实现示例如下

class MyAppMotusDelegate : MotusDelegate {
  func tripStarted(trip: Trip) {}
  func tripUpdated(trip: Trip) {}
  func tripsUpdated(trip: Trip) {}
  func locationPermissionsChanged(status: CLAuthorizationStatus){}
  func tripEnded(trip: Trip)
  func batteryDegraded(reading: Double)
  func businessHoursStarted()
  func businessHoursEnded()

  func distanceUpdated(distance : Double){
    print("Today's distance updated to: \(distance) meters!.")
  }
}

为了使 SDK 知道这个实现，宿主应用应将我们的 motus sdks 实例字段 'delegate' 赋予我们的实现的一个实例

motusInstance.delegate = MyAppMotusDelegate()

重要：如果您的应用未传递实现 MotusDelegate 协议的实例，SDK 将无法通知您的应用任何在 SDk 上下文中发生的事情。

debug (默认为 nil)

此设置告诉 SDK 是否将日志写入到 Documents/Logs/ 中的文件。

配置 SDK

如您在安装部分所见，要设置 SDK，您需要使用配置，如下例所示

var config = MotusConfiguration(username: "FINAL_USERNAME", groupId: "[PROVIDED_GROUP_ID]")
self.motus.setup(config)

然而，setup 的目的是在应用完成启动后使用，有时您需要根据应用的用户交互或其他业务特定行为来更改应用中的某些内容。

无论何时您需要更改配置，您都应该调用 updateConfiguration 方法。

//In AppDelegate.swift
var motus : MotusSDK = MotusSDK.withCredentials("[appId]", secret: "[motus provided secret]")
let configuration : MotusConfiguration = MotusConfiguration(username: "[username]", groupId: "[groupID]")

//In other class within your app
//Lets asume this function will be called in your app when businessHours was changed.
func userChangedBusinessHours(workdays: [Workday]) {
  let appDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
  let config = appDelegate.configuration

  config.businessConfiguration = workdays
  appDelegate.motus.updateConfiguration(config)
}

SDK 存储空间

SDK 使用安全磁盘机制来存储行程和设置，使用 AES-256 对文件进行加密并保存到磁盘上，所有 SDK 存储的设置/行程都保存到 Documents/motus/settings.mo，该文件只能由 motus SDK 打开，并且在其外部不可读。

常见问题

如何将 SDK 重置为出厂设置？

MotusSDK 提供了一个将 MotusSDK 重置为出厂设置的功能。您可以通过调用 clearSettings 函数来实现这一点。

let delegate : AppDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
delegate.motus.clearSettings()

我如何使用 Motus SDK 在我的应用程序中跟踪行程？

MotusMileage 类提供了在主机应用程序中跟踪里程的方法，它使用 iOS locationManager 来检测行程的开始和结束，为此，主机应用程序（您的应用程序）需要在应用程序代理上的设置中调用 Motus SDK 共享实例中的 startTracking 方法。

//Inside some button action or other:
let delegate : AppDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
delegate.motus.mileage.startTracking()

这样我们就是在告诉 Motus SDK 开始检查行程开始的条件。

另一方面，一旦我们的应用程序不再需要跟踪行程，我们可以调用 stopTracking 方法，以防止我们在不需要跟踪行程时浪费电量。

//Inside some button action or other:
let delegate : AppDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
delegate.motus.mileage.stopTracking()

如何获取当天的行程列表？

获取当天的行程列表有两种选择

  • 获取最新的本地行程列表（经常与服务器同步）

为此，我们将使用 MotusMileage 实例，通过调用它的 trips() 方法。

let delegate : AppDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
let trips : [Trip] = delegate.motus?.mileage().trips()
  • 让 SDK 从服务器获取行程列表并将其与本地行程同步

为了获取此行程列表并触发服务器同步，我们需要将一个 responseHandler 传递给 trips() 方法，此 responseHandler 将在同步过程中与同步行程的列表或错误一起调用。

let delegate : AppDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
delegate.motus.mileage.trips(responseHandler: { trips, error in
  if error != nil {
    logw("| Sample: \(error!)")
    return
  }

  logw("| Trips -> \(trips)")

  self.trips = trips;
})

如何获取特定日期的行程列表？

您可以通过将格式化的日期传递给 trips() 方法来获取过去一天的行程列表。此调用将需要服务器调用，因此我们还需要传递一个 responseHandler。

let delegate : AppDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
delegate.motus.mileage.trips(forDate: "2016-02-20",responseHandler: { trips, error in
  if error != nil {
    logw("| Sample: \(error!)")
    return
  }

  logw("| Trips -> \(trips)")
  self.trips = trips;
})

如何删除一天的行程？

Motus 在 MotusMileage 类中提供了重置功能，该功能可以删除给定日期标识符的行程。

例如，如果您想删除 2016 年 12 月 28 日的行程，这是所需的代码

let delegate : AppDelegate = UIApplication.sharedApplication().delegate as! AppDelegate
delegate.motus.mileage.reset(identifier : “2016-12-28”,  responseHandler : { trips, error
  if error != nil {
    print(“ | A good error \(error)”)
    //Handle error
  }
  print(“| Trips from 2016-12-28 -> \(trips)")
})

如何从 1.1.3 迁移到 2.0.0？

2.0.0 更改了 Motus SDK 跟踪行程的方式，我们实现了一些启发式方法，使 SDK 能够更有效地跟踪行程，同时保持相同的质量和稳定电源消耗；这都需要更少的后台权限。

如果您当前的应用程序正在使用 1.1.3，以下列表应有助于您无问题地设置 SDK 的 2.0.0 版本。

  1. 将 Podfile 中 MotusSDK pod 的版本更改为 2.0.0。
  2. 从您的应用程序需要的能力中删除背景音频权限。
  3. 在您的 func applicationWillTerminate(_ application: UIApplication) { 中添加以下内容：
self.motus.willTerminate()
  1. 如果您的应用程序将 config.desiredAccuracy 设置为 .Medium 或 .High，则请删除设置它的行，2.0.0 只有一个精度模式，并且由于主机应用程序不再能够更改它。
  2. 如果意外地将 UIFileSharingEnable 属性设置为 YES，现在您可以禁用它，除非您的应用程序使用它用于其他目的。

版权

© 2016 Motus LLC