Documentation

Migration Notes

Migration notes for the Wikitude Unity Plugin

Migrate to 9.10.1

The minimum Unity version was increased to 2020.3.17f1 LTS.

Migrate to 9.9

  • The minimum Android SDK Version was raised to Android 6.0 (API level 23). Please update minSdkVersion to 23 in the manifest of your app or build.gradle file if you export to a gradle project.

Migrate to 9.8

The minimum Unity version was increased to 2020.3.2f1 LTS. If custom gradle files were used to ensure Anroid 11 support for Unity 2019.4, they should be removed from the project for 2020.3.

Migrate to 9.4

The minimum Unity version was increased to 2019.4.10f1 LTS. If Android 11 (API Level 30) support is required, additional settings are required for this Unity version. Please refer to the Google documentation therefore.

Migrate to 9.3

  • The minimum Android SDK Version was raised to Android 5.1 (API level 22). Please update minSdkVersion to 22 in the manifest of your app or build.gradle file if you export to a gradle project.
  • A 'BackgroundCamera' child object was added to the 'WikitudeCamera'. If there is no such child object set by choice, a background camera will be instantiated during runtime and will not be hidden like before.

Migrate from 8.9.1 to 8.10

The minimum Android SDK Version was raised to Android 5.0 (API level 21). Please update minSdkVersion to 21 in the manifest of your app or build.gradle file if you export to a gradle project.

Migrate from 8.7.0 to 8.9.0

The minimum Unity version was increased to 2018.4 LTS for better compatibility with Xcode 11. This migration mostly affects the samples, so if compatibility with older Unity versions is still something you require, please contact support and we'll guide you through the upgrade process.

Migrate from 8.3.0 to 8.4.0

The minimum Unity version was increased to 2017.4 LTS. Android binaries contain libraries for the ARM64 architecture by default. Please make sure that your version of Unity has support for ARM64 and make sure it's enabled in PlayerSettings. Android binaries no longer contain libraries for the x86 architecture. Please make sure to disable it in PlayerSettings.

Migrate from 8.2.0 to 8.3.0

The Unity plugin will start enforcing license checks when running in the Unity editor. Please make sure that the WikitudeCamera component has a proper license, the bundle identifier / package name is properly set in Player Settings and that the current platform is either iOS, Android or UWP. If that is not the case, tracker creation will fail and all existing samples will display an error message.

Migrate from 8.0.0 to 8.1.0

The InstantTracker now has the PlaneDetectionEnabled, PlaneFilter and ConvexHullEnabled properties that are used to configure Plane Detection.

The InstantTrackable now has a new PlaneDrawable property for rendering augmentations on planes and three new events related to Plane Detection: OnPlaneRecognized, OnPlaneTracked and OnPlaneLost.

All tracker types now have the TrackerEfficiencyMode property.

The CloudRecognitionService now has a new GroupId property that should correspond with your Wikitude cloud recognition account.

Migrate from 7.2.0 to 8.0.0

The minimum Unity version was increased to 5.5.6.

On both iOS and Android, the framework and libraries have been renamed. Please make sure to remove the old ones before updating to the new version. If building was done automatically, please make sure the rename is taken into account.

The deprecated Trackable Behaviour class was removed.

The Legacy Scale option on the ImageTracker and InstantTracker introduced in 7.2.0 was removed.

The PluginManager was removed and replaced with the Plugin class. The Input Plugin settings were moved from WikitudeCamera to Plugin. Please see the Plugin and Custom Camera samples and documentation for more information on how the new Plugin APIs work.

The Frame class was removed. Please use the new CameraFrame class instead.

All error callbacks had their signature changed to have a single Wikitude.Error parameter instead of two parameters. The error code and error message were moved into the Wikitude.Error object.

Migrate from 7.1.0 to 7.2.0

The minimum Unity version was increased to 5.4.2.

Initialization of WikitudeCamera and the internal SDK was moved from Awake to Start. This means WikitudeCamera properties can now be easily changed from script, as long they are done before the Start method is called on the WikitudeCamera.

ImageTracker and InstantTracker now have a new option called Legacy Scale. In previous versions of the plugin, the augmentations needed to be scaled by a factor of 10 to match their targets. In the new version, this is no longer required. However, for backwards compatibility, the Legacy Scale allows developers to re-enable the old behavior. Keep in mind that this option will be removed in future versions and is only intended to ease the transition of existing projects.

