Bloombox for Swift

这个 Swift 包为 Bloombox Cloud API 提供了一个 API 客户端。Bloombox API 使用 gRPC 构建和提供，并在客户端库中公开，例如这个，它提供了一个更流畅的界面来使用。Bloombox 系统符合 OpenCannabis 标准，并公开例如一个 OpenCannabis pod，它可以独立于 API 客户端使用。

您可以始终选择使用较低级别的 API，而不是客户端库，可以通过 gRPC+protobuf 或 JSON-REST。

在 iOS 方面，这个库客户端是用原生 Swift 构建的，并打包为 Cocoapod 和 Swift Package。它基于 Apple 的 Protobuf for Swift 和新的原生 gRPC for Swift 构建。它在 macOS 11 和 iOS 11 上进行了测试，尽管底层工具仍在积极开发中，因此 YMMV（您的里程可能会有所不同）。

使用代码

通过 CocoaPods

project 'YourProject.xcodeproj/'

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '8.0'
inhibit_all_warnings!

target 'YourProject' do
  use_frameworks!

  pod 'OpenCannabis', '~> 0.5.0'
  pod 'Bloombox', '~> 0.5.0'
end

通过 Swift Package Manager

// swift-tools-version:5.0
  
import PackageDescription

let package = Package(
    name: "YourProject",

    /// ...

    dependencies: [
        .package(url: "https://github.com/bloombox/swift", .upToNextMinor(from: "0.5.0"))])

通过 Carthage

github "bloombox/swift" ~> 0.5.0

Schema Pods

Bloombox Swift SDK 被分解为三个 pods，以便较低级别的结构可以直接与手动实现的 gRPC 一起使用。它们的布局如下（大致按反抽象顺序排列）

Pod	版本	平台	描述
`Bloombox`			完整的客户端库外观、示例应用程序、文档和指南。
`BloomboxServices`			用于与 Bloombox API 交互的低级 gRPC 服务。
`OpenCannabis`			Swift 中与 OpenCannabis 兼容的对象树。

构建代码

构建代码很容易，并且遵循标准的 Swift 打包约定。还有一个 Makefile 与各种有用的例程打包在一起 - 如果您正在开发代码，您将使用 make。

工具

Xcode 10/Swift 4.2（对于 0.1.5 及以上版本，以前是 Xcode 9 / Swift 3.2）
make 和其他用于 XCode 的 CLI 工具
代码访问 Bloombox 的私有 schema 存储库

服务

要开始使用 API 服务，请在您的应用程序中的某个位置设置一个 API 客户端

    let client: Bloombox = Bloombox(settings: Bloombox.Settings(
      apiKey: "[your-api-key]",
      partner: "[your-partner-id]",
      location: "[your-location-id]"))

有关这些设置的详细信息

API 密钥：向 Bloombox API 标识您的应用程序/项目。您可以从 Bloombox 仪表板配置这些密钥。
合作伙伴 ID：通过简短的字符串代码标识您的合作伙伴帐户。可以在您的 Bloombox 仪表板中找到。
位置 ID：标识您要交易/交互的合作伙伴位置。也可以在您的 Bloombox 仪表板中找到，在您希望使用的位置下。

注意： 请确保在某处保留 Bloombox 客户端实例，否则您有客户端（以及相关的回调等）在请求过程中被释放的风险

架构

对于 SDK 中的几乎每个方法，都有一个直接返回其响应的同步变体，以及一个通过回调而不是直接返回响应的异步变体。使用同步 API 时，会抛出错误，无论它们是在客户端（例如，缺少 API 密钥）还是在服务器端（例如，授权失败）遇到。相比之下，异步 API 仅抛出客户端错误，并通过提供的回调报告服务器端错误。

每个服务都有一个附带的客户端错误枚举，它提供了在请求离开服务器之前可能抛出的每个错误。

为了方便跨位置使用，大多数（如果不是全部）方法都支持在每次调用时覆盖合作伙伴、位置或 API 密钥。如果您选择不提供这些覆盖值，则会从 Bloombox.Settings 对象中收集它们。

Shop API

