The following migration steps are included below:

• Migrating Unity Projects to Vuforia Engine 7.2
• Migrating Unity Projects to Vuforia Engine 7.1
• Migrating Unity Projects to Vuforia Engine 6.5
• Migrating Unity Projects to Vuforia Engine 6.2
• Migrating Unity Projects to Vuforia Engine 5.5
• Migrating Unity Projects to Vuforia Engine 5
• Migrating Unity Projects to Vuforia Engine 4

These migration steps generally assume an upgrade from one version prior unless noted otherwise. If you are migrating to a version of Vuforia Engine that is several releases ahead of your existing version, we recommend reading through the intermediate release notes for additional details. Also please refer to our articles documenting the changes in new releases:

• Changes in Vuforia Engine 6.2
• What's New in Vuforia Engine 6
• What's New in Vuforia Engine 5.5
• What's New in Vuforia Engine 5
• What's New in Vuforia Engine 4

Migrating Unity Projects to Vuforia Engine 7.2

Extended Tracking

In Vuforia Engine 7.2, the Extended Tracking API has been deprecated. The functional equivalent continues in the form of the Device Tracker.  Developers can enable Extended Tracking functionality by enabling the Positional Device tracker.

Developers migrating applications which use Image Targets, VuMarks, Multi-Targets, Cylinder Targets or Object Targets and are looking for equivalent Extended Tracking functionality as pre 7.2 should follow these steps:

1. Open the Vuforia Configuration panel (Windows> Vuforia Configuration or Ctrl+Shift+V)
2. Check the "Track Device Pose" option under the "Device Tracker" section
3. Confirm that the Tracking Mode is set to "POSITIONAL"
4. Select "Optimize for Image Targets and VuMarks" for "Fusion Mode"

The following APIs have been deprecated:

• Target.StartExtendedTracking()
• Target.StopExtendedTracking()

Instead of calling these APIs for each target, call TrackerManager.Instance.InitTracker<PositionalDeviceTracker>() once to enable Extended Tracking functionality on all targets. Be sure to start the Device Tracker.

For more information on Extended Tracking, please refer to the Extended Tracking documentation.

Device Tracker

The Device Tracker no longer requires a specific World Center Mode. Device Tracker can work alongside all World Center Modes.

Targets will continue to report pose information when the target is out of view and Device Tracking is enabled. If Device Tracking is not enabled and the target goes out of view, tracking will be lost (NO_POSE).

Device Tracking can be enabled in the Vuforia Configuration Panel as seen in the previous screenshot.

Device Tracking can also be enabled via code:

void Awake()
{
    VuforiaARController.Instance.RegisterVuforiaInitializedCallback(OnVuforiaInitialized);
}
void OnVuforiaInitialized()
{
    deviceTracker = TrackerManager.Instance.InitTracker<PositionalDeviceTracker>();
}

The device tracker can now be started/stopped anytime at runtime without the need to re-initialize the camera with:

deviceTracker.Start();

and

deviceTracker.Stop();

For more information on the Device Tracker, please refer to Using the Device Tracker document

Vuforia Fusion

Also part of Vuforia Engine 7.2, we are updating the Device Tracker to leverage Vuforia Fusion. Vuforia Fusion refers to the internal techniques used by the Vuforia Engine to take advantage of the best platform enablers (such as ARCore and ARKit) while still providing developers with the broadest reach of devices.

Vuforia Fusion works by choosing the best technology for Device Tracking. Please refer to the following list for default priority:

Vuforia Fusion Default Priority:

1. Platform Enablers (ARKit/ARCore)
2. Vuforia VIO
3. Vuforia SLAM

Due to addition of support for platform enablers, it is important that AR content, targets, and physical objects all have their coordinate scale in meters. Objects that do not have their scale set appropriately may not track well.

For more information about Vuforia Fusion, please refer to the Vuforia Fusion documentation.

World Center Mode

• DEVICE - The camera now moves if the device tracker is enabled. If the device tracker is not enabled, the camera will stay fixed at the last position. Targets always moves in this mode.
  
• FIRST_TARGET / SPECIFIC_TARGET - The first Target or the specified target will be at the last position and not move

ARCore

To enable ARCore support in Unity, please refer to Using ARCore with Vuforia document.

