MileusWatchdogKit 2.1.0

MileusWatchdogKit 2.1.0

×

由 Mileus、SKOUMAL, s.r.o.、SKOUMAL STUDIO 维护。

MileusWatchdogKit 2.1.0

  • 作者：
  • Mileus

Mileus Watchdog 的 iOS SDK

Carthage compatible Pods compatible SPM compatible Platform Swift Version

此库支持通过 Mileus 进行异步后台搜索旅途计划，基本用例是从用户的当前位置通勤回家。

请参阅 Watchdog 搜索文档 了解更多关于功能的信息，或查阅 SDK 文档 了解更多关于此 SDK 的使用信息。

要求

  • iOS 11.0+
  • Xcode 11.0+
  • Swift 5.0+

安装

Carthage

github "mileus/watchdog-sdk-ios" ~> 2.1.0

Cocoapods

pod 'MileusWatchdogKit', '~> 2.1.0'

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/mileus/watchdog-sdk-ios.git", .upToNextMajor(from: "2.1.0"))
]

配置

首先，您需要在您的 AppDelegate.application(:, didFinishLaunchingWithOptions:) 中配置 Mileus SDK

MileusWatchdogKit.configure(
    partnerName: String, // Unique partner identifier
    accessToken: String, // Token from Watchdog Auth API
    environment: MileusWatchdogEnvironment // Environment type (staging or production)
) // throws exception (MileusWatchdogError.invalidInput) if partnerName or accessToken is an empty string

迁移

1.0.2 -> 2.1.0

Mileus Watchdog Search

更新位置的方法已经被一个通用方法所替换

// 1.0.2
func updateOrigin(location: MileusWatchdogLocation)
func updateDestination(location: MileusWatchdogLocation)

// 2.0.0
func update(location: MileusWatchdogLocation, type: MileusWatchdogSearchType)
func update(searchData: MileusWatchdogSearchData)

Mileus Watchdog Search Data

这种结构已经被修改为通用。我们移除了原点属性和目的地属性，并添加了通用位置属性。

// 1.0.2
struct MileusWatchdogSearchData {
    let type: MileusWatchdogSearchType
    let origin: MileusWatchdogLocation
    let destination: MileusWatchdogLocation
}

// 2.0.0
struct MileusWatchdogSearchData {
    let type: MileusWatchdogSearchType
    let location: MileusWatchdogLocation
}

使用说明

启动 Mileus Watchdog 屏幕

这是 Mileus Watchdog 的一个通用入口点。使用它来初始化新的搜索，以及从通知中打开 Mileus Watchdog。

只要你需要它，就必须保持对 mileusWatchdogSearch 实例的引用。

let mileusWatchdogSearch = MileusWatchdogSearch(
    delegate: MileusWatchdogSearchFlowDelegate,
    origin: MileusWatchdogLocation? = nil, 
    destination: MileusWatchdogLocation? = nil 
) // throws exception (MileusWatchdogError.instanceAlreadyExists) if you have already created an instance or exception (MileusWatchdogError.sdkIsNotInitialized) if you have not initialized sdk yet.

显示 Mileus Watchdog 屏幕

let mileusVC = mileusWatchdogSearch.show(from: UIViewController)

搜索流程代理

Flow Delegate 的方法总是在主线程上调用。

protocol MileusWatchdogSearchFlowDelegate {
    func mileus(_ mileus: MileusWatchdogSearch, showSearch data: MileusWatchdogSearchData)
    func mileusShowTaxiRide(_ mileus: MileusWatchdogSearch)
    func mileusShowTaxiRideAndFinish(_ mileus: MileusWatchdogSearch)
    func mileusDidFinish(_ mileus: MileusWatchdogSearch)
    func mileusDidFinish(_ mileus: MileusWatchdogSearch, with error: MileusWatchdogError)
}

搜索出发点或目的地

func mileus(_ mileus: MileusWatchdogSearch, showSearch data: MileusWatchdogSearchData)

当它被调用时，您应该打开您的搜索视图控制器。

根据用户的选项更新出发点或目的地

mileusWatchdogSearch.update(location: MileusWatchdogLocation, type: MileusWatchdogSearchType)

或

mileusWatchdogSearch.update(searchData: MileusWatchdogSearchData)

打开出租车行程 Activity

func mileusShowTaxiRide(_ mileus: MileusWatchdogSearch)

当它被调用时，您应该打开您的出租车行程视图控制器。

打开出租车行程并结束

func mileusShowTaxiRideAndFinish(_ mileus: MileusWatchdogSearch)

当它被调用时，您应该关闭 mileusVC 并打开您的出租车行程视图控制器。调用 mileusWatchdogSearch.show(from:) 后，您将获得 mileusVC。

完成

func mileusDidFinish(_ mileus: MileusWatchdogSearch)

