- Augmented Reality Cordova Plugin v2.4+
- On-device Image Recognition Cordova Plugin v2.4+
- CraftAR Pro Cordova Plugin v2.4+
Are you still using an older version? Previous versions of the SDKs will not receive updates anymore. If you need help transitioning to the newer versions, you can get support through our support channel.
In order to add on-device collections to your Cordova 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 v1.1+, Augmented Reality SDK v5+ or CraftAR Pro v2+);
- download the bundle of that collection from CraftAR and add it to the app
This tutorial covers the 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 added the collection to the device, you can start using your collection with the On-device Image Recognition Cordova Plugin, the Augmented Reality Cordova Plugin or the Pro Plugin.
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 copy the collection bundle zip file into the www folder of your project.
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 it, you can use the method
|
1
2
3
4
5
|
CraftARCollectionManager.addCollectionWithToken("imagerecognition", function(collection) {
// HAVE ON-DEVICE COLLECTION!!!
}, function (error) {
alert("Erroor adding collection: " + error.errorMessage);
}, function(progressFloat) {});
|
The 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 it to the local database. You can skip step 2 and look at step 3 if you need to synchronize your on-device collection.
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 (or both in the Pro version). This step only needs to be done once in the app lifetime or when you need to update the on-device collection.
First, check whether your collection has already been added to this device with the method getCollection() of CraftAROnDeviceCollectionManager module. An Error callback means the collection is not present on the device. In this case, proceed to add the collection to the device:
|
1
2
3
4
5
6
7
8
9
10
11
|
CraftARCollectionManager.getCollectionWithToken("imagerecognition", function(collection) {
// HAVE ON-DEVICE COLLECTION!!!
}, function( error) {
// The collection was not found on the device, add it
CraftARCollectionManager.addCollectionWithToken("imagerecognition", function(collection) {
setCollection(collection);
}, function (error) {
alert("Erroor adding collection: " + error.errorMessage);
}, function(progressFloat() {});
});
|
Note that this can be done from any view. You don’t need to call CraftAR.startView(…) to start adding collections to the device.
3. Syncing your collection
Some applications, such as catalog experiences 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.
Call CraftARCollectionManager.syncCollection(…) to synchronize the collection.
|
1
2
3
4
5
|
CraftARCollectionManager.syncCollection(myCollection, function(collection) {
// Collection sync Done!
}, function (error) {
alert("Error synchronizing collection: " + error.errorMessage);
}, function(progressFloat){});
|
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 bundle in the device already includes the current version of the collection, the SDK will directly trigger the success 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 progress callback. When the synchronization finishes, you will receive the callback to success 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 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.
Note: After modifying the items in your collection you don’t need to re-generate the collection bundle.