Migration

Migrate from 4.1 to 4.1.1

The Wikitude SDK 4.1.1 adds new properties and methods to it's public API.

• WTArchitectView

  • new -reloadArchitectWorld Calling this method will reload the Architect World that was previously loaded using the -loadArchitectWorldFromURL:withRequiredFeatures: method. It does not matter if the Architect World finished loading previously or failed. In all cases a new reload is triggered.

• WTNavigation

  • new property isLoading indicates if the original URL is currently loading or not.
  • new property wasInterrupted indicates if the WTArchitectView's -stop method was called while an Architect World was still loading.

Migrate from 4.0.2 to 4.1

There are several API changes in the Wikitude SDK 4.1 that improve the usage. Please note that the next major release will remove all deprecated APIs.

This version requires the iOS SDK framework SystemConfiguration.framework to determine the network connectivity for cloud recognition.

• WTArchitectView

  • new +isDeviceSupportedForRequiredFeatures:error: Use this method to determine if the current device is supported with the given bit mask of required features. In case the method returns NO, a NSError object is available which describes the missing device features in more detail.

  • deprecated +isDeviceSupportedForAugmentedRealityMode:

  • new +sdkVersion

  • deprecated +versionNumber

  • new -loadArchitectWorldFromURL:withRequiredFeatures: This method replaces -loadArchitectWorldFromURL:withAugmentedRealityMode: and uses the new WTFeatures based API to load an ARchitect World from a URL with the specified required features.

  • deprecated -loadArchitectWorldFromURL:withAugmentedRealityMode:

  • new -start:completion: The new SDK start mechanism allows to specifically alter the SDK startup behaviour. Right now it can be used to define which camera should be used at startup and which auto focus mode should be used. The first block provides a pre configured WTStartupConfiguration object which can be used to define a value different than the default one for any of the currently present member variables. The second block replaces the previous available isRunning property and provides more information if the SDK could be started successfully.

  • deprecated -start

• new WTFeatures: Features allows a more use case tailored usage of the Wikitude SDK. They're also more future proof when new functionality is added to the SDK. WTFeatures is implemented using a bit mask. To combine features, use the |= operator.

• deprecated WTAugmentedRealityMode. Please adopt to the new WTFeatures based API.

• WTStartupConfiguration
  This new class is used from -start:completion: in order to define the startup procedure. Right now it allows setting the active camera position and the camera focus mode range restriction. Please read through the Apple iOS SDK documentation for more information about these two properties.

• WTArchitectViewDebugDelegate This new protocol provides hooks to react on internal SDK warnings and errors. It is useful to implement these methods during development but please consider removing them for any final App Store build.

Besides the API changes version 4.1 of the Wikitude SDK also offers a new file format for client based 2d tracking. The new .wtc file is not compatible with older versions of the Wikitude SDK but version 4.1 can read older file formats. Please consider migrate your existing .wtc anyway because it delivers more accurate and faster target recognitions. See more details here

This version of the SDK also comes with a Quick Look Plugin for Mac OS X that allows introspection of any .wtc file. It displays all target images in a .wtc file and also shows the version number and the compatible SDK's. The Quick Look Plugin is bundled with the Wikitude 3D Encoder application that is part of the SDK download package.

Migrate from 4.0 to 4.0.2

The Wikitude SDK for iOS 4.0.2 introduces several API improvements when it comes to loading augmented reality experiences and error reporting.

