MBurgerSwift

MBurgerSwift 是一个客户端库，用 Swift 编写，可以用来与 MBurger API 交互。该库的最小部署目标为 iOS 10.0。

安装

Swift 包管理器

使用 Xcode 11，您可以使用 Swift 包管理器将 MBurgerSwift 添加到项目中。按照以下简单步骤操作：

• 在 Xcode 中，转到 File > Swift Packages > Add Package Dependency。
• 在“选择包存储库”对话框中键入 https://github.com/Mumble-SRL/MBurgerSwift.git 并按 Next。
• 使用规则“到下一个主版本”指定版本，其最早版本为“1.0.7”，然后按 Next。
• Xcode 将尝试解决版本，之后，您可以选择 MBurgerSwift 库并将其添加到您的应用目标中。

CocoaPods

CocoaPods 是 iOS 的依赖项管理器，能够自动化并简化在项目中使用第三方库的过程。您可以使用以下命令安装 CocoaPods：

$ gem install cocoapods

要将MBurgerSwift集成到您的Xcode项目中，使用CocoaPods，请在Podfile中指定它。

platform :ios, '10.0'

target 'TargetName' do
    pod 'MBurgerSwift'
end

如果您使用Swift，请记住在pod声明前添加use_frameworks!。

然后，运行以下命令：

$ pod install

CocoaPods是安装库的首选方法。

Carthage

Carthage是一个去中心化的依赖管理器，它可以构建您的依赖关系并为您提供二进制框架。要使用Carthage将MBurgerSwift集成到您的Xcode项目中，请在Cartfile中指定它。

github "Mumble-SRL/MBurgerSwift"

手动安装

要手动安装库，将文件夹MBurgerSwift拖放到XCode的项目结构中。

注意，MBurgerSwift依赖MBNetworkingSwift (1.0.4)，因此您还需要安装这个库。

初始化

要初始化SDK，您必须通过仪表板创建一个令牌。点击右上角的设置图标，创建一个API密钥并指定权限。

然后在您的AppDelegate中的application:didFinishLaunchingWithOptions:初始化SDK的MBManager，并设置令牌如下所示：

import MBurgerSwift

...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        MBManager.shared.apiToken = "YOUR_API_TOKEN"
    return true
}

如果您不使用正确的令牌/密钥初始化，您将无法与SDK交互。

使用方法

使用MBClient类来发送所有请求到api以从MBurger检索数据。所有的API调用都有一个复数版本和它的单数对应版本。例如，您可以检索项目的所有块的列表，或者通过其ID检索单个块。

项目

您可以像这样检索项目信息：

MBClient.getProject(success: { project in

}, failure: { error in

})

块

您可以使用函数 getBlocks(Success:Failure) 来检索项目的块，如下所示

MBClient.getBlocks(success: { (blocks, paginationInfos) in

}, failure: { (error) in

})

parameters 参数是一个可选的按照 MBParameter 协议的对象数组，作为参数传递给 MBurger api。可以传递给 api 的多数参数已经在 SDK 中定义，并且在初始化后可以使用。

• MBSortParameter
• MBPaginationParameter
• MBFilterParameter
• MBGeofenceParameter

如果您想传递另一种类型的参数，可以使用 MBGeneralParameter 类，该类可以用键和值初始化，将被传递到 api 中。

所以如果您想包含分页参数，可以这样做

let paginationParam = MBPaginationParameter(skip: 0, take: 10)
MBClient.getBlocks(withParameters: [paginationParam], success: { (blocks, paginationInfos) in

}, failure: { (error) in

})

存在另一个版本的 getBlocks(withParameters:success:failure:)，该版本接受两个额外的参数 包括区域（一个布尔值，指示是否包括每个块的区域），以及 包括元素（一个布尔值，对区域元素执行相同操作）。

所以您可以通过此调用检索所有块的信息，所有块的区域以及所有区域元素

MBClient.getBlocks(withParameters: [paginationParam], includingSections: true, includeElements: true, success: { (blocks, paginationInfos) in

}, failure: { (error) in

})

