cordova-plugin-vuforia

Cordova-Plugin-Vuforia is a Cordova plugin that uses Vuforia to perform image recognition.

You can see a live example in the Peugeot 208 app on iOS and Android, and an open source example in the cordova-vuforia-example repo.

Contents

• Supported Platforms
• Requirements
  • Dependencies
• Getting Started
  • Plugin Installation
  • JavaScript
    • startVuforia - Start your Vuforia session
      • options object
        • Examples
      • Success callback data API
    • stopVuforia - Stop your Vuforia session
    • stopVuforiaTrackers - Stop Vuforia image trackers
    • startVuforiaTrackers - Start Vuforia image trackers
    • updateVuforiaTargets - Update the list of targets Vuforia is searching for
  • Using your own data
    • www/targets/
    • JavaScript
      • startVuforia(...)
    • config.xml
• Contributing
• License

Supported Platforms

Android (Minimum 4), iOS (Minimum 8)

Requirements

NOTE: You will require an Android or iOS device for development and testing. Cordova-Plugin-Vuforia requires hardware and software support that is not present in either the iOS or Android simulators.

Cordova-Plugin-Vuforia requires the following:

• npm
• Cordova 6.* - 6.* is required as of v2.1 of this plugin, it adds support for Android 6 (Marshmellow) and iOS 9.
  • If you haven't yet installed the Cordova CLI, grab the latest version by following these steps.
  • If you've already got a project running with an older version of Cordova, see here for instructions on how to update your project's Cordova version.
  • Or if you want to upgrade to the latest version on a platform-by-platform basis, see either upgrading to cordova-ios 4 or upgrading to cordova-android 5.

Dependencies

At present there is one major dependency for Cordova-Plugin-Vuforia:

• Cordova-Plugin-Vuforia-SDK - This plugin is used to inject the Vuforia SDK into our Cordova applications

Getting Started

Plugin Installation

cordova plugin add cordova-plugin-vuforia

JavaScript

Cordova-Plugin-Vuforia comes with the following JavaScript methods:

Method	Description
startVuforia	Begin a Vuforia session - Launch the camera and begin searching for images to recognise.
stopVuforia	Stop a Vuforia session - Close the camera and return back to Cordova.
stopVuforiaTrackers	Stop the Vuforia tracking system - Leave the Vuforia camera running, just stop searching for images.
startVuforiaTrackers	Start the Vuforia tracking system - Leave the Vuforia camera running and start searching for images again.
updateVuforiaTargets	Update Vuforia target list - Update the list of images we are searching for, but leave the camera and Vuforia running.

startVuforia - Start your Vuforia session

From within your JavaScript file, add the following to launch the Vuforia session.

var options = {
  databaseXmlFile: 'PluginTest.xml',
  targetList: [ 'logo', 'iceland', 'canterbury-grass', 'brick-lane' ],
  overlayMessage: 'Point your camera at a test image...',
  vuforiaLicense: 'YOUR_VUFORIA_KEY'
};
 
navigator.VuforiaPlugin.startVuforia(
  options,
  function(data) {
    // To see exactly what `data` can return, see 'Success callback `data` API' within the plugin's documentation.
    console.log(data);
    
    if(data.status.imageFound) {
      alert("Image name: "+ data.result.imageName);
    }
    else if (data.status.manuallyClosed) {
      alert("User manually closed Vuforia by pressing back!");
    }
  },
  function(data) {
    alert("Error: " + data);
  }
);

NOTES:

• You will need to replace YOUR_VUFORIA_KEY with a valid license key for the plugin to launch correctly.
• For testing you can use the targets/PluginTest_Targets.pdf file inside the plugin folder; it contains all four testing targets.

options object

The options object has a number of properties, some of which are required, and some which are not. Below if a full reference and some example options objects

Option	Required	Default Value	Description
databaseXmlFile	true	null	The Vuforia database file (.xml) with our target data inside.
targetList	true	null	An array of images we are going to search for within our database. For example you may have a database of 100 images, but only be interested in 5 right now.
vuforiaLicense	true	null	Your application's Vuforia license key.
overlayMessage	false	null	A piece of copy displayed as a helpful hint to users i.e. 'Point your camera at the orange target'. Providing no message will hide the overlay entirely
showDevicesIcon	false	false	Display a device icon within the overlay. This can be a helpful hint for users i.e. 'Scan any page with the device icon on it.' By default, this is false (the icon is hidden)
showAndroidCloseButton	false	false	Show a close icon on-screen on Android devices. This is helpful if your Android device's back button is hidden/disabled. By default, this is false (no close button is shown on Android)
autostopOnImageFound	false	true	Should Vuforia automatically return to Cordova when an image is found? This is helpful if you want to scan for multiple images without re-launching the plugin. By default, this is true (when an image is found, Vuforia returns to Cordova)

Examples

Minumum required

var options = {
  databaseXmlFile: 'PluginTest.xml',
  targetList: [ 'logo', 'iceland', 'canterbury-grass', 'brick-lane' ],
  vuforiaLicense: 'YOUR_VUFORIA_KEY'
};

Complete options

var options = {
  databaseXmlFile: 'PluginTest.xml',
  targetList: [ 'logo', 'iceland', 'canterbury-grass', 'brick-lane' ],
  vuforiaLicense: 'YOUR_VUFORIA_KEY',
  overlayMessage: 'Point your camera at a test image...',
  showDevicesIcon: true,
  showAndroidCloseButton: true,
  autostopOnImageFound: false
};

