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:
- Create an on-device collection in CraftAR
- Generate a collection bundle for your SDK version (CraftAR Pro SDK or Augmented Reality SDK v4 +)
- Create a Unity app with CraftAR Augmented Reality or Pro SDK
- Download the bundle of that collection from CraftAR and add it to the app
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.
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 Unity project
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.
Download the collection bundle from the CraftAR Service
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.
2. Adding collection bundles to the local database
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:
- CollectionAdded: The SDK will trigger this callback when the collection has been added correctly to the device database. This callback has a parameter which is the collection added, in this way you can easily start working with it.
- AddCollectionFailed: If during the add collection process something fails (e.g. if there’s no data connectivity when trying to download the collection, or any other error occurs) the SDK will trigger this callback. This callback has a parameter with the error information, which you can log to know what happened.
- AddCollectionProgress: When the add collection process begins, the SDK will start triggering this callback. The progress parameter is the current % done of that process.
|
1
2
3
4
5
|
void CraftARCollectionManager.CraftARCollectionManagerCallbacks.CollectionAdded(CraftAROnDeviceCollection collection) {}
void CraftARCollectionManager.CraftARCollectionManagerCallbacks.AddCollectionFailed(CraftARError error) {}
void CraftARCollectionManager.CraftARCollectionManagerCallbacks.AddCollectionProgress(float progress) {}
|
3. Syncing your collection
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:
- Ask the CraftAR Service for the current version of the collection to be compared with the bundle.
- If the collection in the device is already the latest version, the SDK will directly trigger the syncSuccessful 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 syncSuccessful callback.
- If the synchronization fails (i.e, if there’s no data connectivity, or any other error occurs), you will receive an error in the syncFailed 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.
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 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.