iOS 開發者輕鬆整合 OCAP 指南

Jonathan Lu (Mobile Engineer at ArcBlock)2018年8月24日

作者： Jonathan Lu (ArcBlock 行動裝置工程師)

在我們先前的部落格文章中，您已經了解了 OCAP 服務及其 Playground，現在您知道如何透過編寫 GraphQL 查詢在 Playground 中深入探索區塊鏈數據。在玩了一段時間後，您發現了一些見解，並想建立一個利用這些查詢的 行動應用程式 (Mobile application)。我們可以做到嗎？

當然可以！事實上，ArcBlock 已經為您準備了一套工具，讓您可以從行動平台整合 OCAP。在本文中，我們將介紹 iOS SDK，您可以使用它輕鬆連接 OCAP。

假設您想建立一個顯示比特幣富豪榜帳戶列表的 App。本文接下來將引導您如何使用我們的 SDK 達成此目標。

安裝 SDK

第一步是將 SDK 安裝到您的專案中，您可以透過 CocoaPods 或 Carthage 來完成：

# Podfile
pod 'ArcBlockSDK', :git => 'https://github.com/ArcBlock/arcblock-ios-sdk.git'
pod 'Apollo', :git => 'https://github.com/ArcBlock/apollo-ios.git'

# Cartfile
github "ArcBlock/arcblock-ios-sdk"

生成 Swift 程式碼

讓我們回到 Playground 一下。

GraphQL 的優點之一是 類型安全 (type safety)。一旦查詢和 Schema 確定後，我們在執行前就能知道查詢參數和回傳數據的類型。因此，我們提供了一個程式碼生成 (codegen) 工具來幫助您生成封裝查詢的 Swift 類別。SDK 將使用這些類別，並在編譯時期強制執行 App 的類型安全。

codegen 工具直接整合在 OCAP Playbook 中。在 Playbook 內部，您可以看到一個 Generate Codes 按鈕。選擇 Swift 作為語言並生成，一個 API.swift 檔案將會下載到您的本地電腦。最後，您只需要將該檔案拖入您的專案資料夾即可。

Playbook 中的 Codegen

這是用於查詢比特幣富豪榜帳戶的範例 playbook。

安裝 XCode 檔案模板

ArcBlockSDK 提供了一些 XCode 檔案模板供您建立新類別。要安裝它們，請執行以下指令：

wget http://ios-docs.arcblock.io/Templates.tar.gz; \
tar -xvf Templates.tar.gz --strip-components=1 --directory ~/Library/Developer/Xcode/Templates/File\ Templates/; \
rm Templates.tar.gz

初始化 ABSDKClient

現在讓我們來寫點程式碼！

ABSDKClient 是一個 GraphQL 用戶端，負責發送查詢、解析結果、管理快取等。您可以為每個請求建立一個用戶端，或者在整個 App 中共用一個：

// in AppDelegate.swift

var arcblockClient: ABSDKClient!

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    let databaseURL = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent("ocap-demo-db")
    do {
        // initialize the AppSync client configuration configuration
        let arcblockConfiguration = try ABSDKClientConfiguration(endpoint: .btc, databaseURL: databaseURL)
        // initialize app sync client
        arcblockClient = try ABSDKClient(configuration: arcblockConfiguration)
    } catch {
        print("Error initializing ABSDKClient. \(error)")
    }
    return true
}

建立您的 ViewController

現在讓我們使用 ABSDKClient 來發送查詢並顯示結果。我們將使用剛安裝的檔案模板建立一個新的 ViewController。

新建檔案

新建檔案配置

現在已經建立了一個 ABSDKTableViewController 和一個 ABSDKTableViewCell 的子類別。

配置您的 ViewController

接下來，我們需要為 ViewController 配置一些屬性。

// in ViewController.swift

override func configDataSource() {
    // config the parameters for initiating data source

    let appDelegate = UIApplication.shared.delegate as! AppDelegate
    client = appDelegate.arcblockClient

    dataSourceMapper = { (data) in
        return data.richestAccounts?.data
    }
    pageMapper = { (data) in
        return (data.richestAccounts?.page)!
    }
    query = RichestAccountsQuery()
}

上述程式碼指定了要使用的用戶端、用於提取數據欄位的閉包 (closure)、用於提取分頁欄位的閉包，以及要使用的查詢封裝類別。

在 Cell 中顯示數據

接下來，我們需要將數據欄位連接到 TableViewCell 中的 UI 元素。

// in AccountListCell.swift

override func updateView(data: RichestAccountsQuery.Data.RichestAccount.Datum) {
    self.textLabel?.text = data.address
    self.detailTextLabel?.text = "Balance: " + String(data.balance!)
}

系統也會為 Cell 類別建立一個 XIB 檔案，因此您可以根據需要自定義 Cell 的外觀。

建置並執行

就這樣！您現在可以建置並執行 App 了。

螢幕截圖

如您所見，您只需要編寫幾行程式碼，SDK 就會處理發送網路請求、解析結果、儲存快取、數據綁定和分頁。

範例專案可以在這裡找到。

最後，如果您想對 ViewController 有更多控制權（例如使用 CollectionView 而不是 TableView），並且只想在數據或網路層級使用 SDK，請查看我們文件中的數據綁定 (Data Binding)、用戶端 (Client) 和類別參考 (Class Reference)。

本頁涉及

產品

OCAP active
一個用統一介面查詢鏈上資料的協定，不必每條鏈配一個客戶端。ArcBlock 持有相關專利。