尝试此 API 或在 API 控制台中浏览文档

属性	值
服务	`shop`
版本	`v1`
端点	`api.bloombox.cloud`
域	`shop.rpc.bloombox.cloud`

Bloombox Shop 服务允许与订购、用户注册和验证等进行交互。包含的示例检查商店的“信息”，其中包括其打开/关闭状态以及其他一些首屏详细信息。完整的可用商店方法包括

info：检索 OPEN/CLOSED 状态和其他首屏详细信息。
verifyMember：对给定的用户帐户执行会员资格验证。
enrollMember：将用户注册为药房位置的成员，并且可能注册一个新帐户。
zipcheck：检查给定的 USPS 邮政编码是否符合送货条件（以及适用的最低要求）。
submitOrder：提交在线/商业订单，用于 PICKUP 或 DELIVERY。
getOrder：检索现有的在线/商业订单。

同步

  do {
    let info: ShopInfo.Response = try client.shop.info()

    switch status.shopStatus {
    case .open:
      // the shop is open
    case .closed:
      // the shop is entirely closed
    case .deliveryOnly:
      // the shop is only open for delivery
    case .pickupOnly:
      // the shop is only open for pickup
    default: fatalError("unrecognized shop status")
    }

  } catch {
    fatalError("some error occurred: \(error)")
  }

Platform API

尝试此 API 或在 API 控制台中浏览文档

属性	值
服务	`platform`
版本	`v1`
端点	`api.bloombox.cloud`
域	`platform.rpc.bloombox.cloud`

Platform API 提供基本的帐户和域名查找方法，以及与任何特定合作伙伴或位置帐户无关的各种方法。这包括健康检查、系统 ping、域名解析和域名信息获取

ping：向服务器发送一条简单的消息，要求它做出响应。
healthcheck：要求系统报告其当前状态。
resolve：解析给定域的合作伙伴帐户代码和位置代码。
domains：解析给定合作伙伴帐户代码和位置代码的一组域。
brand：检索给定合作伙伴帐户代码和位置代码的品牌信息。

同步

  do {
    let assignment: ResolveDomains.Response = try client.platform.resolve("domain.com:443")

  } catch {
    fatalError("some client-side or server-side error occurred: \(error)")
  }

异步

  do {
    try client.platform.resolve("domain.com:443") { result, response in
      // result is the call result from gRPC, response is the RPC response, if available
      if let assignment = response {
        // assignment.partner and assignment.location
      } else {
        // do something about the error state
        fatalError("some error happened: \(result.statusCode)")
      }
    }
  } catch {
    // only client-side errors will show up here (i.e. missing API key, or unresolved partner ID)
    fatalError("client-side error")
  }

Devices API

尝试此 API 或在 API 控制台中浏览文档

属性	值
服务	`devices`
版本	`v1beta1`
端点	`api.bloombox.cloud`
域	`devices.rpc.bloombox.cloud`

执行合作伙伴端设备的激活。对于菜单平板电脑和其他项目，Devices API 提供了工具来访问并发现绑定到调用设备的任何分配和角色信息。

在某些情况下（通常由分配的设备角色决定），可能需要 fingerprint 或 publicKey 值。设备激活可能会根据这些属性的值受到限制，或者，它们可能需要与设备有史以来发生的第一次激活相匹配。其他限制可能适用于设备激活，同样，通过角色，例如强制执行客户端证书、IP 限制等等。

同步

  do {
    let manifest: DeviceActivation.Response = try client.devices.activate(
        deviceSerial: "ABC-123",
        withFingerprint: "[device-hardware-fingerprint]",
        withPublicKey: "[device-public-key]")

  } catch {
    fatalError("some client-side or server-side error occurred: \(error)")
  }

异步

  do {
    try client.devices.activate(
        deviceSerial: "ABC-123",
        withFingerprint: "[device-hardware-fingerprint]",
        withPublicKey: "[device-public-key]") { callResult, response in

      // handle the call result and response
      if let manifest = response {
        // the device was able to activate
      } else {
        fatalError("the device was not able to activate: \(call.statusCode)")
      }
    } 
  } catch {
    fatalError("some client-side error occurred: \(error)")
  }