Success callback data API

startVuforia takes two callbacks - one for success and one for faliure. When success is called, a data object is passed to Cordova. This will be in one of the following formats:

Image Found - when an image has been successfully found, data returns:

{
  "status": {
    "imageFound": true,
    "message": "Image found."
  },
  "result": {
    "imageName": "IMAGE_NAME"
  }
}

NOTE: imageName will return the name of the image found by Vuforia. For example, with the above options objects, brick-lane would be sent when the brick-lane image was found.

Manually Closed - when a user has exited Vuforia via pressing the close/back button, data returns:

{
  "status": {
    "manuallyClosed": true,
    "message": "User manually closed the plugin."
  }
}

stopVuforia - Stop your Vuforia session

From within your JavaScript file, add the following to stop the Vuforia session. stopVuforia takes two callbacks - one for success and one for faliure.

Why? - Well, you could pair this with a setTimeout to give users a certain amount of time to search for an image. Or you can pair it with the autostopOnImageFound option within startVuforia to have more granular control over when Vuforia actually stops.

navigator.VuforiaPlugin.stopVuforia(
  function (data) {
    console.log(data);
 
    if (data.success == 'true') {
        alert('Stopped Vuforia');
    } else {
        alert('Couldn\'t stop Vuforia\n'+data.message);
    }
  },
  function (data) {
    console.log("Error: " + data);
  }
);

This script could be paired with a timer, or other method to trigger the session close.

NOTE: You do not need to call stopVuforia() other than to force the session to end. If the user scans an image, or chooses to close the session themselves, the session will be automatically closed.

stopVuforiaTrackers - Stop Vuforia image trackers

From within your JavaScript file, add the following to stop the Vuforia image trackers (but leave the camera running). stopVuforiaTrackers takes two callbacks - one for success and one for faliure.

Why? - Well, you may want to play a sound after an image rec, or have some kind of delay between recognitions.

navigator.VuforiaPlugin.stopVuforiaTrackers(
  function (data) {
    console.log(data);
    
    alert('Stopped Vuforia Trackers');
  },
  function (data) {
    console.log("Error: " + data);
  }
);

startVuforiaTrackers - Start Vuforia image trackers

From within your JavaScript file, add the following to start the Vuforia image trackers. This method only makes sense when called after stopVuforiaTrackers. startVuforiaTrackers takes two callbacks - one for success and one for faliure.

Why? - Well, you may want to play a sound after an image rec, or have some kind of delay between recognitions.

navigator.VuforiaPlugin.startVuforiaTrackers(
  function (data) {
    console.log(data);
    
    alert('Started Vuforia Trackers');
  },
  function (data) {
    console.log("Error: " + data);
  }
);

updateVuforiaTargets - Update the list of targets Vuforia is searching for

From within your JavaScript file, add the following to update the list of images Vuforia is searching for. updateVuforiaTargets takes three options, an array of images you want to scan for, a callback for success and a callback for faliure.

Why? - Well, you may want to change the images you are searching for after launching Vuforia. For example, consider a scenario where a game requires users to scan images one after another in a certain order. For example, a museum app may want you to scan all of the Rembrandt paintings in a room from oldest to newest to unlock some content. This method can offload the burdon of decision from your app to Vuforia, instead of writing login in your JavaScript, we're letting Vuforia take care of it.

navigator.VuforiaPlugin.updateVuforiaTargets(
    ['iceland', 'canterbury-grass'], // Only return a success if the 'iceland' or 'canterbury-grass' images are found.
    function(data){
        console.log(data);
        
        alert('Updated trackers');
    },
    function(data) {
        alert("Error: " + data);
    }
);

Using your own data

We know that eventually you're going to want to use your own data. To do so, follow these extra steps.

www/targets/

First, create a targets/ folder inside www/ and place your own .xml and .dat files inside.

NOTE: Adding a .pdf file isn't required, but might be helpful for testing and development purposes.

JavaScript

startVuforia(...)

There are two pieces you will need to replace:

1. PluginTest.xml - Replace with a reference to your custom data file e.g. www/targets/CustomData.xml
2. [ 'logo', 'iceland', 'canterbury-grass', 'brick-lane' ] - Replace with the specific images for your data file that you are searching for.

NOTES:

• You don't have to search for all of the images in your data file each time. Your data file may contain 20 images, but for this particular action you may be only interested in two.
• Data file paths can be either from the resources folder (which is the default) or absolute (in which case you'd start the src with file://). Absolute paths are useful if you'd like to access files in specific folders, like the iTunes sharing document folder for iOS, or the app root folder for Android.

config.xml

Add the following to your config.xml file:

<platform name="android">
    <resource-file src="www/targets/CustomData.xml" target="assets/CustomData.xml" />
    <resource-file src="www/targets/CustomData.dat" target="assets/CustomData.dat" />
</platform>
 
<platform name="ios">
    <resource-file src="targets/CustomData.xml" />
    <resource-file src="targets/CustomData.dat" />
</platform>

Contributing

If you wish to submit a bug fix or feature, you can create a pull request and it will be merged pending a code review.

1. Clone it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

Cordova-Plugin-Vuforia is licensed under the MIT License.