Migrate from 7.0.0 to 7.1.0

No changes.

Migrate from 2.1.0 to 7.0.0

Version 7.0.0 increases the minimum required version for Unity to 5.4.0. Please make sure to also upgrade Unity if you are using an older version, otherwise the plugin will not work properly. Version 7.0.0 also increases the minimum iOS version to 9.0 and the minimum Android version to Android 4.4(19). Please update minSdkVersion to 19 in the manifest of your App or build.gradle if you export to a gradle project.

To align the Unity API with that of the Wikitude Native SDK, the general TrackableBehaviour component has been deprecated, and was replaced with ImageTrackable, ObjectTrackable and InstantTrackable. These new trackables also have different events. So instead of the generic OnEnterFieldOfVision from the previous version, the ImageTrackable has an equivalent OnImageRecognized event, with an ImageTarget parameter, instead of just a string. Similar events are present in the other trackers. When you update to the new API, please make sure to never mix the new Trackables with the deprecated TrackableBehaviour, as this is not supported.

The new Trackable components now have an additional Drawable field. This was added to support multiple targets for ImageTrackers, but the API is available for all Trackables. Please see the Image Tracking examples for more information about multiple targets.

Additionally, some sample scripts were renamed. If you are upgrading and importing the samples as well, please check fo duplicate scripts, or for scripts that should not be present in the project anymore.

Migrate from 2.0.0 to 2.1.0

Version 2.1.0 adds a new value to the FrameColorSpace enum used for Plugins and Input Plugins. Because of this, when loading a scene that contains a WikitudeCamera component configured to use Input Plugins, the deserialized value of the enum will be incorrect. Please set it to the appropriate value for your use case after upgrading to 2.1.0.

Migrate from 1.4.0 to 2.0.0

Version 2.0.0 deprecates the ClientTracker and the CloudTracker classes. When before you used the ClientTracker to recognize images, it is recommended to switch to the new ImageTracker, in combination with a TargetCollectionResource. Instead of the CloudTracker, the same ImageTracker can be used, but with a CloudRecognitionService, instead. You can select between the TargetCollectionResource and the CloudRecognitionService in the ImageTracker inspector, in the first dropdown menu. Finally, if you used the ClientTracker to track 3D targets, you can now use the new ObjectTracker with a TargetCollectionResource for this.

To help migrate your project to the new APIs, the inspectors of the old classes have a button that allows you to automatically upgrade the script component with the appropriate replacement.

When you press the button, a warning message will appear, informing you that during the upgrade process, the properties set on the old tracker will be migrated to the new one, but events will not. This would not be possible, because in most cases you need to update the script functions receiving the events to the appropriate signature.

After pressing OK, GameObject will have the new component instead. If you are not happy with the result, or something went wrong, you can undo this operation.

Keep in mind that you still need to update the source code, where references to the old trackers are used.

For example, the Runtime Tracker sample used to create a ClientTracker with a custom remote URL.

GameObject trackerObject = new GameObject("ClientTracker");
_currentTracker = trackerObject.AddComponent<ClientTracker>();
_currentTracker.UseCustomUrl = true;
_currentTracker.TargetPath = Url.text;

_currentTracker.OnTrackerFinishedLoading.AddListener(OnTrackerFinishedLoading);
_currentTracker.OnTrackerLoadingError.AddListener(OnTrackerLoadingError);

Here is how the sample would look like when using the new ImageTracker and APIs.

GameObject trackerObject = new GameObject("ImageTracker");
_currentTracker = trackerObject.AddComponent<ImageTracker>();
_currentTracker.TargetSourceType = TargetSourceType.TargetCollectionResource;
_currentTracker.TargetCollectionResource = new TargetCollectionResource();
_currentTracker.TargetCollectionResource.UseCustomURL = true;
_currentTracker.TargetCollectionResource.TargetPath = Url.text;

_currentTracker.TargetCollectionResource.OnFinishLoading.AddListener(OnFinishLoading);
_currentTracker.TargetCollectionResource.OnErrorLoading.AddListener(OnErrorLoading);

_currentTracker.OnTargetsLoaded.AddListener(OnTargetsLoaded);
_currentTracker.OnErrorLoadingTargets.AddListener(OnErrorLoadingTargets);