Front Facing Camera

Front-facing camera support has been deprecated in Vuforia Engine 7.2.

Vuforia Engine Initialization

Vuforia Engine 7.2 has made some changes to the initialization process that may impact the flow of your application. The default initialization behavior of Vuforia Engine 7.2 is to download the latest device profile in order to deliver the best experience on the device.  Depending on the speed of the user's internet, this could add several seconds to application load. This only occurs the very first time the user launches the app and will not impact application loading in future launches of the app.

It is strongly recommended to allow the Vuforia Engine to fetch the latest device profile. Developers looking to disable this behavior should set the following hint before initializing Vuforia Engine: VuforiaUnity.SetHint(VuforiaHint.HINT_ASYNC_FETCH_OF_LATEST_CALIBRATION, 1);

Migrating Unity Projects to Vuforia Engine 7.1

Vuforia Engine 7.1 included improvements to Database loading and activation. Developers looking to migrate from Vuforia Engine 7.0 to 7.1 that have customized how Databases are loaded and activated via code should review Automatic Database Loading in Unity

Migrating Unity Projects to Vuforia Engine 6.5

The process of migrating projects from Vuforia Engine 6.2 to 6.5 integrated with Unity 2017.2 is outlined here: Migrate Unity Projects from Vuforia Engine 6.2 to 6.5

Migrating Unity Projects to Vuforia Engine 6.2

The Vuforia Unity Extension version 6.2 introduces the global configuration editor, OpenGL 3 support and some other API changes. Frame markers are not supported anymore and have to be replaced by VuMarks. Vuforia Engine 6.2 drops the support for Unity 5.2 and now supports Unity 5.3 and 5.4.

Migration steps:

1. MAKE A BACKUP OF YOUR EXISTING UNITY PROJECT.
   Important: DO NOT SKIP THIS STEP!
2. Make sure your project has been upgraded to Unity 5.3 or 5.4.
3. Do not proceed further in the migration, if step 1 and 2 have not been successfully completed.
4. Download the upgrade script ConfigurationUpgrade.cs and add it to any Assets/Editor folder. It is important to run this script before upgrading Vuforia Engine to version 6.2
5. Select the first scene where Vuforia Engine is used, i.e. with an ARCamera, and select the menu item Vuforia/ExportConfiguration. The new configuration file should be saved as Assets/Resources/VuforiaConfiguration.asset.
6. From the Unity Project view, delete the following folders:
   • Assets/Vuforia
7. Carefully delete only the Vuforia Engine-specific plugin files in the Plugins directory as your project may have other third-party plugins
   • In Assets/Plugins/x86 and Assets/Plugins/x64
     • VuforiaWrapper.bundle
     • VuforiaWrapper.dll
     • VuforiaWrapper.exp
     • VuforiaWrapper.lib
   • In Assets/Plugins/Android
     • VuforiaUnityPlayer.jar
     • Vuforia.jar
     • AndroidManifest.xml
   • In Assets/Plugins/Android/libs/armeabi-v7a:
     • libVuforia.so
     • libVuforiaUnityPlayer.so
     • libVuforiaWrapper.so
   • In Assets/Plugins/Android/src/com:
     • delete the vuforia folder
   • In Assets/Plugins/iOS:
     • libVuforia.a
     • libVuforiaUnityPlayer.a
     • VuforiaUnityPlayer.h
     • VuforiaNativeRendererController.mm
     • VuforiaRenderDelegate.h
     • VuforiaRenderDelegate.mm
   • Delete the folder Assets/Plugins/VuforiaWrapper.bundle
   • In Assets/Plugins/WSA/x64 and WSA/x86
     • Vuforia.dll
     • VuforiaWrapper.dll
8. After removing the necessary files, you may want to close and re-open your Unity project if using source control in your project
9. You may also want to delete the Library folder under your project directory (Unity will generate a new one automatically when re-opening the project)
10. Import vuforia-unity-6-2-x.unitypackage. Make sure that all components are checked and installed.
11. Fix any compiler errors; in particular, you may need to update a few API calls, according to the following API changes:

Additional migration notes for multiple scenes