区域

您可以使用函数 getSections(ofBlock:parameters:success:failure:) 来检索具有指定 id 块的所有区域

MBClient.getSections(ofBlock: THE_BLOCK_ID, parameters: nil, success: { (sections, paginationInfos) in

}, failure: { (error) in

})

与块类似，此函数有另一个版本接受布尔参数 elements，它指示是否包括区域元素。如果想要检索块的所有区域及其元素，可以这样调用

MBClient.getSections(ofBlock: THE_BLOCK_ID, parameters: nil, elements: true, success: { (sections, paginationInfos) in

}, failure: { (error) in

})

媒体

您可以使用其 ID 来检索存储在 MBurger 上的媒体

MBClient.getMedia(withId: MEDIA_ID,
                  success: { media in
                        
                  },
                  failure: { error in
                            
                  })

要检索存储在 MBurger 上的所有媒体，可以使用此函数

MBClient.getAllMedia(success: { media in
            
},
failure: { error in
            
})

类型解码

MBurgerSwift 具有内置系统，可用于初始化自定义结构。您只需让您的结构符合 MBDecodable 协议即可。

例如，一个 News 结构反映了 MBurger 中的新闻源块

class News: MBDecodable {
    let text: String
    let images: [MBImage]
    let link: String
    let date: Date
    
    enum DecoderCodingKeys: String, CodingKey {
        case text
        case images
        case link
        case date
    }
    
    required init(from decoder: MBDecoder) throws {
        let container = try decoder.container(keyedBy: DecoderCodingKeys.self)
        
        text = try container.decode(String.self, forKey: .text)
        images = try container.decode([MBImage].self, forKey: .images)
        link = try container.decode(String.self, forKey: .link)
        date = try container.decode(Date.self, forKey: . date)
    }
}

然后调用 MBDecoder 的 decode 函数来创建并填充一个新闻数组，如下所示

MBClient.getSections(ofBlock: THE_BLOCK_ID, parameters: nil, elements: true, success: { (sections, _) in
    sections.forEach { section in
         do {
             if let elements = section.elements {
                 let news = try MBDecoder.decode(News.self, elements: elements)
                 newsArray.append(news)
             }
         } catch let error {
              self.showError(error)
         }
     }
}, failure: { error in
      self.showError(error)
})       

注意：DecoderCodingKey 需要与 MBurger 块中元素的 name 匹配（例如，如果仪表板上的元素称为 Title，则解码器键需要是 Title）

enum DecoderCodingKeys: String, CodingKey {
        case text = "Title"
        case images
        case link
        case date
 }

您可以在示例项目中找到一个完整的示例。

序列化

所有对象模型都实现了 Codable 协议，因此您可以轻松地进行序列化和反序列化而无需实现它。以下是实现此协议的对象列表。

• MBProject
• MBBlock
• MBSection
• MBElement
• MBMedia
• MBAddressElement
• MBCheckboxElement
• MBDateElement
• MBDropdownElement
• MBGeneralElement
• MBImagesElement
• MBMarkdownElement
• MBMediaElement
• MBRelationElement
• MBPollElement
• MBTextElement
• MBColorElement
• MBMultipleElement
• MBUser

相等性

所有模型对象都基于相应的 id 符合 Equatable 协议（例如，如果两个 MBSection 对象具有相同的 sectionId，则它们将等于另一个 MBSection 对象）

身份验证

请参阅有关身份验证 API 的完整文档此处。

管理员

如果您需要在MBurger项目中创建区块和部分，可以使用MBAdmin SDK

插件

使用符合MBPluginProtocol的类扩展MBurger的功能，可以添加更多插件到MBurger。例如有MPPayments插件，允许您通过单个支付或订阅形式向用户提供收费服务。

文档

有关更多信息，您可以在docs文件夹中查看完整的SDK参考。

联系我们

您可以通过以下邮箱联系我们：[email protected]。

许可

MBurger遵守Apache 2.0许可。请查看LICENSE获取详细信息。