注意：这是 Clover iOS SDK 的 alpha 版本，可能会更改。

示例用法

• 获取访问令牌

CLVSession.authenticateUser(forClientId: "####", withAppName: "", domain: .US, activeView: self,
  success: { session in
    // Persist the values in Keychain to use later
  }, failure: { err in
})

• 简化示例

CLVSession(accessToken: "####", domain: .US, merchantId: "####")
  .getMerchantOrder(withId: "####", expands: ["lineItems"],
    success: { order in },
    failure: { error in })

• 完整示例

let session = CLVSession(accessToken: "####", domain: .US, merchantId: "####")
session.getMerchantEmployees(
    filters: ["role": "ADMIN"],
    expands: ["shifts"],
      sorts: ["name": .ASC],
     params: [:],
      limit: 50,
     offset: 0,
    success: { employees in
    for employee in employees {
      print(employee.name!)
    }
  },
    failure: { error in
    switch error {
    case .UnacceptableStatusCode(let statusCode, let serverMessage):
      print("\(statusCode) - \(serverMessage)")
    case .Error(let error): print(error)
    case .UnknownError: print("Unknown error!")
    }
})

• CloverSDK 通过以指数级增加时间延迟重试相同请求来处理 429（请求过多）错误情况。

Clover iOS SDK 的组件

模型：Swift 实现的 API 文档页面上的 json 响应模型

• 所有模型都遵循 NSObject 和 NSCoding，适用于 iOS 持久化。

• 所有模型都遵循 Mappable（开源库：ObjectMapper）用于 json 的序列化和反序列化。

• alpha 版本中包含一些不在公共 API 中的模型，但通过一些 API 调用进行了扩展，因此后续版本中会删除一些模型。

• 所有模型都继承自主 CLVModel 类，然后组合成逻辑分组类；例如，客户地址模型将是：CLVModels.Customers.Address。

• 模型上的大多数字段都有文档，将在 Xcode 的自动完成中显示。

• 一些与 Swift 关键字冲突的字段名在末尾加上下划线，例如：description_。

Utils：API 调用的辅助类

• 主要有两个类：CLVSession 和 CLVRequest。

• CLVSession

  • 一旦你有商家的 ID、商家令牌和域名（目前为美国或欧洲以及用于开发的沙箱），你就可以启动一个会话对象，然后开始在该对象上调用存储这些信息的 Clover 端点。

  • 会话有两个静态变量用于定义调试选项。`debugMode` 是一个布尔值，用于确定是否会对任何请求输出任何内容，而 `debugPrintOptions` 是一个枚举值列表，你可以选择加入以获得输出。

let session = CLVSession(accessToken: "####", domain: .US, merchantId: "####")
session.getMerchantOrder(withId: "####", expands: ["lineItems"])

• CLVRequest

  • 这主要是内部用于调用我们的 v3 端点的方法，但它也可以独立使用以进行进一步的自定义或使用 v1/v2 端点。

  • 它提供了一个构建器来传递所有选项，以及一个具有绝对最小选项的初始化器：HTTP方法、域和端点。传递所有选项后，您可以通过调用build()方法来获取一个CLVRequest对象。修改请求时，构建器还需要一个CLVRequest参数。

  • 一旦您拥有一个CLVRequest对象，您就可以在该对象上调用makeRequest…()方法，这是端点方法内部使用的，但它们也是公共方法。这些方法负责所有请求的前后验证，如果在收到429 - 太多的请求错误时需要重新提交请求，并调用通过传递的适当的success或failure块。有三种方式获取单个对象、对象的数组或获取不包含在CLVModels中（对于v1/v2端点）的模型AnyObject。

  • CLVMethods文件是CLVSession的一个扩展，是一个自动生成的文件，包含了在我们api_docs页面上所有GET端点的调用，如：getMerchantOrderDiscounts:withId:。目前使用这些方法不支持POST和DELETE请求，但在beta版本中将会包含，然而，目前您可以使用CLVRequest.Builder类和makeRequest方法。

  • 一些端点方法返回单个对象（如getMerchantOrder:withId:），而一些则返回该对象的数组（如getMerchantOrders:）。返回的对象是可选的，而数组不是，但它们可以是空的。

  • CLVEndpoint是一个枚举，包含两个案例：V3和Custom。V3接受一个参数CLVV3Endpoint，这是一个包含所有我们v3端点url的枚举。如果您需要调用不同的端点（v1/v2），您可以使用包含String作为url的Custom。

  • CLVError是一个继承自标准ErrorType的枚举。目前，它只有非200状态代码、NSError和未知错误的选项，但未来版本可能会添加更多细分选项。它还有一个用于宁市error对象的计算的变量。

PromiseKit扩展

• 在我们的Clover Dashboard应用中使用SDK的经验中，当使用多个连续的API调用时，使用成功和失败方法使得代码难以阅读和调试；作为替代方案，我们支持开源的Promise概念，您可以在承诺对象可用时对其执行操作。所有的CLVRequest.makeRequest方法和端点方法也已重新定义用于PromiseKit。使用示例

let session = CLVSession(accessToken: "####", domain: .US, merchantId: "####")
session.getMerchantOrders(filters: ["employee.id": "####"], expands: ["lineItems", "customers"])
  .then() { (orders) -> String? in
    for order in orders {
      print(order.lineItems!)
    }
    return orders.first?.employee?.id
  }
  .then() { (employeeId) -> Void in
    guard let employeeId = employeeId else { return }
    session.getMerchantEmployee(withId: employeeId)
    ...
  }
  .always() {
    // cleanup code, such as: hide spinners
  }
  .error() { error in
    print(error)
}

• PromiseKit的使用仍然是实验性的，因此请自行承担风险。

OAuth

• 这是一个助手类，它使用在应用中弹出的网页，要求用户登录并安装您的应用，如果是这样，将返回包含所有值填充的CLVSession对象。

• clientId是您的应用的id。目前，在通过页面弹出之前，您需要推断/询问用户的区域，因为用户不能更改登录页面的URL，您需要传递给定区域的适当应用id，假设您的应用存在于多个区域。我们可能会在登录页面上添加一个让用户切换到不同区域的选项，如果是这样，我们将更新此方法，这样您就不必事先知道他们的区域。

• appName仅用于浏览器窗口的标题。

• domain是您的应用所在的区域。

• activeView是您从这里调用此方法的ViewController。

• 只使用Keychain保存这些信息是很重要的，因为这个令牌可以让任何人为商家做出API请求！

CLVSession.authenticateUser(forClientId: "####", withAppName: "App", domain: .US, activeView: self,
  success: { (session) -> Void in
    // Persist the values in Keychain to use later
  }) { (error) -> Void in
    // ...
}

一般注意事项

• 这是一个Alpha版本，因此无法保证内容是否会保持不变，或者是否会在SDK中保留。任何内容都可能会发生变化或被删除，具体取决于反馈。我们将尽力做出更改，以便您在更新项目时不会遇到太多麻烦，但这是一个Alpha版本，因此任何变化都是可能的。

• 欢迎并感谢您的反馈和拉取请求！