This is a piece by one of the biggest public contributors to Ambrosus open-source code for iOS, Max Stein. Max is an iOS Engineer who has been developing mobile applications for the past 7 years. He has worked both with startups and large companies (including Amazon) building iOS applications end-to-end for consumers. Currently, he focuses on building iOS apps for blockchain use cases and he is passionate about delivering blockchain experiences to end users with high-quality UI and UX.

The Ambrosus iOS SDK is now officially released on Github.

Written in Swift 4.0 supporting Xcode 9.0+. It works with apps written in iOS 10+ and supports Objective-C.

What is the Ambrosus iOS SDK?

The Ambrosus iOS SDK makes it easy for iOS app developers to create their own dapps powered by AMB-NET. AMB-NET API gives access to Assets and Events tracked by Ambrosus,. With the SDK you can create iOS apps with end-to-end tracking of any Asset stored on the AMB-NET.

Ambrosus Viewer

Included is a sample application that enables bar code, QR (and all 1D and 2D symbologies) scanning. You can see scanned Assets, and details about Assets and Events scanned. The app provides examples for the SDK’s use in creating iOS dapps with Ambrosus.

Scanning an Asset, viewing its details and events with Ambrosus Viewer

Getting Started

Ready to start working with the SDK? Start by downloading a copy of the repo here.

After downloading unzip, then open the “AmbrosusViewer.xcworkspace” contained in the “AmbrosusViewer” folder. You’ll need Xcode 9.0+ to open it.

Run Ambrosus Viewer (⌘+r), once the apps open tap the folder icon (bottom right) to see the following screen:

Browse Screen in Ambrosus Viewer (bottom right tab)

Several assets come with the app, navigate to the “BrowseViewController.swift” from the projects pane on the left-hand side (located within the AmbrosusViewer workspace at App/Browse/BrowseViewController.swift”):

Take a look at line 27:

private var dataSource = AMBDataStore.sharedInstance.assetStore.all

This screen uses the AMBDataStore ’s AMBAssetStore instance to fetch all AMBAsset ’s in the app.

Clearing the Sample Data

As we could see when running the app, the BrowseViewController already shows 4 sample AMBAsset ’s, to see where these are set open up “SampleFetcher.swift” (located within the AmbrosusViewer workspace at App/SampleFetcher.swift”

Take a look at func fetch() on line 20:

requestSampleJSON() fetches four sample AMBAsset s with AMBEvent s, and stores them in AMBDataStore , used within the BrowseViewController . Clear all data by commenting out requestSampleJSON() , then replace the fetch() function with:

Run the app (⌘+r), then go to the Browse Screen again and it should now not have any samples.

Adding assets from the network

There are no more sample JSONs requested, now query the AMB-NET to download some Assets and Events. Below the commented out requestSampleJSON() add the following call:

This queries AMBNetwork for an AMBAsset , the AMBNetwork.requestAsset(fromId _: completion _:) completion returns an optional asset, so we use a guard statement to ensure the asset is non-nil.

Now that we have an asset returned from AMB-NET we need to store it inside the AMBDataStore ’s AMBAssetStore , to do so add the following below the “Use unwrapped Asset here” comment:

AMBDataStore.sharedInstance.assetStore.insert(asset)

Now he AMBAsset is in the AMBDataStore . The BrowseViewController will return it using AMBDataStore.sharedInstance.assetStore.all

To make sure the request is working properly run the app again (⌘+r) then go to the Browse screen, you should see the following:

Pulling down data from AMB-NET and displaying it on the Browse Screen

Getting Events Associated with an Asset

A instance of AMBAsset has an array of [AMBEvent]? associated with it. The AMBAsset we pulled down has events associated with it, lets fetch these as well. Add the following below the AMBDataStore.sharedInstance.assetStore.insert(asset) we added:

This will query AMBNetwork for all AMBEvent ’s associated with the AMBAsset we requested, because the AMBNetwork.requestEvents(fromAssetId _:completion _:) completion handler returns an optional array of AMBEvent ’s, first we use a guard statement to ensure the events are non-nil.

Now just like with the AMBAsset we want to store all these AMBEvent ’s within the AMBDataStore so the app can fetch all of the AMBEvent ’s associated with this AMBAsset later. Add the following below the “Use unwrapped events here” comment:

AMBDataStore.sharedInstance.eventStore.insert(events)

Viewing the Asset Details Screen

Once the AMBEvent s are stored within the AMBDataStore the app can now pull those Events into the AssetDetailCollectionViewController , run the app (⌘+r). Now go back to the Browse screen but this time select the cell:

Asset Details

You’ll now be presented with the AssetDetailCollectionViewController , you can view all data stored within the Asset. Scroll down to the bottom of this screen and you’ll see the events timeline:

Events Timeline on the Asset Details Screen

Now lets open up the AssetDetailCollectionViewController.swift (Located at “App/AssetDetails/AssetDetailCollectionViewController.swift”).

Take a look at the formatted sections on line 79:

The AssetDetailCollectionViewController uses the asset.formattedSections as its main data source, this provides a formatted array of information pulled down from the Asset to make it easy to display. It also accesses asset.events , which fetches the associated AMBEvent s with this AMBAsset that we stored previously in the AMBDataStore .

By using the asset.formattedSections the AssetDetailCollectionViewController is easily able to populate the various sections such as “idData” and “metadata” as we saw on the screen.

Viewing the Event Details Screen

Run the app again (⌘+r), now go back to the Asset Details screen and scroll to the event timeline at the bottom of the screen. Tap any of the events from the events timeline on the Asset Details screen and you should be presented with a screen similar to this:

Event Details

As you may have guessed with the various sections that are populated here, an AMBEvent object also contains a formattedSections value which has an array of key-value pairs that make it easy to build this type of screen.

Open up “EventDetailsCollectionViewController.swift” and on line 35 you’ll see:

The EventDetailsCollectionViewController is a bit more straightforward since it uses event.formattedSections directly, there are no additional fields it needs to rely on like the AssetDetailsCollectionViewController .

Conclusion

This provides an overview of what can be done with the AMB-NET APIcombined with the Ambrosus iOS SDK. If you are interested in learning more we encourage you to check out the Github page for the SDK, it includes further documentation and more usage examples.

We are really excited to see what the development community will build using this SDK! Don’t hesitate to reach out if you have any questions, simply by email: tech[at]ambrosus.com, or via our other channels!