Menu API

尝试此 API 或在 API 控制台中浏览文档

属性	值
服务	`menu`
版本	`v1beta1`
端点	`api.bloombox.cloud`
域	`menu.rpc.bloombox.cloud`

Menu API 提供了以只读方式与产品数据交互的工具，着眼于展示/销售产品。这与更详细的产品目录解决方案和 Bloombox API 不同，因为

缺货或当前未在给定位置提供的商品默认情况下会被隐藏
没有定价或标记为不适合销售的商品默认情况下会被隐藏
标记为在零售渠道上禁止分发的商品默认情况下会被隐藏

某些 Menu API 方法提供了覆盖上述行为的标志，但是，总的来说，Menu API 旨在提供产品目录数据，然后将其展示给潜在的零售客户。

使用 Menu API 的最简单示例（如下所示）是检索给定合作伙伴位置的整个菜单。完整的方法包括

retrieve：检索给定合作伙伴位置的整个菜单目录。
section：检索给定位置菜单的单个部分。菜单按 ProductKind 分段。
featured：检索给定位置菜单上当前的一组特色产品。
products：检索一个或多个产品数据记录。
search：对当前列在给定位置菜单上的产品执行全文搜索。
create：从头开始创建新的产品记录。
update：使用新数据更新现有产品记录。
remove：从位置的菜单中删除现有的产品记录。
productStatus：检索给定产品记录在位置菜单上的当前状态。
inStock：将现有产品记录标记为当前在给定位置菜单上有库存。
outOfStock：将现有产品记录标记为当前在给定位置菜单上缺货。

同步

  do {
    let menu: GetMenu.Response = try client.menu.retrieve()

  } catch {
    fatalError("some client-side or server-side error occurred: \(error)")
  }

异步

  do {
    try client.menu.retrieve() { callResult, response in
      // handle the call result and response
      if let menu = response {
        // the catalog will be at `menu.catalog`
      } else {
        fatalError("unable to fetch the menu: \(call.statusCode)")
      }
    }
  } catch {
    fatalError("some client-side error occurred: \(error)")
  }

Telemetry API

尝试此 API 或在 API 控制台中浏览文档

属性	值
服务	`telemetry`
版本	`v1beta4`
端点	`api.bloombox.cloud`
域	`telemetry.rpc.bloombox.cloud`

Telemetry API 允许您在事件发生时中继事件，以便它们可以在用户流程和其他 Bloombox 提供的指标中被归因。Bloombox 合作伙伴还可以记录具有自己含义的任意事件，并可以选择将这些事件包含在内置事件流程中。

Bloombox 遥测系统按类别区分事件，支持外部使用的三个主要类别

EventTelemetry：通用的基于事件的遥测，具有任意事件有效负载。
CommercialTelemetry：零售式漏斗兼容的遥测，分为展示、查看和操作。
IdentityTelemetry：与用户身份相关的遥测事件。合作伙伴无法直接使用，但可以在分析流程中使用。

这些方法的完整枚举和使用指南即将推出。

Auth API

属性	值
服务	`auth`
版本	`v1beta1`
端点	`api.bloombox.cloud`
域	`auth.rpc.bloombox.cloud`

完整文档和指南即将推出。

Checkin API

属性	值
服务	`checkin`
版本	`v1beta1`
端点	`api.bloombox.cloud`
域	`checkin.rpc.bloombox.cloud`

完整文档和指南即将推出。

媒体 API

属性	值
服务	`媒体`
版本	`v1beta1`
端点	`api.bloombox.cloud`
域	`media.rpc.bloombox.cloud`

完整文档和指南即将推出。

许可

Apache 2.0 许可证的副本包含在 LICENSE.txt 中，以及 NOTICE.txt 中的其他声明。根据 Apache 许可证 2.0 版（“许可证”）获得许可；除非遵守许可证，否则您不得使用此文件。您可以在以下位置获得许可证的副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或以书面形式同意，否则按“原样”分发的软件不附带任何形式的明示或暗示的担保或条件。有关许可证下管理权限和限制的具体语言，请参见许可证。