If your project contains multiple scenes using Vuforia Engine, it might be necessary to manually change settings for each scene. The settings in the global configuration window (Vuforia/Configuration) apply to all scenes in the project. You can change the settings before loading a new scene with the VuforiaConfiguration-class. The changes will apply to all future scenes.
As an example, you can change the loaded and activated datasets for subsequent scenes with this code:
var datasets = new [] { "tarmac" };
VuforiaConfiguration .Instance.DatabaseLoad.DataSetsToLoad = datasets;
VuforiaConfiguration. Instance.DatabaseLoad.DataSetsToActivate = datasets;
SceneManager .LoadScene(...)

Additional migration notes for stereo configurations

If your project uses a Vuforia Engine stereo setup (Optical See-Through or Video See-Through with Vuforia Engine framework), the existing stereo setup is not valid anymore. The ARCamera should contain only a single camera in the editor. To fix this, you can either revert to the ARCamera prefab settings or execute the following steps:

• Remove the second camera in the hierarchy of the ARCamera.
• Change the viewport of the first camera to the whole screen (W and H are 1)

If your existing Vuforia Engine project is integrated with a 3 ^rd party VR SDK, such as GoogleVR or GearVR, the scene may lose its connections ( camera bindings ) to the VR SDK game objects. To fix this, select the VuforiaBehaviour component on the ARCamera and:
For Cardboard / GoogleVR:

• Drag the Head object of the CardboardMain /GvrMain onto the Central Anchor Point field
• Drag the Main Camera Left onto the Left Camera field
• Drag the Main Camera Right onto the Right Camera field

For GearVR / Oculus:

• Drag the CenterEyeAnchor object of the CameraRig onto the Central Anchor Point field
• Drag the LeftEyeAnchor object onto the Left Camera field
• Drag the RightEyeAnchor object onto the Right Camera field

Additional migration notes for KeepAliveBehaviour

The KeepAliveBehaviour has been removed and needs to be replaced by a custom script. Any Vuforia game object can be kept alive with the Unity method DontDestroyOnLoad. It is also possible to delete Vuforia game objects. If trackable game objects are deleted or kept alive, it is necessary to reassociate Vuforia trackables with Unity game objects:
TrackerManager .Instance.GetStateManager().ReassociateTrackables();

Migrating Unity Projects to Vuforia Engine 5.5

The Vuforia Unity Extension version 5.5 incorporates a few API changes and also updates the supported Unity versions to Unity 5.2, 5.3 and 5.4. Unity 4.x is not longer supported - Unity discontinued Unity 4.x support in December 2015.

Note: If you have an existing project that is still based in Unity 4.x, it is recommended to first upgrade it to Unity 5.2.4f1 before proceeding further with the actual migration to Vuforia Engine 5.5.

Important Notes:

1. Once your project has been upgraded from Unity 4 to Unity 5, you will not be able to revert it back to Unity 4; therefore, make sure to create a BACKUP of your project before executing this step.

2. Vuforia Engine 5.0.10 is compatible with Unity 5.x up to and including version 5.3.1f1; do not attempt to upgrade your Vuforia Engine 5.0.10-based project to Unity 5.3.2 or newer versions; simply upgrade to 5.2.4f1 or 5.3.1f1 at most.

3. Vuforia Engine 5.0.9 is compatible with Unity 5.x up to and including version 5.2.4f1; do not attempt to upgrade your Vuforia Engine 5.0.9-based project directly to Unity 5.3.0 or newer versions; simply upgrade to 5.2.4f1.

Additionally, in Vuforia Engine 5.5 a few folders and files have been renamed, by replacing the QCAR prefix with Vuforia:

Migration steps:

1. MAKE A BACKUP OF YOUR EXISTING UNITY PROJECT.
   Important: DO NOT SKIP THIS STEP!
2. Make sure your project has been upgraded to Unity 5.2, in case it was based on Unity 4.x, as explained previously.
3. Do not proceed further in the migration, if steps 1 and 2 have not been successfully completed.
4. From the Unity Project view, delete the following folders:
   • Assets/Vuforia
