Working with VuMarks in Unity

The Vuforia VuMark Sample project for Unity provides a pre-configured VuMark scene that you can use as a reference and starting point for your own VuMark apps. This article will show you how to author content on top of the sample, how to customize event handling for the detection and tracking of VuMarks, and how to read and respond to data encoded in a VuMark instance.

Unity Setup for Vuforia Engine

Import the VuMark sample together with the Core samples available on the Unity Asset Store website or from the Vuforia Developer portal. By importing the sample, the Vuforia Engine SDK for Unity will automatically be imported and configured as well.

Add a License Key

The Core samples available on the Asset Store will work without a Vuforia license key. However, to use a custom VuMark database created by yourself, it is necessary to add a license key to the Vuforia Configuration in Unity.The license key can be created in the License Manager on the Developer Portal. Go to Vuforia Configuration with the shortcut key bindings cmd+shift+V for Mac and ctrl+shift+V for Windows. 

See also: How To add a License Key to your Vuforia Engine App

Setup VuMark in Unity

Start by locating the VuMark scene in the Project Folder at Assets/SamplesResources/Scenes/3-VuMarks. Open the scene. The VuMark sample's scene Hierarchy demonstrates how to set-up a Vuforia VuMark scene in Unity.

For a general introduction to the Vuforia Engine setup and components in the Unity Editor, please see Getting Started with Unity


The VuMark GameObject encapsulates the VuMark Behaviour which ensures that your VuMark instances will be detected. It also holds the primary script component, the Default Observer Event Handler, where you can assign events when instances are found.

In the VuMark Behaviour component, the ID Type and ID Length is shown for the VuMark database.

The Track From Appearance lets you signal to the Vuforia Engine whether it should also track the VuMark Background.

  1. A VuMark GameObject is created by right-clicking in the Hierarchy and then select Vuforia Engine -> VuMark.

    TIP: Add content as a child of the VuMark GameObject that you wish to have present on all VuMark instances. See the VuMarkHandler.cs for insights on adding content to certain VuMark instances identified by their ID data.

In the VuMark Behaviour component, the ID Type and ID Length shows the VuMark database size and type. The VuMark scene from the sample uses a database with type NUMERIC encoded data supporting up to 4. See VuMark Setup Script for details

The Track From Appearance lets you signal to the Vuforia Engine whether it should also track the VuMark Background.

  • Enable it if you have VuMarks that have different backgrounds for each instance.
  • Keep it disabled when the VuMark instances’ backgrounds match that of the VuMark Template (which they were created from). See VuMark Design Guide for more information on VuMark background.

Add Occlusion to your VuMark or a Target Representation with the available buttons in the Behaviour component. See Adding Vuforia Engine Features for details.

Select a tracking mode fitting to your use case; Default for the majority of tracking scenarios and AR_Controller if you are using VuMark instances as markers on handheld controllers. Note that Device Tracking is disabled when AR_Controller is enabled.

Build Settings

To build and test the Core Sample, add all of the scenes in the /SamplesScenes folder to Scenes In Build in File -> Build Settings window. Depending on your device, select Android, iOS or Universal Windows Platform as the build Platform.

Then, proceed to name your app’s Bundle Identifier in Player Settings -> Publishing tab. Connect your device and click Build and Run

Using PlayMode

Alternatively, test the scene and VuMark by using Vuforia’s Play Mode. Press the Play button at the top of the Unity Editor and use an inbuilt or attached webcam to detect and track the activated VuMark databases.

See Vuforia Play Mode for Unity.

Customizing the Sample

The quickest possible way to test your own VuMark database is to exchange the VuMark GameObject’s database with your own in the VuMark Behaviour component.

  1. Follow the instructions on creating your own VuMark Template in Adobe Illustrator and download the resulting database as a .unitypackage from the Vuforia Target Manager. 
  2. Import the database into your Unity project by selecting Assets -> Package -> Custom Package. 
  3. Select the VuMark GameObject and replace the Database in the dropdown menu with your own. 
  4. Make sure to add a Vuforia License key as described in How To add a License Key to your Vuforia Engine App
  5. Test your VuMark instances by generating and download them from the Target Manager and print them without scaling them. A guide on generating instances can be found in How to Work with VuMark Databases.

Further customization

Default Observer Event Handler

The Default Observer Event Handler component is responsible for handling callbacks to the VuMark Behaviour arising from changes in the status and tracking information of the VuMark’s TargetStatus, such as when it has been detected and is being tracked.
Extend the script’s OnTrackingFound() and OnTrackingLost() methods to implement custom event handling for your VuMark and app. See Status Poses and Status Info for details on the VuMark’s tracking statuses.

Enabling/Disabling Extended Tracking

Using the Device Tracking and Extended Tracking enables you to maintain tracking for a scene even when the VuMark is no longer in the camera view.

Device Tracking is enabled by default, but you can manage it at build time in the Vuforia Configuration or at runtime at initialization by calling the DeviceBehaviour.OnEnable(). Control when to render augmentations if tracking accuracy of a target is reduced significantly; when the status is switched to LIMITED, you may choose between continuing rendering augmentations or wait until EXTENDED_TRACKING is reported once again.  

See: Device Tracking Overview

VuMark sizes

The size of a VuMark is controlled through its template and needs to correspond to the physical size of the printed VuMark. All instances of the template will use the same size.

For use cases where different VuMark instances are differently sized, you can use the setHeight() and setWidth() methods of the VuMark class to change the size at runtime. You can also use the Virtual Scene Scale Factor in Unity to translate between real-world size and virtual scale in your Unity scene.

If two different sized VuMark instances of the same template are being tracked at the same time, at least one of them will be scaled wrongly. To avoid unexpected tracking effects, disable the Track Device Pose in such a case.

Can this page be better?
Share your feedback via our issue tracker