Documentation

Migration

Migrate from 8.3.2 to 8.4

  • WTArchitectView
    • deprecated:
      • isDeviceSupportedForRequiredFeatures:error:
    • added
      • isDeviceSupportingFeatures:error: is now the preferred way to check if the current device supports the iOS capabilities required for an AR experience

Migrate from 8.1 to 8.2

  • JS API:
    • AR.ImageTrackable
      • onDragBegan, onDragChanged, onDragEnded now receive ray-plane-intersection coordinates as two additional input float parameters - these parameters allow the drag gesture to be rotationally invariant and provide absolute positions for it
      • AR.ObjectTrackable
        • onDragBegan, onDragChanged, onDragEnded now receive ray-plane-intersection coordinates as two additional input float parameters - these parameters allow the drag gesture to be rotationally invariant and provide absolute positions for it

Migrate from 7.1 to 7.2

  • JS API:
    • AR.InstantTracker
      • new method canStartTracking
      • new constructor parameter smartEnabled
      • when running with platform assisted tracking, some functionality is not available; these functions will raise an error through the error callback when called regardless
        • trackingplaneOrientation
    • AR.hardware.camera
      • new property AR.hardware.smart.deviceSupported
        • should be used to guard methods that are not available when running with platform assisted tracking
      • when running with platform assisted tracking, some functionality is not available; these functions will raise an error through the error callback when called regardless
        • enabled
        • features
        • flashLight
        • flashlightAvailable
        • focusDistance
        • focusMode
        • manualFocusAvailable
        • position
        • zoom

Migrate from 7.0 to 7.1

  • no changes required

Migrate from 6.1 to 7.0

  • iOS 9.0 or higher is now required
  • Plugins API:
    • Plugin.h
      • deprecated:
        • void update(const std::list<RecognizedTarget>& recognizedTargets_). Use void update(const RecognizedTargetsBucket& recognizedTargetsBucket_) instead. * RecognizedTarget.h
      • deprecated class RecognizedTarget. Use ImageTarget instead.

Migrate from 6.0 to 6.1

Migrate from 5.3 to 6.0

  • JS API:
    • The JS API is fully backwards compatible with SDK 5
    • Positioning:
      • AR.Drawable these changes affect all Drawables (e.g. AR.ImageDrawable, AR.Model):
        • removed:
          • roll use rotate.z or rotate.global.z instead
          • tilt use rotate.x or rotate.global.x instead
          • heading use rotate.y or rotate.global.y instead
        • deprecated:
          • rotate.tilt use rotate.x or rotate.global.x instead
          • rotate.heading use rotate.y or rotate.global.y instead
          • rotate.roll use rotate.z or rotate.global.z instead
      • AR.Drawable2D:
        • removed:
          • scaling use scale.x and scale.y instead
        • deprecated:
          • offsetX use translate.x or translate.global.x instead
          • offsetY use translate.y or translate.global.y instead
    • Trackers:
      • removed:
        • AR.Tracker
        • AR.Trackable2DObject:
          • getDistance`
          • height
          • width
      • deprecated:
        • AR.ClientTracker use AR.TargetCollectionResource with an AR.ImageTracker instead
        • AR.CloudTracker use AR.CloudRecognitionService with an AR.ImageTracker instead
        • AR.Trackable2DObject use AR.ImageTrackable instead
        • AR.Trackable2DObject:
          • onEnterFieldOfVision use onImageRecognized instead
          • onExitFieldOfVision use onImageLost instead
    • AR.ActionRange:
      • removed:
        • geoLocation
        • positionX
        • positionY
        • width

Migrate from 5.2 to 5.3

iOS 10 now requires a camera usage description. Please make sure that you add the NSCameraUsageDescription key to your applications .plist. In case you use the screenshot feature of our SDK and would like to save screenshots to the iOS photo library, the NSPhotoLibraryUsageDescription key has to be present as well.

In case Architect Worlds are loaded from a https URL, please make sure that the architect.js is included like this <script src="https://www.wikitude.com/libs/architect.js"></script>. The old include statement (<script src="architect://architect.js"></script>) is still valid but fails to load in https environments.

Migrate from 5.0 to 5.2

Migrate from 4.1 to 5.0

  • Projects now require iOS7 or newer

Migrate from 4.1 to 4.1.1

The Wikitude SDK 4.1.1 adds new properties and methods to its public API.

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.

  • 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 its loading state. It might be the case that the URL that was passed to the -loadArchitectWorldFromURL:withAugmentedRealityMode: is causing some redirects during its 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.

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 6.0 (and later)

The Wikitude SDK 6.0 introduces an updated format for the target collection. The new format improves the recognition phase significantly. The updated format is not backward compatible with Wikitude 5.x (and prior) and can not be used in projects using Wikitude SDK 5.x or prior.

However you can use wtc-4.1 formats with the Wikitude SDK 6.0, although we strongly recommend to updated to the newest (wtc-5.0) 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 6.0 link. Put this .wtc file in your app and replace the previous one.

It is not possible to use a wtc 5.0 file together with Wikitude SDK 5.x. Please download the respective wtc versions from the target manager and use them.
Wikitude SDK 3.x Wikitude SDK 4.0 Wikitude SDK 4.1 Wikitude SDK 5.0 Wikitude SDK 5.1-5.3 Wikitude SDK 6.0
wtc 3.x supported supported supported not supported not supported not supported
wtc 4.0 not supported supported supported not supported not supported not supported
wtc 4.1 not supported not supported supported supported supported supported
wtc 5.0 not supported not supported not supported not supported not supported supported

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.

Support for wtc-3.x and wtc-4.0 is deprecated and will be not supported in Wikitude SDK 5.0 (later 2015).

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.

It is not possible to use a wtc 4.1 file together with Wikitude SDK 3.x or Wikitude SDK 4.0. Please download the respective wtc versions from the target manager and use them.

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