5. Carefully delete only the Vuforia-specific plugin files in the Plugins directory as your project may have other third-party plugins:
   • in Assets/Plugins:
     • QCARWrapper.bundle
     • QCARWrapper.dll
     • QCARWrapper.exp
     • QCARWrapper.lib
   • in Assets/Plugins/Android:
     • QCARUnityPlayer.jar
     • Vuforia.jar
     • AndroidManifest.xml
   • in Assets/Plugins/Android/libs/armeabi-v7a:
     • libVuforia.so
     • libQCARUnityPlayer.so
     • libQCARUnityWrapper.so
   • in Assets/Plugins/Android/src/com:
     • delete the qualcomm folder
   • in Assets/Plugins/iOS:
     • libVuforia.a
     • libQCARUnityPlayer.a
     • QCARUnityPlayer.h
     • VuforiaNativeRendererController.mm
     • VuforiaRenderDelegate.h
     • VuforiaRenderDelegate.mm
6. After removing the necessary files, you may want to close and re-open your Unity project if using source control in your project
7. You may also want to delete the Library folder under your project directory (Unity will generate a new one automatically when re-opening the project)
8. Import vuforia-unity-android-ios-5-5-x.unitypackage. Make sure that all components are checked and installed.
9. Fix any compiler errors; in particular, you may need to update a few API calls, according to the following API changes:

Additional migration notes for Stereo configurations

If your existing Vuforia Engine 5.0 project makes use of Stereo Cameras and integrates a 3rd party VR SDK, such as Cardboard or Oculus SDK for GearVR, after the migration to Vuforia Engine 5.5 the ARCamera in your scene may lose its connections ( camera bindings ) with the Cardboard Head and Left/Right Main Cameras, or with the CenterAnchor and Left/Right Camera objects of the GearVR/Oculus CameraRig.
This can happen because in Vuforia Engine 5.5 the stereo camera bindings (and other related stereo configuration properties) have been moved from the VuforiaBehaviour component to the new DigitalEyewearBehaviour component of the ARCamera.
To fix this, select the DigitalEyweareBehaiour component on your ARCamera and:

1. set the Eyewear Type to Video See-Through
2. set the Stereo Camera Config field to either Cardboard or GearVR
3. For Cardboard:
   1. Drag the Head object of the CardboardMain onto the Central Anchor Point field
   2. Drag the Main Camera Left onto the Left Camera field
   3. Drag the Main Camera Right onto the Right Camera field
4. For GearVR / Oculus:
   1. Drag the CenterEyeAnchor object of the CameraRig onto the Central Anchor Point field
   2. Drag the LeftEyeAnchor object onto the Left Camera field
   3. Drag the RightEyeAnchor object onto the Right Camera field

Additional notes about migrating Vuforia-Cardboard projects
Vuforia 5.5 also introduces a built-in support for Stereo visualization on Cardboard viewers, without requiring the integration of the Cardboard SDK. So, while you can still make use of the Cardboard SDK, when migrating your project you may also want to consider the possibility of using the new Vuforia built-in support, so to remove your project dependency from the Cardboard SDK.

Migrating Unity Projects to Vuforia Engine 5

The Vuforia Unity API has been refactored, as have the folder structures of the Vuforia Unity extension and samples. These changes bring the Vuforia Unity releases into harmony with the naming conventions and workflow for Vuforia Engine 5.

1. MAKE A BACKUP OF YOUR EXISTING UNITY PROJECT.
   Important: DO NOT SKIP THIS STEP!
2. Remove any ARCamera instance from your scene(s): take note of any custom scripts or components attached to your ARCamera instance before deleting it, as you will need to manually re-add the ARCamera to your scene, and re-add those custom components as well, at the end of your migration.
3. In the Qualcomm Augmented Reality/Script folder, rename the following files and update their class names to match:
   
   

   From	To
   File: QCARBehaviour	File: VuforiaBehavior
   File: DataSetLoadBehaviour	File: DatabaseLoadBehaviour
   Folder: Qualcomm Augmented Reality	Folder: Vuforia

   
   
   
4. Renaming the Qualcomm Augmented Reality folder to Vuforia is necessary to allow Unity to update prefab script component references.
5. From the Unity Project view, delete the following folders:
   • Editor/QCAR/Scripts
   • Vuforia
