How To Migrate a Unity Project

The following migration steps are included below:

Unity Extension 8.1 Migration Guide
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

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

Vuforia Unity Extension 8.1 Migration Guide

New Platform Support
1. Android ARM64 Support
  Vuforia 8.1 now supports ARM64 bit on Android. Simply select IL2CPP as your scripting backend and add ARM64 to the Target Architectures in the Android player settings of your project:
2. BitCode Support
  The iOS version of Vuforia 8.1 now contains Bitcode. Provided any other dependencies of your project also contain Bitcode, you may build with Bitcode enabled and use this for App Store submission. It is recommended to test Bitcode recompilation by making an Archive build and then exporting an Ad Hoc .ipa, selecting the "Recompile from Bitcode" option.
  
  Bitcode is automatically enabled by Unity when it creates the Xcode project. To build without Bitcode, edit the project and turn it off.
  
  Note that due to a limitation in the recompilation process, if you are going to build for Bitcode then you must embed VuforiaDL.framework in your app even if you are not using a feature that requires it. This is the default behaviour.
API and Workflow Changes
1. Model Target 3D Guide View Extraction
  With Vuforia 8.1, we have changed the mechanism for Model Target extraction in Unity. The extracted 3D models are used for guide views and editor previews of Model Targets. Previously, the 3D mesh was extracted and set up in a Unity scene once “3D guide view” was selected for a model target in that scene.
  This has now changed so that the mesh is extracted at the time a Model Target dataset is imported into a Unity project. At that time, a prefab is created on the project level in the Resources/VuforiaModels folder. This prefab is used by default for both the editor preview of a model target and when 3D guide views are used at runtime. This makes it easier to update all instances of Model Targets when importing a new version of a database into the project.
  The model extraction can be disabled in the Vuforia configuration if the extracted 3D models are not needed for guide views, preview models, augmentations or if you want to reduce the size of your application.
  If model target extraction is disabled, 3D guide views are not available for model targets in your project.
  If your Vuforia 8.0 (or earlier) project used 3D Model Target guide views, please follow these steps to migrate it to Vuforia 8.1:
  - Open the project with new Vuforia SDK 8.1 -> notice that a new folder Resources/VuforiaModels is generated
  - If your project used the extracted models for anything other than 3D guide view functionality (e.g. as augmentation assets), you’ll need to assign the guid of the old prefab to the new prefab:
    - Close the Unity editor
    - Open meta-files of old (Assets/Models/) and new (Resources/VuforiaModels/) prefab and swap the guid values of the two prefabs
    - Open Unity editor again and verify that new prefabs are used in your scene
    - Alternatively, you can manually replace all instances of 3D guide view prefabs with the new prefab by manually adding them to the scene
  - If you no longer need them, delete all previously extracted 3D models from the folder Assets/Models. There is a separate subfolder for each database.
2. Public changes to Image class
  The Vuforia Image class has been refactored and optimized for better memory usage. This resulted in the following changes for Vuforia 8.1:
  - The enum Image.PIXEL_FORMAT is replaced by PIXEL_FORMAT. If you used that enum in your code, you’ll need to fix any compiler errors by changing to the new enum.
  - The PIXEL_FORMAT.YUV format was replaced with more explicit format YUV formats by introducing PIXEL_FORMAT.NV21 and PIXEL_FORMAT.NV12.
    If you previously used the YUV format you now need to check for the NV21 or NV12 formats.
    Please note that not all formats are supported on every platform. Rule of thumb:
    - NV12: native image format on iOS and UWP tablet devices
    - NV21: native image format on Android
      There are exceptions to this, for example the Google Pixel C device uses other YUV based formats
  - Image.IsValid() has been marked deprecated and can be replaced with the static Image.IsNullOrEmpty(Image) method.
  - Image.Clear() and Image.ClearUnmanagedData() have been removed, they are not required anymore.
Removed APIs and Features
1. Front Camera Support
  The previously deprecated front camera functionality has been removed with Vuforia 8.1. You can now only access the back camera.
  
  As part of this change, the reflection flag was removed as well, which was enabling mirrored rendering. If you still need to have mirror rendering due to your current setup, this is best done in a post processing effect in Unity.
