Dec 17, 2020
Catchoom Team
Augmented Reality, bundle, collection, Image Recognition, on-device, SDK, Unity
This article applies to the CraftAR Unity Augmented Reality SDK for iOS and Android version 4.0 + and CraftAR Unity Pro SDK for iOS and Android version 1.0 +.
In order to add on-device collections to your app developed with our CraftAR Unity Augmented Reality SDK and/or CraftAR Unity Pro SDK, it is necessary to:
This tutorial covers the fourth 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, and for the third step in the tutorial of how to create a Unity app with CraftAR. Once you have the collection added into the device, you can start using your collection with the CraftAR Unity Augmented Reality SDK or the CraftAR Unity Pro SDK.
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 related to the items of the corresponding collection.
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.
To embed the collection bundle into the Unity project, copy the collection bundle zip file into the Assets/StreamingAssets directory.
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.
You can download collection bundles at runtime from the CraftAR service. To do this, you can use the 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 application identifier and SDK version, and directly add the collection to the local database (next section). You can find more details about how to manage these application IDs here.
Adding collection bundles to the local database of the device enables them to be always available for on-device Image Recognition or on-device Augmented Reality. This step only needs to be done once in the app’s lifetime or when you need to update the on-device collection.
Start by initializing the SDK and get access to the CraftAROnDeviceCollectionManager module. Then, check whether your collection has already been added to this device with the method getCollectionWithToken(CollectionToken) of CraftAROnDeviceCollectionManager instance. If not, you will have to different ways to add the collection to the device database, as explained before.
If you want to add the embed collection to the device database, you will have to use the following CraftARCollectionManager method:
1 |
addCollectionFromBundle (CollectionBundleName+".zip"); |
This method will add the collection with the name CollectionBundleName that has been previously embed into the Unity project.
Otherwise, if you want to download collection bundle at runtime from the CraftAR service and then add them to the device database, you will have to use the following CraftARCollectionManager method:
1 |
addCollectionWithToken(CollectionToken); |
This method will download collection bundle with the CollectionToken token at runtime from the CraftAR service and then add them to the device database.
1 2 3 4 5 6 7 8 9 |
CraftAROnDeviceCollection collection = CraftARCollectionManager.instance.getCollectionWithToken(CollectionToken); if (collection == null) { // Add the collection to the local database by downloading the collection bundle from the CraftAR Service CraftARCollectionManager.instance.addCollectionWithToken(CollectionToken); // OR Add the collection to the local database by the embed collection bundle imported into the app // CraftARCollectionManager.instance.addCollectionFromBundle (CollectionBundleName+".zip"); } else { // Collection is already added to the device } |
Finally, to know when the collection has been added and is it ready to use, you have to implement the CraftARCollectionManagerCallbacks interface, which have the following callback handlers:
1 2 3 4 5 |
void CraftARCollectionManager.CraftARCollectionManagerCallbacks.CollectionAdded(CraftAROnDeviceCollection collection) {} void CraftARCollectionManager.CraftARCollectionManagerCallbacks.AddCollectionFailed(CraftARError error) {} void CraftARCollectionManager.CraftARCollectionManagerCallbacks.AddCollectionProgress(float progress) {} |
Some applications, for instance, experiences for catalogs may require that the app synchronizes the collection often. If this is the 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 Unity SDK, call collection.Sync() after setting its callback handler collection.setCraftAROnDeviceCollectionCallbacksHandler(this) to synchronize the collection.
1 2 3 4 5 6 7 8 9 10 11 |
void CraftARSDK.CraftARSDKCallbacks.CraftARReady() { .... collection.setCraftAROnDeviceCollectionCallbacksHandler(this); collection.Sync(); } void CraftAROnDeviceCollection.CraftAROnDeviceCollectionCallbacks.SyncFinished(CraftAROnDeviceCollection collection) {} void CraftAROnDeviceCollection.CraftAROnDeviceCollectionCallbacks.SyncProgress(CraftAROnDeviceCollection collection, float progress) {} void CraftAROnDeviceCollection.CraftAROnDeviceCollectionCallbacks.SyncFailed(CraftAROnDeviceCollection collection, CraftARError error) {} |
This call will do the following:
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.
Note: After modifying the items in your collection you don’t need to re-generate the collection bundle.
When an error is produced in a bundle management operation in the SDK, the SDK triggers a callback with a CraftARError that includes its code and message. For example, you can get an AddCollectionFailed callback when you are trying to add a collection, and there is an incompatibility between the SDK and this collection bundle. The following example shows how to log the error message that you would get in this case.
1 2 3 |
void CraftARCollectionManager.CraftARCollectionManagerCallbacks.AddCollectionFailed(CraftARError error) { Debug.Log ("AddCollectionFailed: " + error.errorMessage); } |
When a collection is not longer valid, the method getCollection will return null for that collection, as it didn’t exist. So, in that case you should add the bundle again. If you try to add an outdated bundle, an error will be triggered in the addCollectionFailed callback. You should always add a bundle that is compatible with the app.