• WTArchitectView

  • new -loadArchitectWorldFromURL:withAugmentedRealityMode:

    Use this method to load an augmented reality experience with a certain WTAugmentedRealityMode. Previously the augmented reality mode could only specified during the WTArchitectView initialization. Since it was not possible to specify an augmented reality mode when the view was created by a storyboard the Wikitude SDK API now allows to specify the augmented reality mode when the augmented reality experience is loaded. This also allows to load different augmented reality experiences with different augmented reality modes by the same architect view object.

    This method now also returns an object of type WTNavigation. A WTNavigation object represents the Architect World URL during it's loading state. It might be the case that the URL that was passed to the -loadArchitectWorldFromURL:withAugmentedRealityMode: is causing some redirects during it's loading. The returned navigation object can now be used to determine which augmented reality experience finished loading when the -architectView:didFinishLoadArchitectWorldNavigation: delegate method is called. A -isEqual: call on the navigation objects will return YES if the original URL is the same but the finally resolved URL differs. A simple scenario would be a short URL. Passing a short URL to the -loadArchitectWorldFromURL:withAugmentedRealityMode: method will return the finally resolved URL to the previously preferred -architectView:didFinishLoad: delegate method. The problem was that the initial load URL is no longer the same URL that finished loading. The new -architectView:didFinishLoadArchitectWorldNavigation: method now provides the navigation object that was returned by the -loadArchitectWorldFromURL:withAugmentedRealityMode: method. A simple -isEqual: call now provides the information if the original URL is the same as the final URL and if the load request finished successfully.

  • deprecated -loadArchitectWorldFromUrl:

    Use -loadArchitectWorldFromURL:withAugmentedRealityMode: instead and refer to the documentation on how to use the WTAugmentedRealityMode.

• WTArchitectViewDelegate
  • new -architectView:didFinishLoadArchitectWorldNavigation:
  • new -architectView:didFailLoadArchitectWorldNavigation:withError:
  • deprecated -architectView:didFinishLoad:
  • deprecated -architectView:didFailLoadWithError:

• WTAugmentedRealityMode
  • deprecated WTAugmentedRealityMode_IR. Use WTAugmentedRealityMode_ImageRecognition instead.
  • deprecated WTAugmentedRealityMode_Both. Use WTAugmentedRealityMode_GeoAndImageRecognition instead.

iOS 8 changed the GPS location access management. All applications that want to use the user location now need to enter either the NSLocationWhenInUseUsageDescription or NSLocationAlwaysUsageDescription key. The Wikitude SDK only uses the users location when the application is active, so the NSLocationWhenInUseUsageDescription key must be set in the applications Info.plist. Note that this key is only required if the specified augmented reality mode is WTAugmentedRealityMode_GeoAndImageRecognition or WTAugmentedRealityMode_Geo. The mode WTAugmentedRealityMode_ImageRecognition does not start any GPS related APIs. The following snippet shows the source code representation for the required key/value pair. Please refer to the iOS example application on how the changes look in a real application.

    <key>NSLocationWhenInUseUsageDescription</key>    
    <string>Accessing GPS information is needed to display POIs around your current location</string>

Please note that there will be some more API changes in upcoming releases and methods that were deprecated in a Wikitude SDK 3.x version will be removed in the next release.

Migrate from 3.3 to 4.0

• SDK 4.0 requires the iOS Accelerate.framework. Please refer to the iOS Setup Guide on how to add additional frameworks to your project.
• Starting with Wikitude SDK 4.0 a valid license key is mandatory for starting the SDK. An empty license key will block the SDK. A free trial key can be generated on the license page (free account required).
• The Wikitude SDK 4.0 introduces a new file format for target collections (wtc). In order to unleash the full power of the new Wikitude SDK 4.0 read this section and re-generate your targets.

Migrate from 3.2 to 3.3

WTArchitectView

• WTARMode is now WTAugmentedRealityMode and is used in +isDeviceSupportedForAugmentedRealityMode: and -initWithFrame:motionManager:augmentedRealityMode.

• -initializeWithKey:motionManager: is now deprecated. Use the new designated initializer -initWithFrame:motionManager:augmentedRealityMode to pass a CMMotionManager instance into the SDK and -setLicenseKey: to set the license key.

• The former instance method -versionNumber is now a class method +versionNumber. The instance method still exists but is deprecated.

WTArchitectViewDelegate

Added a new delegate method -architectView:didFinishLoad: which is called when the ARchitect World finished loading.

Migrate from 3.1 to 3.2

SDK 3.2 adds methods to the delegate protocol and updates existing methods to match a more common CocoaTouch style. Have a look at the WTArchitectView.h file for more information.

If you have been previously using -urlWasInvoked: you now need to use -architectView:invokedURL:.