您负责关闭 mileusVC。您在调用 mileusWatchdogSearch.show(from:) 之后获得 mileusVC。

启动 Mileus 单次搜索屏幕

这是一个针对单次搜索的特殊入口点。您只需要初始化 Mileus SDK 并使用以下方法之一来打开单次搜索。如果后端未准备好，请不要打开单次搜索。

只要您需要，就必须保持对 mileusOneTimeSearch 实例的引用。

let mileusOneTimeSearch = MileusOneTimeSearch(
    delegate: MileusOneTimeSearchFlowDelegate, explanationDialogKey: String)
) // throws exception (MileusWatchdogError.instanceAlreadyExists) if you have already created an instance or exception (MileusWatchdogError.sdkIsNotInitialized) if you have not initialized sdk yet.

显示 Mileus 单次搜索屏幕

let mileusVC = mileusOneTimeSearch.show(from: UIViewController)

单次搜索流程代理

Flow Delegate 的方法总是在主线程上调用。

protocol MileusOneTimeSearchFlowDelegate {
    func mileusDidFinish(_ mileus: MileusOneTimeSearch)
    func mileusDidFinish(_ mileus: MileusOneTimeSearch, with error: MileusWatchdogError)
    func mileusShowTaxiRide(_ mileus: MileusOneTimeSearch)
    func mileusShowTaxiRideAndFinish(_ mileus: MileusOneTimeSearch)
}

完成

func mileusDidFinish(_ mileus: MileusOneTimeSearch)

您负责关闭 mileusVC。您在调用 mileusOneTimeSearch.show(from:) 之后获得 mileusVC。

带有错误完成

func mileusDidFinish(_ mileus: MileusMarketValidation, with error: MileusWatchdogError)

您永远不会触发这个调用。您会收到错误信息，其中说明错误发生的原因。

启动 Mileus 市场验证屏幕

针对市场验证目的的特殊入口点。在此模式下，不会调用任何回调函数。您只需初始化 Mileus SDK 并使用以下方法之一打开市场验证界面。

只要您需要，就必须保留对 mileusMarketValidation 实例的引用。

let mileusMarketValidation = MileusMarketValidation(
    delegate: MileusMarketValidationFlowDelegate,
    origin: MileusWatchdogLocation, 
    destination: MileusWatchdogLocation 
) // throws exception (MileusWatchdogError.instanceAlreadyExists) if you have already created an instance or exception (MileusWatchdogError.sdkIsNotInitialized) if you have not initialized sdk yet.

显示 Mileus 市场验证界面

let mileusVC = mileusMarketValidation.show(from: UIViewController)

市场验证流程代理

Flow Delegate 的方法总是在主线程上调用。

protocol MileusMarketValidationFlowDelegate {
    func mileusDidFinish(_ mileus: MileusMarketValidation)
}

完成

func mileusDidFinish(_ mileus: MileusMarketValidation)

您负责关闭 mileusVC。在调用 mileusMarketValidation.show(from:) 后，您会获得 mileusVC。

开始 Mileus 监视狗调度屏幕

这是打开监视狗调度屏幕的入口点。用于从用户界面以及从通知打开监视狗调度。您可以选择传递家庭住址作为目的地，如果您的应用程序允许选择一个，否则该功能本身将允许用户选择。它将仅用作默认值，用户仍可以在功能内选择不同的值。

只要您需要，就必须保留对 mileusScheduler 实例的引用。

let mileusScheduler = MileusWatchdogScheduler(
	delegate: MileusMarketValidationFlowDelegate,
    homeLocation: MileusWatchdogLocation? = nil
) // throws exception (MileusWatchdogError.instanceAlreadyExists) if you have already created an instance or exception (MileusWatchdogError.sdkIsNotInitialized) if you have not initialized sdk yet or (MileusWatchdogError.insufficientLocationPermission) if the app does not have sufficient location permissions.

显示 Mileus 监视狗调度屏幕

let mileusSchedulerVC = mileusScheduler.show(from: UIViewController)

监视狗调度流程代理

Flow Delegate 的方法总是在主线程上调用。

protocol MileusWatchdogSchedulerFlowDelegate {
    func mileus(_ mileus: MileusWatchdogScheduler, 
        	     showSearch data: MileusWatchdogSearchData)
    func mileusDidFinish(_ mileus: MileusWatchdogScheduler)
}

搜索起点或终点

func mileus(_ mileus: MileusWatchdogScheduler, showSearch data: MileusWatchdogSearchData)

当它被调用时，您应该打开您的搜索视图控制器。

更新家庭地址

mileusSchedulerVC.updateHome(location: MileusWatchdogLocation)

完成

func mileusDidFinish(_ mileus: MileusWatchdogScheduler)

后台位置同步

我们使用前台服务来在计划中的看门狗准备启动时发起用户位置的同步。调用此方法以启动服务。在调用此方法之前，请从用户那里获得适当的位置权限。此外，在调用它之前，请确保您已设置Info.plist中的位置权限文本，否则您的应用会崩溃。

