HeliumKit

Mia-js 的 iOS 中间件访问库。

要求

iOS >= 8.0, Swift

设置

将 HeliumKit 添加到您的 Podfile。

pod "HeliumKit", "~> 1.0"

运行 pod install。

通用用法

// Struct containing a decoded TVShow.
struct TVShow: Decodable {
    static var selectionString: String { return "{id,titles{default},images{url}}" }

    let id: String
    let title: String
    let imageURL: NSURL

    static func decode(data: NSData) -> TVShow? {
        // dataToJSON is a helper method provided by the Decodable protocol.
        let json = dataToJSON(data)
        // Extract properties from decoded JSON here and initialize struct...
        return self.init(
          id: id,
          title: title, 
          imageURL: imageURL
        )
    }
}

// Configuration for device registration.
let deviceConfiguration = DeviceConfiguration(
    URL: NSURL(string: "https://mobileapi-stage.prosiebensat1.com/7tv/mobile/v1/devices")!,
    deviceInfo: DeviceInfo(bundle: NSBundle.mainBundle(), carrierName: ""),
    persistenceStore: DeviceConfigurationUserDefaultsStore()
)

// Create Helium with configuration. 
let config = HeliumConfiguration(
    secret: "YourClientSecret",
    secretID: "YourClientSecretID",
    baseURL: NSURL(string: "https://mobileapi-stage.prosiebensat1.com")!,
    acceptableStatusCodes: 200..<300,
    deviceConfiguration: deviceConfiguration
)

let helium = Helium(configuration: config, authenticationHashFunction: HashFunctions.sha256)

// Perform get call and retrieve decoded TVShow.
let task = helium.get("/7tv/mobile/v1/tvshows/:id", returnType: TVShow.self)
  .pathReplacements(["id": "1032808"])
  .parameters(["limit": 100])
  .completion { result in
    switch result {
    case .Success(let tvShow, _, _):

    case .Error(let error, _):

    }
}

上述代码段使用了四个主要步骤来执行中间件调用

• 定义了一个结构体，它实现了 Decodable 协议，用于将中间件的 JSON 响应解码为 TVShow 的基本数据。
• 创建了用于设备注册和 Helium 的配置对象。请联系 ProSiebenSat.1 Mobile Middleware 团队以获取用于您的用例的有效参数。
• 使用先前定义的配置对象创建了 Helium 的一个实例。
• 执行了一个 GET 调用。调用配置了特定 TVShow 的路径、响应的返回类型（本例中定义的第 1 步中定义的 TVShow 结构体）和 GET 参数（例如，本例中的“limit”）。最终的完成方法启动调用并接收一个闭包，该闭包由关联枚举触发。结果枚举是 .Success 或 .Error。在成功的情况下，第一个关联值包含解码的结果类型。注意：如果您想在此处更新 UI，则需要将任务分发到主队列。

配置

Helium 必须使用 HeliumConfiguration 的一个实例进行配置。从 Middleware 团队获取以下配置值：如 secret、secretID 和 baseURL。acceptableStatusCodes 是 Swift Range，指定被视为成功的 HTTP 状态码。

单独配置了 DeviceConfiguration 类，并将其作为参数传递给 HeliumConfiguration。在这里，URL指定了创建、更新和删除设备的端点。（Helium 内部处理设备的注册和更新。）

对于参数 deviceInfo，注入了 DeviceInfo 类的一个实例。该类使用应用程序包和可选的运营商名称进行配置。然后该类在内部查询有关设备和操作系统的各种详细信息。从传入的包中读取有关应用程序标识符和版本字符串等详细信息。（请联系 Middleware 团队以获取有效值。）

设备令牌的持久化存储策略可以通过参数 persistenceStore 进行配置。您可以选择 DeviceConfigurationUserDefaultsStore，它将令牌存储在用户默认设置中，或者通过实现 DeviceConfigurationPersistenceStore 协议创建自己的存储（例如使用密钥链存储）。

解码 / 编码

在它的 get、post、put 和 delete 方法中，Helium 允许您指定中间件响应解码到的类型。这些类型需要遵循 Decodable 协议并实现一个静态的 decode 方法。此方法由 Helium 调用并接收一个 NSData 对象。使用便捷方法 dataToJSON，您可以解码数据到 JSON，提取结构的具体值，并在方法末尾返回初始化后的值。

在您的应用程序中，您可以定义一个 TVShow 和一个 Video 结构，然后为参数 returnType (例如，helium.get("/7tv/mobile/v1/tvshows/:id", returnType: TVShow.self) 设置这些结构的元类型值。当响应成功时，完成闭包将接收此类型的解码值。

执行请求

Helium 提供了一个流畅的接口，允许您按需链式调用多个选项，并在链的最后通过调用链的末尾的 complete 方法开始调用。前四个主要方法是 get、post、put 和 delete。第一个参数是要附加到基本路径的路径（通过 HeliumConfiguration 进行配置），第二个参数是返回类型的元类型值（参见上一节）。

您可以使用对 parameters 的调用（包含查询参数的字典）和对 pathReplacements 的调用（用于替换 path 参数的字典）将主要方法串联起来。 timeout 允许您为调用设置一个每个请求的超时值。链必须始终以对 completion 方法的调用结束。然后触发完成闭包，并带有一个与成功和错误案例相关联的枚举（参见示例）。

取消请求

Helium 方法为最后的 complete 调用返回一个 Task 对象。该 Task 提供一个 cancel() 方法。