The old trackers are still kept for backwards compatibility, but will be removed in a future version, so please update to the new ones.

Additionally, the CloudTrackable was removed from the samples. If you are upgrading from an older version, please make sure that this script is no longer in your projects, otherwise you might encounter compilation errors.

Migrate from 1.1.0 to 1.2.0

Version 1.2.0 simplifies the WikitudeCamera prefab. It is now a single GameObject, without the hierarchy it previously had. If you had any changes to the prefab, except for the license key, please make sure to back it up first.

Because the previous hierarchy is gone, the camera feed is no longer explicitly exposed in the editor, but you can still access it through the CameraTexture property on the WikitudeCamera script.

Migrate from 1.0.1 to 1.1.0

Version 1.1.0 contains many breaking changes to the plugin, so before upgrading, please backup your project, to prevent accidentally losing your work.

Wikitude classes are now concrete and sealed and expose Unity events to communicate. This means that now you can add them directly to game objects and subscribe to their events through the editor or at runtime in code. When adding subscribers to events, make sure you use the dynamic version of your method, when there is a choice between static and dynamic (please see the Client Recognition examples for more information on how to set up Client Trackers).

Values that were set in the inspector for these classes will need to be reset because of the change in class name and their internal representation.

The classes that previously derived from them will no longer work, so they need to be updated to receive events. On your game objects, you will get missing mono classes after updating. These should be replaced with the corresponding classes in the Wikitude plugin (Wikitude/Dependencies/WikitudeUnityPlugin) and the values need to be reintroduced.

All function names in Wikitude classes now begin with a capital letter.

When building for iOS, if you choose to append over a build made with a previous version, you will end up with two versions of the Wikitude plugin in your project, one located in Plugins/iOS and the new one in Plugins/Wikitude/iOS. Please make sure that only the new one is used. Alternatively, you can redo the build from scratch using the steps from the Setup Guide section.

Migration Example

This section will show how to migrate the example project from version 1.0.1 to work with the new version of the plugin.

  1. (Optional) Delete the Dependencies, Editor and Plugins folders. The plugin folder has changed drastically in this version. If you don't delete these folders, the correct files should still be replaced with the new version. However, the samples will not work correctly because magazine.wtc will be in StreamingAssets folder instead of StreamingAssets/Wikitude. Since we won't be using the samples in this example, this step can be skipped.
  2. Delete the Wikitude/Samples folder. The Samples folder is for illustration purposes only and is not needed in development.
  3. Update ClientTracker script. Wikitude.IClientTracker has been renamed to Wikitude.ClientTracker and is a sealed class. As such, the ClientTracker script should be changed to derive from MonoBehaviour instead and it's methods should be simple, instead of override. These methods will be set as callbacks in the Inspector. The class name should also be changed to avoid clashes with the Wikitude class.
  4. Similar steps should be taken to update the CloudTracker script. Additionally, since it no longer derives from Wikitude.CloudTracker, it will need a reference to it so that it can call StartContinuousRecognition.
  5. Similar steps should be taken to update the SurferBehaviour script.
  6. Delete MagazineTracker, TrackableBehaviour and WikitudeCamera scripts. Since Wikitude classes are concrete now, they can be assigned directly to GameObjects, so there is no need for these empty classes anymore.
  7. Open the scene called main from the Scenes folder.
  8. Select the WikitudeCamera GameObject from the Hierarchy and enter your license key in the appropriate field in the Inspector. If the script is missing, add the WikitudeCamera script from the Dependencies/WikitudeUnityPlugin dll.
  9. Create a new GameObject and add the script you updated at step 3 to it.
  10. Select the ClientTracker GameObject from the Hierarchy and from the Target Collection dropdown select magazine.wtc. Then, for each event you want to subscribe to, press the plus sign, set the GameObject created at step 9 to the field None (Object) and select the corresponding function callback. Please see Client Recognition examples for more information on how to work with Unity Events.
  11. Select the WikitudeEye GameObject from the Hierarchy and add the script you updated at step 5 to it.
  12. Select the Trackable GameObject from the Hierarchy and in the Target Pattern field enter * to track all targets. In the events foldout, subscribe the script you added to WikitudeEye to both On Enter Field Of Vision and On Exit Field Of Vision events.

The project should now work as before.