let locationSync = MileusWatchdogLocationSync() // throws exception (MileusWatchdogError.insufficientLocationPermission) if the app does not have sufficient location permissions.

locationSync.start(completion:)

样式

当您调用show(from:)方法时，它返回 UINavigationController。您可以完全访问UIKit元素，例如navigationBar或navigationItem等。请根据需要自由定制。

如果您更改或删除导航项中的某些内容，例如按钮或标题，您对此更改及 SDK UI 在此更改后的正常工作负责。

示例

let navigationController = show(from: yourCurrentViewController)
// Transparent bar background colour
navigationController.navigationBar.backgroundColor = .red 
// Solid bar background colour
navigationController.navigationBar.barTintColor = .green
// Bar buttons colour
navigationController.navigationBar.tintColor = .blue
// Title font and colour
navigationController.navigationBar.titleTextAttributes = 
[
NSAttributedString.Key.font : UIFont.systemFont(ofSize: 18.0),
	NSAttributedString.Key.foregroundColor : UIColor.orange
]

模型

类

Mileus 监视犬搜索

class MileusWatchdogSearch {
    init(delegate: MileusWatchdogSearchFlowDelegate, 
        origin: MileusWatchdogLocation? = nil, 
        destination: MileusWatchdogLocation? = nil
    )

    func show(from: UIViewController) -> UIViewController
    func update(location: MileusWatchdogLocation, type: MileusWatchdogSearchType)
    func update(searchData: MileusWatchdogSearchData)
}

Mileus 单次搜索

class MileusOneTimeSearch {
    init(delegate: MileusOneTimeSearchFlowDelegate, 
        explanationDialogKey: String
    )
    func show(from: UIViewController) -> UIViewController
}

Mileus 市场验证

class MileusMarketValidation {
    init(delegate: MileusMarketValidationFlowDelegate, 
        origin: MileusWatchdogLocation, 
        destination: MileusWatchdogLocation
    )

    func show(from: UIViewController) -> UIViewController
}

Mileus 监视犬调度器

class MileusWatchdogScheduler {
    init(delegate: MileusWatchdogSchedulerFlowDelegate, 
        homeLocation: MileusWatchdogLocation? = nil, 
    )
    
    func show(from: UIViewController) -> UINavigationController
    func updateHome(location: MileusWatchdogLocation)
}

Mileus 监视犬位置同步

class MileusWatchdogLocationSync {
    init()
    
    
    func start(completion: CompletionHandler? = nil)
    func stop()
}

委托人

Flow Delegate 的方法总是在主线程上调用。

搜索流程委托

protocol MileusWatchdogSearchFlowDelegate {
    func mileus(_ mileus: MileusWatchdogSearch, showSearch data: MileusWatchdogSearchData)
    func mileusShowTaxiRide(_ mileus: MileusWatchdogSearch)
    func mileusShowTaxiRideAndFinish(_ mileus: MileusWatchdogSearch)
    func mileusDidFinish(_ mileus: MileusWatchdogSearch)
    func mileusDidFinish(_ mileus: MileusWatchdogSearch, with error: MileusWatchdogError)
}

单次搜索流程委托

protocol MileusOneTimeSearchFlowDelegate {
    func mileusDidFinish(_ mileus: MileusWatchdogSearch)
    func mileusDidFinish(_ mileus: MileusWatchdogSearch, with error: MileusWatchdogError)
}

市场验证流程委托

protocol MileusMarketValidationFlowDelegate {
    func mileusDidFinish(_ mileus: MileusMarketValidation)
}

Mileus看门狗调度流程委托

protocol MileusWatchdogSchedulerFlowDelegate {
    func mileus(_ mileus: MileusWatchdogScheduler, 
        	     showSearch data: MileusWatchdogSearchData)
    func mileusDidFinish(_ mileus: MileusWatchdogScheduler)
}

数据

搜索数据

struct MileusWatchdogSearchData {
    let type: MileusWatchdogSearchType
    let location: MileusWatchdogLocation
}

位置

struct MileusWatchdogLocation {
    let address: String
    let latitude: Double
    let longitude: Double
    let accuracy: Float
    
    init(address: String, 
         latitude: Double, 
         longitude: Double, 
         accuracy: Float = 0.0)
}

枚举

环境

enum MileusWatchdogEnvironment {
    case development
    case staging
    case production
}

搜索类型

enum MileusWatchdogSearchType {
    case origin
    case destination
    case home
}

错误

enum MileusWatchdogError: Error {
    case invalidInput
    case instanceAlreadyExists
    case sdkIsNotInitialized
    case insufficientLocationPermission
    case fatalInvalidState(message: String)
    case unknown
}

SDK结构内部类图

Internal Class Diagram of SDK structure