In order to add on-device collections to your iOS app, it is necessary to:
- create an on-device collection in CraftAR;
- generate a collection bundle for your SDK version (On-device Image Recognition SDK or Augmented Reality SDK v4 +;
- download the bundle of that collection from CraftAR and add it to the app;
- you are ready to go and start using the on-device collection with the SDK
This tutorial covers third step. You can find more details for the first and second steps in the tutorial about how to create a collection in CraftAR for on-device image recognition or on-device Augmented Reality. Once you have the collection added into the device, you can start using your collection with the on-device Image Recognition SDK or the Augmented Reality SDK v4 +.
On-device collection bundles represent a collection from the CraftAR service that can be added to a device in order to do Image Recognition or Augmented Reality on the device, without the need to connect to the network. They contain the image database and metadata of the items of the corresponding collection.
1. Adding collection bundles to the app
You can decide to create apps that have the collection bundle embedded or download the collection bundle from the CraftAR Service. The first option will increase the size of your app but will make the first use faster for the user. The second option is the opposite case and has the extra advantage that you can publish your app and modify the collection bundle later on.
Embed the collection bundle into the app
To embed the collection bundle into the app drag the downloaded zip file to the Copy Bundle Resources Build phase of your app target in xCode.
Download the collection bundle from the CraftAR Service
You can download collection bundles at runtime from the CraftAR service. With the [CollectionManager addCollectionWithToken: withOnProgress: andOnError:] method the SDK will retrieve the bundle for the collection with the provided token from the CraftAR service. This method will download the latest available bundle matching your appID and SDK version, and directly add it to the local database..
After adding the collection bundle to the app it is also necessary to add the bundle to the local database. See the next section for details.
2. Adding collection bundles to the local database
Add collection bundles to the local database of the device, allows to have them always available for on-device Image Recognition or on-device Augmented Reality. This step only needs to be done once in the app lifetime or when you need to update the on-device collection.
Start by initializing the SDK and get access to the CraftARCollectionManager module. Then, check whether your collection has already been added to this device with the method getCollectionWithToken of CraftARCollectionManager.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
mSDK = [CraftARSDK sharedCraftARSDK]
// Get the collection manager
mCollectionManager = [CraftARCollectionManager sharedCollectionManager];
NSError* error;
// Get the collection if it is already in the device
CraftARCollection* demoCollection=
[mCollectionManager getCollectionWithToken:@"catchoomcooldemo" withError: &error];
if (error != nil ) {
// Error getting collection
}
// if it is not in the device load it
if (demoCollection == nil) {
[self addDemoCollection];
} else {
// demo collection is already added to the device
}
|
Note: This can be done either in the AppDelegate or in a UIViewController.
If the collection is not in the device, it can be added by providing the path for the collection bundle file. This will extract the reference image database and store it in the user storage. This process may take a few seconds if the collection is big so the SDK provides feedback to implement a progress bar.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
- (void) addDemoCollection {
MainScreenViewController* myself = self;
// Get the collection bundle file that contains the image database for recognition
NSString* bundlePath = [[NSBundle mainBundle] pathForResource:
@"catchoomcooldemoBundle" ofType: @"zip"];
// Add the collection to the device
[mCollectionManager addCollectionFromBundle:bundlePath withOnProgress:^(float progress) {
NSLog(@"Add bundle progress: %f", progress);
} andOnSuccess:^(CraftARCollection *collection) {
// the collection is now added to the device
} andOnError:^(NSError *error) {
NSLog(@"Error adding collection: %@", [error localizedDescription]);
}];
}
|
Alternatively, you can download the bundle from the CraftAR service using the collection token:
|
1
2
3
4
5
6
7
|
[mCollectionManager addCollectionWithToken:@”yourcollectiontoken” withOnProgress:^(float progress) {
// progress
} andOnSuccess:^(CraftARCollection *collection) {
// Collection downloaded and added
} andOnError:^(NSError *error) {
// Error
}];
|
3. Syncing your collection
Some applications as catalogs require that the app synchronizes the collection often. If this is your case, you might consider using collection synchronization. In this section we will briefly explain how to synchronize the collections in your app with your collections in CraftAR.
This method works on all our SDKs. However, at the moment it does not download the augmented reality contents. We recommend its use for image recognition or when the augmented reality contents are added programmatically.
In the SDK, call [CraftARCollection syncWithOnProgress: andOnSuccess: andOnError:] to synchronize the collection.
This call will do the following:
- Ask the CraftAR Service for the current version of the collection to compare it with the bundle.
- If the collection in the device is already the latest version, the SDK will directly trigger the OnSuccess callback.
- If the collection in the device is outdated, the call will download the new and changed items and update the collection in the app. When the collection is synchronizing, you will receive the progress in the syncProgress callback. When the synchronization finishes, you will receive the callback to OnSuccess.
- If the synchronization fails (i.e, if there’s no data connectivity, or any other error occurs), you will receive an error callback. Depending on your use case, you might consider loading the collection even if it’s outdated, or avoid loading it.
We recommend you try to sync your collections when the app starts (for example, at the Splash screen), but this is completely up to you. Check our github examples for on-device-image-recognition to see how to load and synchronise your collections in a Splash screen.
Note: After modifying the items in your collection, you don’t need to re-generate the collection bundle.
4. Handling errors
When an error is produced in a bundle management operation in the SDK, the SDK triggers a callback with an NSError or generates an error if the operation is not asynchronous.
When there is an incompatibility between the SDK and the added collection bundle a runtime error is produced. There are two types of version compatibility errors:
- COLLECTION_BUNDLE_VERSION_IS_OLD which is produced when there is an attempt to add a bundle that was generated for a version of the SDK that is older than the one running in the app; and
- COLLECTION_BUNDLE_SDK_VERSION_IS_OLD which is produced when there is an attempt to add a bundle that was generated for a version of the SDK that is newer than the one running in the app.