Karhoo iOS Network SDK
KarhooSDK 是一个用于集成 KarhooAPI 的框架：https://developer.karhoo.com
安装
CocoaPods
您可以通过将 KarhooSDK 添加到您的 Podfile 来使用 CocoaPods 进行安装
use_frameworks!
pod 'KarhooSDK', '~> 1.8.0'然后在您想要访问 Karhoo 服务的任何地方导入 KarhooSDK
import KarhooSDKCarthage
创建一个包含框架的Cartfile，并执行carthage update。按照说明，将$(SRCROOT)/Carthage/Build/iOS/YourLibrary.framework添加到iOS项目中。
github "Karhoo/Karhoo-ios-sdk"
Swift Package Manager
Swift Package Manager（Swift包管理器）是一个自动化分发Swift代码的工具，并集成到swift编译器和Xcode 11及其以后版本中。
一旦您的Swift包设置完成，将Karhoo作为一个依赖项添加，就像将其添加到Package.swift中的dependencies值一样简单。
dependencies: [
.package(url: "https://github.com/Karhoo/karhoo-ios-sdk.git", .upToNextMajor(from: "1.8.0"))
]用法
初始化
在您开始之前，SDK需要知道一些信息。例如要连接的环境或要使用的认证方式。这些依赖项可以在实现KarhooSDKConfiguration协议中设置。
import KarhooSDK
struct YourCompanyKarhooConfiguration: KarhooSDKConfiguration {
func environment() -> KarhooEnvironment {
return .sandbox
}
func authenticationMethod() -> AuthenticationMethod {
// for other authentication methods such as guest or token exchange bookings please see: https://developer.karhoo.com/docs/using-the-network-sdk#authentication
return .karhooUser
}
}使用此配置，SDK可以在您的App/SceneDelegate中初始化。
import KarhooSDK
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Karhoo.set(configuration: YourCompanyKarhooConfiguration())
..
return true
}
}有关SDK服务的完整文档，请访问我们的开发者门户：https://developer.karhoo.com/reference#user-service
认证
KarhooSDK 需要进行身份验证，未经验证就与 SDK 交互会导致错误。该 SDK 支持三种身份验证方法：
Karhoo 用户
在 Karhoo 平台上创建和管理的主用户。Karhoo 用户对于企业差旅和概念验证集成非常有用。将您的 KarhooSDKConfiguration 接口身份验证方法设置为 .karhooUser。然后您可以使用 UserService 使用用户名和密码发起登录请求。
let userService = Karhoo.getUserService()
let userLogin = UserLogin(email: "[email protected]", password: "abc")
userService.login(userLogin: userLogin).execute { result in
switch result {
case .success(let user):
print("user authenticated: ", user)
case .failure(let error):
print("error: \(error.code) \(error.message)")
}
}来访者用户
来访者用户是无名的，适用于 B2C 旅行者解决方案。以来访者用户身份预订时，您的应用程序用户不需要进行身份验证，但当使用行程服务做预订时，您需要提供乘客详情。要将 SDK 设置为访客模式，请在您的 KarhooSDKConfiguration 接口中指定身份验证方法为 .guest 并提供相应的凭据。之后，您就可以与 SDK 服务交互。
struct YourCompanyKarhooConfiguration: KarhooSDKConfiguration {
func environment() -> KarhooEnvironment {
return .sandbox
}
func authenticationMethod() -> AuthenticationMethod {
return .guest(settings: GuestSettings(identifier: "",
referer: "",
organisationId: ""))
}
}令牌交换
您还可以将您的用户与 Karhoo 平台同步，以便您可以交换用户的 JWT 令牌为 Karhoo 用户令牌。这允许您的用户自动进行身份验证并使用 Karhoo 服务。如果您的集成涉及此身份验证方法，您可以使用 AuthService 设置 SDK。
首先，在您的 SDK 配置文件中将身份验证方法指定为 .tokenExchange。
struct YourCompanyKarhooConfiguration: KarhooSDKConfiguration {
func environment() -> KarhooEnvironment {
return .sandbox
}
func authenticationMethod() -> AuthenticationMethod {
return .tokenExchange(settings: TokenExchangeSettings(clientId: "",
scope: ""))
}
}然后使用 AuthService 交换您的 JWT 为 Karhoo 用户。
let authService = Karhoo.getAuthService()
authService.login(token: "user-jwt").execute { result in
switch result {
case .success(let user):
print("user authenticated: ", user)
case .failure(let error):
print("error: \(error.code) \(error.message)")
}
}制作请求
一旦 SDK 验证通过，您可以使用 Karhoo 平台的各项服务。SDK 使用两种通用类型，Call 和 PollCall。这些是网络请求，可能会发送一个请求或在一个指定的间隔内观察端点。
示例调用
let tripService = Karhoo.getTripService()
let tripCancellation = TripCancellation(tripId: "123", cancelReason: .notNeededAnymore)
tripService.cancel(tripCancellation: tripCancellation).execute { result in
switch result {
case .success:
print("Trip cancelled")
case .failure(let error):
print("error: \(error.code) \(error.message)")
}
}示例轮询调用
或许您想监视一次行程并根据需要更新用户界面。我们创建了一个 Observable 类型，可以订阅/取消订阅主题到发布者。
//ensure your reference for the Observer (Subject) AND the Observable (Publisher) are not confined to the scope of a function otherwise they go out of memory at runtime and your UI won't update.
private var tripTrackingObservable: Observable<TripInfo>?
private var tripTrackingObserver: Observer<TripInfo>?
tripTrackingObserver = Observer<TripInfo>.value { [weak self] tripInfo in
print("new trip update! ", tripInfo)
}
tripTrackingObservable = tripService.trackTrip(identifier: "some-trip-id").observable(pollTime: 5) // where 5 = 5 seconds
tripTrackingObservable?.subscribe(observer: tripTrackingObserver)
// deallocation
tripTrackingObservable?.unsubscribe(observer: tripTrackingObserver)SDK 架构概述
SDK 被分为服务。例如，行程、驾驶员跟踪、可用性、用户、支付等服务。这些服务依赖于执行者，这些执行者依赖于请求。在服务中简单调用一个函数将触发执行者调用请求。请求使用我们的 HttpClient 进行网络调用。
模型使用可解码结构体进行编码/解码。这些位于 Api/DataObjects/Request/Response 组中。
有一个单元测试目标，用于测试单个类的预期工作，还有一个集成测试目标，它使用 OHHTPStubs 来测试 SDK 是否按预期工作（从网络层到服务）。
开发准备
我们使用 Swift Package Manager 来处理 SDK 内部依赖和开发。在 Xcode 11 及以上版本，检出项目后，您可以前往 Xcode -> 文件 -> Swift Packages -> 更新到最新包版本
运行测试
存在用于单元测试和集成测试的 Xcode 计划。单元测试使用模拟依赖项测试单个类的功能。集成测试使用 JSON 合同模拟后端响应，并确保 SDK 从输入到输出都能正常工作。
客户端示例
在本存储库的 Client 目录中有一个示例项目。这是用来快速测试 SDK 变化和开发步骤的一个方法。您需要将这些访问密钥添加到客户端模块，因为这些由于这是开源仓库而被忽略。
struct Keys {
static let identifier = ""
...
}问题
希望贡献吗？
🐛 错误
请为错误、缺少文档或意外的行为提交问题。
💡 功能请求
请提交问题来建议新功能。通过添加 👍 为功能请求投票。这有助于维护者优先考虑哪些功能进行开发。
❓ 问题
有关使用库的问题，请首先查看文档。如果没有答案，请创建一个带有标签 help needed 的问题。