6. From the Unity Project view, delete the PostProcessBuildPlayer file from the Editor folder.
7. Carefully delete only the Vuforia Engine-specific plugin files in the Plugins directory as your project may have other third-party plugins. The Vuforia Engine plugin files are shown in the following image with Unity's Project View (left) & local file system (right).
   • Unity hides the file extensions. Most plugin files above easy to distinguish. Where multiple files with same name exist, such as QCARWrapper.*, colored lines illustrate relationship to the associated files as displayed in the file system (ex: OS X Finder).
8. After removing the necessary files, you may want to close and re-open your Unity project if using source control in your project.
9. From the latest installer, import vuforia-unity-android-ios-5-0-x.unitypackage. Make sure that all components are checked and installed.

Fix any compiler errors. Mostly will show a class or method containing QCAR not being found.
Simply replace QCAR with Vuforia, except for the following two exceptions:



From	To
Class: DatasetLoadBehaviour	Class: DatabaseLoadBehaviour
Property: QCARManager.QCARFrameIndex	Property: VuforiaManager.CurrentFrameIndex

Once these changes are implemented, following these migration steps:

1. For pre-Vuforia Engine 4 projects, you will need to replace the ARCamera instances in your scenes with an updated 5.0.x ARCamera prefab instance.
   • Be sure to replace any custom scripts that you had attached to the ARCamera
2. Add a valid license key to the App License Key field in VuforiaBehaviour. See: How To add a License Key to your Vuforia Engine App
3. Fix any compile errors that can occur due to the API changes that were introduced with the latest SDK.
4. Build and run.

Migrating Unity Projects to Vuforia Engine 4

Follow these steps to upgrade your Vuforia Engine 3 projects to Vuforia Engine 4.

1. MAKE A BACKUP OF YOUR EXISTING UNITY PROJECT.
   Important: DO NOT SKIP THIS STEP!
2. From the Unity Project view, delete the following folders:
   • Editor/QCAR/Scripts
   • Vuforia
3. From the Unity Project view, delete: PostProcessBuildPlayer.
4. Carefully delete only the Vuforia files in the Plugins directory, since your project can have other third-party plugins. Typically, the Vuforia files look like the following figure:

1. From the latest installer, import vuforia-unity-android-ios-x-x-x.unitypackage. Make sure that all components are checked and installed.
2. Replace the ARCamera instances in your scenes with updated ARCamera prefab instances.
3. Add a valid license key to the App License Key field in VuforiaBehaviour.
4. Fix any compile errors that can occur due to the API changes that were introduced with the latest SDK.
5. Build and run.

There are a few API changes in the Vuforia 4 SDK for Unity that will require code changes to Vuforia Engine projects using prior SDK versions.

1. All occurrences in code of the <ImageTracker> class must be replaced with the <ObjectTracker> class.
2. The ARCamera inspector exposes an additional field for a License Key, see below.
3. The ARCamera no longer includes a camera component, it now utilizes a child Camera object.
4. The QCARRenderer.DrawVideoBackground( boolean ) is no longer present; rather the Video Background rendering can be switched off by disabling the renderer components of the BackgroundPlane object, which is a child of the Camera under ARCamera.

Adding a license key

As of Vuforia Engine 4.0 apps require a license key to unlock the features of the Vuforia Engine platform. You'll need to create a license key in the License Manager and add it to the VuforiaBehaviour component on the ARCamera.

See:
Vuforia License Manager
How To Create an App License
How To add a License Key to your Vuforia Engine App

Code Changes in C#

Vuforia Engine 4.0 also introduces a new Vuforia namespace. You'll need to add the following statement at the top of any scripts that reference the Vuforia API.

using Vuforia;

To retrieve an ImageTracker from the TrackerManager, use the following code:

ObjectTracker ot = TrackerManager.Instance.GetTracker<ObjectTracker>();

To initialize an ObjectTracker through the TrackerManager, use the following code:

ObjectTracker ot = TrackerManager.Instance.InitTracker<ObjectTracker>();

Changes to the ARCamera

The ARCamera now incorporates a child camera instance that defines the Projection type, Clipping Planes and Viewport rectangle for the camera frustom. This camera has a Background Plane child object that serves as the video background for the scene. The device camera image is rendered onto this plane. You can disable video background rendering by disabling this BackgroundPlane object in the scene.