Bloombox for Swift

这个Swift包为Bloombox Cloud API提供了一个API客户端。Bloombox API使用gRPC构建和提供，并通过像这样一个客户端库暴露，提供了更流畅的接口来使用。Bloombox系统符合OpenCannabis标准，例如，提供了一个可以独立于API客户端使用的OpenCannabis pod。

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

在iOS领域，此库客户端是用原生Swift编写的，并打包为Cocoapod和Swift Package。它是基于Apple's 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包管理器

// 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			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 Dashboard 预配这些密钥。
• 合作伙伴 ID：通过一个简短的字串代码识别您的合作伙伴账户。可在 Bloombox Dashboard 中找到。
• 位置 ID：识别您想进行交易/交互的合作伙伴位置。您也可以在 Bloombox Dashboard 中找到，在您希望使用的位置下。

注意：请确保在某个地方保留 Bloombox 客户端实例，否则在请求过程中存在客户端（和相关回调等）被回收的风险

架构

在 SDK 的几乎所有方法中，都提供了同步版本，它直接返回其响应，以及异步版本，它通过回调响应而不是直接返回响应。当使用同步 API 时，如果错误是在客户端遇到的（例如，缺少 API 密钥），或是在服务器端遇到的（例如，授权失败），则会抛出错误。相比之下，异步 API 只抛出客户端错误，并通过提供的回调报告服务器端错误。

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

为了使跨位置使用简单，大多数方法（如果不是所有方法）都支持在每次调用基础上覆盖合作伙伴、位置或 API 密钥。如果您选择不提供这些覆盖值，它们将来自 Bloombox.Settings 对象。

Shop API

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

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

平台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用于激活合作伙伴侧设备。对于菜单平板电脑和其他物品，设备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 动力想法公司。

在LICENSE.txt中包含Apache 2.0许可的副本，以及额外的通知在NOTICE.txt中。在本许可证下（“许可证”）；您只能在本许可证的条件下使用此文件。您可以在以下位置获取许可证副本：

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

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