Bloombox for Swift

这个Swift包提供了Bloombox云API的API客户端。Bloombox API使用gRPC构建并托管，并通过这个客户端等类似库以更流畅的界面暴露出来。Bloombox系统遵循OpenCannabis，例如提供了一个可独立于API客户端使用的OpenCannabis pod。

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

在iOS领域中，这个库客户端是用原生Swift构建的，并包装为Cocoapod和Swift Package。它基于Apple的Swift Protobuf和新原生Swift gRPC构建。它在macOS 11和iOS 11上进行过测试，尽管底层工具仍在积极开发中，因此可能会有所不同。

使用代码

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被拆分为三个pod，以便可以直接使用手工编写的gRPC实现使用较低级别的结构。它们按如下方式排列（大致按反向抽象顺序）

Pod	版本	平台	描述
Bloombox			完整的客户端库门面、示例应用、文档和指南。
BloomboxServices			与Bloombox API交互的底层gRPC服务。
OpenCannabis			OpenCannabis兼容的对象树在Swift中。

构建代码

构建代码简单，遵循标准的Swift打包约定。还包含了一个包含各种实用例程的Makefile - 如果你在这个代码上进行开发，你会使用make。

工具

• Xcode 10/Swift 4.2（针对版本0.1.5及以上，之前是Xcode 9 / Swift 3.2）
• make和其他XCode的CLI工具
• 对于Bloombox的私有模式仓库的代码访问权限

服务

要开始使用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控制台中的文档

Bloombox Shop服务允许与订单、用户注册和验证等交互。包含的示例检查商店的“信息”，包括其开放/关闭状态和其他一些重要的详细信息。可用的商店方法包括

• info：检索OPEN/CLOSED状态和其他重要的详细信息。
• verifyMember：对特定用户账户执行会员验证。
• enrollMember：将用户注册为 dispensary 地点的会员，并且可能为新的账户。
• 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控制台中的文档

平台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 API提供工具来发现绑定到调用设备的任何分配和角色信息。

在某些情况下（通常由分配的设备角色控制），可能需要指纹或公钥值。设备激活可能会根据这些属性的值进行限制，或者，它们可能需要与设备首次激活时匹配。设备激活可能还会根据角色应用其他限制，例如实施客户端证书、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)")
  }

菜单API

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

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

• 默认情况下，不提供库存或当前不在特定位置提供的商品
• 默认情况下，没有定价或标记为不适合出售的商品会被隐藏
• 标记为在零售渠道中禁止分发的商品默认会被隐藏

一些菜单API方法提供了用于覆盖上述行为的标志，但总体而言，菜单API旨在提供产品目录数据，然后向潜在零售客户展示。

使用菜单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)")
  }

遥测API

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

遥测API允许您实时传递事件，以便它们可以归因于用户流程和其他Bloombox提供的度量标准。Bloombox合作伙伴还可以记录具有自己意义的事件，并可选择将这些事件包含在内置事件流程中。

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

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

这些方法的全览和使用指南即将发布。

认证API

完整文档和指南即将发布。

登记API

完整文档和指南即将发布。

媒体API

完整文档和指南即将发布。

许可

版权所有 © 2018 Momentum Ideas Co.

Apache 2.0 许可协议的副本已包含在 LICENSE.txt 中，以及 NOTICE.txt 中的附加通知。在 Apache License, Version 2.0（以下简称“许可证”）之下许可；除非适用法律要求或已签订书面协议，否则不得使用此文件，除非符合许可证。您可以在以下地址获取许可证的副本：

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

除非适用法律要求或书面同意，否则在许可证下分发的软件按“现状”分发，不提供任何形式的保证或条件，无论是明示的、暗示的还是法律的。有关许可证所辖权限和限制的具体语言，请参阅许可证。