How To Migrate an iOS Project

Use this article to understand the steps necessary to upgrade a project that uses the Vuforia Android SDK. To upgrade a Unity-based Android project, See: How to migrate a Unity project

If you are migrating from Vuforia Engine 4 or 5 to 6 or later, be sure to review the Changes in Vuforia Engine 5 and Changes in Vuforia Engine 6 articles. Migrating a Vuforia Engine 4 or 5 project to Vuforia Engine 6 does not require code or project structure changes, though you may want to extend your project to take advantage of new APIs introduced with Vuforia Engine 6. You'll simply need to update the libraries of your Vuforia Engine installation, See: Installing Vuforia Engine for iOS.

Note: Ensure you make a copy of your project before upgrading.

If you are migrating a Vuforia Engine 3 project to 4 or 5, follow the steps outlined below. These will enable you to make the changes necessary to adapt a Vuforia Engine 3 project to the newest Vuforia APIs.

Note: This article only pertains to native iOS SDK project. For iOS Unity projects, See:
How To Migrate a Unity Project to Vuforia 4
Migrating Unity Projects to Vuforia 5

Migrating from Vuforia Engine 3 to 5

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

1. All occurrences in code of the <ImageTracker> class must be replaced with the <ObjectTracker> class.

2. The QCAR.setInitParameters() method in 5 takes an additional string parameter for the app's license key, see below.


Adding a license key

Vuforia Engine 5 apps require a license key to unlock the features of the Vuforia Engine 5 platform. You'll need to create a license key in the License Manager and add it to your project, See: How To add a License Key to your Vuforia App

Vuforia License Manager
How To Create an App License

If a project was built in the same directory as the Vuforia Engine 3.0 samples, do the following:

  1. Install the Vuforia Engine 5.
  2. Copy the project into the Vuforia Engine 5 samples directory.
  3. Compile and run the project.
  4. If the project was organized with its own directory structure, ensure that the application references the new files in the build directory.
  5. Replace the previous files by copying over all the include and library files.

API changes

You can now perform certain operations that previously relied on the TYPE enum by using the Type class and its related API:

  • Remove the TYPE enum from the Tracker, Trackable, and TrackableResult classes
  • Introduce the new Type class

Code Changes

To initialize a Tracker, use the following C++ code:

  QCAR::ObjectTracker* objectTracker = static_cast<QCAR::ObjectTracker*> 
    (trackerManager.initTracker( QCAR::ObjectTracker::getClassType() ));

To obtain a Tracker from the TrackerManager, use the following C++code:

  QCAR::ObjectTracker* objectTracker = static_cast<QCAR::ObjectTracker*> 
    (trackerManager.getTracker( QCAR::ObjectTracker::getClassType() ));

To compare TrackableResults types, use the following C++ code:

const QCAR::TrackableResult* result = state.getTrackableResult(tIdx);
if (result->isOfType(QCAR::ImageTargetResult::getClassType()))
    // Do something target-specific

To compare Trackable types, use the following C++ code:

const QCAR::Trackable& trackable = result.getTrackable(); 
if (trackable.isOfType(QCAR::ImageTarget::getClassType())) 
  // Do something target-specific 


Unity iOS Build Setting Changes

Unity 4.6.3 introduced support for the Metal rendering framework for iOS and has defined Metal as the default graphics API for iOS builds. Because Vuforia Engine does not use the Metal framework, it will be necessary to set your iOS graphics build option in Build Settings to Force OpenGL ES 2.0.