2. Model Recognition Template Mode
  The template mode for trained Model Targets has been removed with Vuforia 8.1. If you used Model Recognition in your Vuforia 8.0 Unity project, please follow these steps:
  - If you did not use template mode, just remove the template object below the Model Recognition game object in your Unity scene
  - If you did use templates in your project, please follow these steps to implement a similar mechanism on application level:
    - Keep the template game object and make sure that no dataset has been assigned to it (editor shows ---EMPTY--- dataset)
    - Create a custom ModelRecoEventHandler by copying the DefaultModelRecoEventHandler script
    - Instantiate the template object in the OnNewSearchResult method
3. Other removed APIs
  The following methods, interfaces and classes have been deprecated in previous Vuforia versions and have now been removed with Vuforia 8.1:
  - PositionalDeviceTracker.CreateMidAirAnchor(string name, Transform transform):
    Use CreateMidAirAnchor(string name, Vector3 position, Quaternion rotation) instead.
  - DeviceTrackerARController.FusionProvider: Use VuforiaRuntimeUtilities.SetAllowedFusionProviders instead.
  - ICloudRecoEventHandler: Use IObjectRecoEventHandler instead.
  - ObjectTracker.TargetFinder: Use GetTargetFinder instead.
  - AnchorStageBehaviour: use AnchorBehaviour instead.
  - FusionProviderType. OPTIMIZE_IMAGE_TARGETS_AND_VUMARKS and OPTIMIZE_MODEL_TARGETS_AND_SMART_TERRAIN: Use ALL instead.
  - VuforiaRuntime.HasInitialized: use VuforiaRuntime.InitializationState or VuforiaManager.Initialized instead.
4. Newly deprecated APIs
  The following field has been deprecated in Vuforia 8.1 and will be removed in a future Vuforia version:
  - TargetFinder.CloudRecoSearchResult.TargetSize

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:

Open the Vuforia Configuration panel (Windows> Vuforia Configuration or Ctrl+Shift+V)
Check the "Track Device Pose" option under the "Device Tracker" section
Confirm that the Tracking Mode is set to "POSITIONAL"
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:

Platform Enablers (ARKit/ARCore)
Vuforia VIO
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

If your experience uses physics or otherwise requires a GameObject to remain static for performance reasons, consider using SPECIFIC_TARGET.

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:

MAKE A BACKUP OF YOUR EXISTING UNITY PROJECT.
Important: DO NOT SKIP THIS STEP!
Make sure your project has been upgraded to Unity 5.3 or 5.4.
Do not proceed further in the migration, if step 1 and 2 have not been successfully completed.
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
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.
From the Unity Project view, delete the following folders:
- Assets/Vuforia
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
After removing the necessary files, you may want to close and re-open your Unity project if using source control in your project
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)
Import vuforia-unity-6-2-x.unitypackage. Make sure that all components are checked and installed.
Fix any compiler errors; in particular, you may need to update a few API calls, according to the following API changes:

Old API	New equivalent API (Vuforia 6.2)
VuforiaBehaviour.Instance or FindObjectOfType<VuforiaBehaviour>	VuforiaARController.Instance
DigitalEyewearBehaviour.Instance or FindObjectOfType<DigitalEyewearBehaviour>	DigitalEyewearARController.Instance
DatabaseAbstractBehaviour	DatabaseLoadARController
DeviceTrackerAbstractBehaviour	DeviceTrackerARController
SmartTerrainAbstractBehaviour	SmartTerrainARController
VideoBackgroundManagerAbstractBehaviour	VideoBackgroundManager
WebCamAbstractBehaviour	WebCamARController
VuforiaBehaviour.Instance.SetLicenseKey()	VuforiaConfiguration.Instance.Vuforia.LicenseKey
VuforiaBehaviour.Instance. RegisterVuforiaInitErrorCallback	VuforiaRuntime.Instance. RegisterVuforiaInitErrorCallback

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();