Bloombox for Swift

此Swift包提供了一个Bloombox Cloud APIs的API客户端。Bloombox APIs使用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包管理器

// 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

架构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私有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.Views对象中收集。

商店API

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

Bloombox Shop服务允许与订单、用户注册和验证等交互。其中包含的示例检查了一个商店的“info”，其中包括其开放/关闭状态以及其他标题详情。可用的完整商店方法集包括

• 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)")
  }

平台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")
  }

设备API

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

执行合作伙伴侧设备的激活。对于菜单平板和其他物品，设备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)")
  }

菜单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合作伙伴还可以记录具有他们自己意义的事件，并可选择将这些事件包括在内置事件流程中。

花盒遥测系统通过类别区分事件，支持三个主要类别的外部使用。

• EventTelemetry：通用的事件遥测，具有任意事件有效载荷。
• CommercialTelemetry：与零售风格漏斗兼容的遥测，拆分为印象、查看和操作。
• IdentityTelemetry：用户身份相关的遥测事件。合作伙伴无法直接使用，但可在分析流程中使用。

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

认证API

即将提供完整文档和指南。

签到API

即将提供完整文档和指南。

媒体API

即将提供完整文档和指南。

许可

版权所有 © 2018 动能创意公司。

Apache 2.0 许可在LICENSE.txt中附带，此外，还包括在NOTICE.txt中的附加声明。根据Apache License，版本2.0（“许可”）；除非遵守许可，否则不得使用该文件。您可以在以下位置获取许可的副本：

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

除非适用法律的要求或已以书面形式约定，否则根据本许可证分发软件基于“现状”进行分发，不提供任何形式的明示或默示保证或条款。有关许可证的许可范围和限制的具体语言请参阅许可证。