Migrate from 3.0 to 3.1

The image recognition engine of Wikitude SDK 3.1 has been updated resulting in shorter time interval to successfully recognize a target image. As a consequence the format of the digital footprint of target image changed. The format is backward compatible. Developers still can use target collections (.wtc) generated with Wikitude SDK 3.0 (prior to 27th August 2013) together with the SDK 3.1 and vice versa.

However we recommend to generated your target collections again in the Target Manager Tool and update the files when you are using Wikitude SDK 3.1

HTML Drawables

Developers using HTML Drawables in projects prior to Wikitude SDK 3.1 and like to upgrade to 3.1 need to define the viewportHeight similar to the already defined viewportWidth. In addition HTML Drawables do not have to be created as static or dynamic anymore. All are created as dynamic ones.

Migrate from 2.0 to 3.0

Wikitude SDK version 3.0 introduces Wikitude's own image recognition and tracking solution and removes support for the Vuforia Plugin.

• -[WTArchitectView loadArchitectWorldFromUrl:] The URL parameter is now an NSURL object rather then a NSString. It is now more consistent and developer are able to load local ARchitect Worlds from bundles that contain white spaces in there name.

• In case you are making use of image recognition features and want to switch from 2.0 to 3.0+ version remove any Qualcomm/Vuforia related assets (Static Library and Header files) from your project. Find a step-by-step guide about how to convert your existing target collection from Vuforia to Wikitude here.

• New property isRunning in WTArchitectView. Developer can use this property to determinate the current state of the WTArchitectView instance.

• +[WTArchitectView isDeviceSupportedForARMode:] The iPhone 3GS is no longer supported for WTARMode_IR.

Migrate from 1.2 to 2.0

The Wikitude SDK 2.0 for iOS is a major update and requires some migration work to be done. The iOS SDK now ships as a .framework instead of a static library. This change requires some project setup changes. Furthermore the iOS SDK 2.0 allows the developer to select which Augmented Reality mode is used in within the ARchitect World. This way, developer can also run Image Recognition World on devices who are not able to run Geo Worlds (iPodTouch 4th and 5th generation).

Framework

1. Remove the libWikitudeSDK.a (either by deleting the linker flag and library search path or removing all references from your project hierarchy.) and the WTArchitectView.h header file (either by deleting the header search path or by removing the reference from you project hierarchy) from your project.
2. Add the WikitudeSDK.framework to your project (You can do this by either drag the framework into your projects Framework folder or by adding it to your link binary with libraries build phase make sure to copy the framework in either cases to your project first).
3. Replace the import directive #import "WTArchitectView.h" with #import <WikitudeSDK/WTArchitectView.h>
4. Replace the linker flag -lstdc++ with -lc++ or add libc++ instead of libstdc++ in your Link Binary With Libraries build phase in Xcode.

You should now be ready to compile, link and run you application again, using the Wikitude iOS SDK 2.0. (Don't forget to check for the -ObjC linker flag and all the required iOS public Frameworks listed in the Wikitude SDK documentation).

Upgrading targets for SDK 4.1

The Wikitude SDK 4.1 introduces an updated format for the target collection. The new format improves the recognition phase considerably. The updated format is not backward compatible with Wikitude SDK 3.x, 4.0 and can not be used in projects using Wikitude SDK 3.x or Wikitude SDK 4.0.

However you can use wtc-3.x and wtc-4.0 formats with the Wikitude SDK 4.1, although we strongly recommend to updated to the newest (wtc-4.1) version.

To use the new format you need to re-create your target collection in the target manager and download the .wtc file under the Download 4.1 link. Put this .wtc file in your app and replace the previous one.

Migrating targets from SDK 1.x

If you have been using a dataset from the Qualcomm Vuforia target management, please follow these steps to convert your ARchitect World to the new approach:

1. Create a new project with the Wikitude target management tool and upload your targets (see instructions above)
2. Create a target collection and store it in the same location as the previously used dataset
3. In your ARchitect World, update the AR.ClientTracker initialization to point to the URL of your new target collection