MBurgerSwift is a client libary, written in Swift, that can be used to interact with the MBurger API. The minimum deployment target for the library is iOS 10.0.
With Xcode 11 you can start using Swift Package Manager to add MBurgerSwift to your project. Follow those simple steps:
- In Xcode go to File > Swift Packages > Add Package Dependency.
- Enter
https://github.com/Mumble-SRL/MBurgerSwift.gitin the "Choose Package Repository" dialog and press Next. - Specify the version using rule "Up to Next Major" with "1.0.7" as its earliest version and press Next.
- Xcode will try to resolving the version, after this, you can choose the
MBurgerSwiftlibrary and add it to your app target.
CocoaPods is a dependency manager for iOS, which automates and simplifies the process of using 3rd-party libraries in your projects. You can install CocoaPods with the following command:
$ gem install cocoapodsTo integrate the MBurgerSwift into your Xcode project using CocoaPods, specify it in your Podfile:
platform :ios, '10.0'
target 'TargetName' do
pod 'MBurgerSwift'
endIf you use Swift rememember to add use_frameworks! before the pod declaration.
Then, run the following command:
$ pod install
CocoaPods is the preferred methot to install the library.
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate MBurgerSwift into your Xcode project using Carthage, specify it in your Cartfile:
github "Mumble-SRL/MBurgerSwift"
To install the library manually drag and drop the folder MBurgerSwift to your project structure in XCode.
Note that MBurgerSwift has MBNetworkingSwift (1.0.4) as dependency, so you have to install also this library.
To initialize the SDK you have to create a token through the dashboard. Click on the settings icon on the top-right and create a API Key specifiyng the permissions.
Then in your AppDelegate application:didFinishLaunchingWithOptions: initialize the MBManager of the SDK setting a token like this:
import MBurgerSwift
...
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
MBManager.shared.apiToken = "YOUR_API_TOKEN"
return true
}You will not be able to interact with the SDK if you don't initialize it with a correct token/key.
Use the MBClient class to make all the request to the api to retrieve data from MBurger. All the api calls have a plural version and its singular counterpart. For example you can retrieve the list of blocks of the project or you can retrieve a single block giving its id.
You can retrieve the informations of the project like this:
MBClient.getProject(success: { project in
}, failure: { error in
})You can retrieve the blocks of the project with the function getBlocks(Success:Failure) like this:
MBClient.getBlocks(success: { (blocks, paginationInfos) in
}, failure: { (error) in
})The parameter parameters is an optional array of objects that conforms to the MBParameter protocol passed to the MBurger api as parameter. The majorityof the parameters that can be passed to the apis are already defined in the SDK and can be used after the initialization:
MBSortParameterMBPaginationParameterMBFilterParameterMBGeofenceParameter
If you want to pass another type of parameter you can use the MBGeneralParameter class that can be initialized with a key and a value that will be passed to the apis.
So if you want to include a pagination parameter you can do like this:
let paginationParam = MBPaginationParameter(skip: 0, take: 10)
MBClient.getBlocks(withParameters: [paginationParam], success: { (blocks, paginationInfos) in
}, failure: { (error) in
})There is another version of the getBlocks(withParameters:success:failure:), that takes two aditional parameter includingSections (a boolean that indicate whether or not include, for each block, the sections), and includeElements (a boolean value that do the same thing but for the elements of the sections).
So you could retrieve the informations of all the blocks, all the sections of the blocks and all the elements of the sections with this call:
MBClient.getBlocks(withParameters: [paginationParam], includingSections: true, includeElements: true, success: { (blocks, paginationInfos) in
}, failure: { (error) in
})You can retrieve all the sections with a block with the given id with the function getSections(ofBlock:parameters:success:failure:) like this:
MBClient.getSections(ofBlock: THE_BLOCK_ID, parameters: nil, success: { (sections, paginationInfos) in
}, failure: { (error) in
})Like for the blocks there's a version of this function that takes a bool elements that indicate to include or not the elements of the section se if you want to retrieve all the sections of a block and their elements you can call:
MBClient.getSections(ofBlock: THE_BLOCK_ID, parameters: nil, elements: true, success: { (sections, paginationInfos) in
}, failure: { (error) in
})You can retrieve a media stored on MBurger with its id:
MBClient.getMedia(withId: MEDIA_ID,
success: { media in
},
failure: { error in
})To retrieve all the media that are saved in MBurger you can use this function:
MBClient.getAllMedia(success: { media in
},
failure: { error in
})MBurgerSwift has a built in system that can be used to init your custom constructs. You have only to make your construct conform to MBDecodable protocol.
For example a News that's reflecting a newsfeed block in 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)
}
}And call the decode function of MBDecoder to create and populate an array of news like this:
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)
}) Note that the DecoderCodingKey needs to match to the name of the element in the MBurger block(e.g. if the element on the dashboard is called Title the decoder key needs to be Title):
enum DecoderCodingKeys: String, CodingKey {
case text = "Title"
case images
case link
case date
}You can find a complete example in the Example project.
All the object models implement the Codable protocol so you can serialize and deserialize them without having to implement it. Below the list of objects that implement this protocol.
MBProjectMBBlockMBSectionMBElementMBMediaMBAddressElementMBCheckboxElementMBDateElementMBDropdownElementMBGeneralElementMBImagesElementMBMarkdownElementMBMediaElementMBRelationElementMBPollElementMBTextElementMBColorElementMBMultipleElementMBUser
All the model objects are conform to the Equatable protcol based on the corresponding id (e.g. an MBSection will result equal to another MBSection object if they have the same sectionId)
Read the full documentation for authentication apis here.
If you need to create blocks and sections in your MBurger project you can use the MBAdmin SDK
You can add more to MBurger with plugins, classes that conforms to the MBPluginProtocol that can extend the functionalities of MBurger. An example of a plugin is MPPayments a plugin that you to charge the users with single payments or sbscription.
For further information, you can check out the full SDK Reference in the docs folder.
You can contuct us at info@mumbleideas.it.
MBurger is released under the Apache 2.0 license. See LICENSE for details.