Documentation

Setup Guide iOS Native API

There are only a few steps necessary to add the Wikitude Native SDK to your existing iOS application. This guide will explain them in detail. In general the steps are

  • Adding the Wikitude Native SDK .framework to a Xcode project
  • Using the main classes to create your augmented reality experiences

Project Setup

Load your Xcode project

The first step is to open an exiting Xcode project. If there is no project already created, do so using the Xcode project configurator.

Adding the Wikitude SDK Framework

To keep things clear, you should copy the Wikitude Native SDK .framework into your Xcode project structure. Having it somewhere else on your machine might lead to confusion when updating to a newer version of the Wikitude Native SDK.

After the .framework was copied, it can be added as 'Embedded Binaries'.

Because the Wikitude Native SDK will fully support Swift, a build setting has to be changed in order to package Swift Standard Libraries into the final application package.

The project is now fully configured to use the Wikitude Native SDK.

Using the Wikitude Native SDK in your Application

After the setup steps are completed, the Wikitude Native SDK is ready to be used within an iOS application.

The Wikitude Native SDK comes with an umbrella header that has to be included in your corresponding source files. The file is called WikitudeNativeSDK.h and can be imported by calling #import <WikitudeNativeSDK/WikitudeNativeSDK.h>

The main class to work with is WTWikitudeNativeSDK. It's the central point for creating trackers, to obtain an already configured rendering component or to control camera related settings.

The Wikitude Native SDK can be used in trial mode without any license, but to remove the watermark, a valid license has to be set using the -setLicenseKey method.

Application Lifecycle

To integrate the Wikitude Native SDK into the application lifecycle, use the -start:completion and -stop methods of WTWikitudeNativeSDK. A good place to call them is e.g. a UIViewControllers -viewWillAppear: and -viewWillDisappear:. To refine the startup phase, the WTStartupConfiguration object can be used which is the first arguments in first block parameter of -start:completion:. The second block parameter can be used to check if the Wikitude Native SDK could actually start with the given configuration on the current device. Use the isRunning parameter to determine the run state and e.g. create tracker in this block. The following listening demonstrates this:

    [self.wikitudeSDK start:nil completion:^(BOOL isRunning, NSError * __nonnull error) {
        if ( !isRunning ) {
            NSLog(@"Wikitude SDK is not running. Reason: %@", [error localizedDescription]);
        }
        else
        {
            __weak typeof(self) weakSelf = self;

            NSURL *imageTrackerResourceURL = [[NSBundle mainBundle] URLForResource:@"magazine" withExtension:@"wtc" subdirectory:@"Assets"];
            self.targetCollectionResource = [self.wikitudeSDK.trackerManager createTargetCollectionResourceFromURL:imageTrackerResourceURL completion:^(BOOL success, NSError * _Nullable error) {
                if ( !success )
                {
                    NSLog(@"Failed to load URL resource. Reason: %@", [error localizedDescription]);
                }
                else
                {
                    weakSelf.imageTracker = [weakSelf.wikitudeSDK.trackerManager createImageTrackerFromTargetCollectionResource:weakSelf.targetCollectionResource delegate:weakSelf configuration:nil];
                }
            }];
        }
    }];

Error Handling

The Wikitude Native SDK calls the WTWikitudeNativeSDK delegate method -wikitudeNativeSDK: didEncounterInternalError: as soon as an internally inconsistent state was detected and parts of the SDK might stop working as expected. This is especially helpful while developing the application and not so much for end user notifications.

Trackers, Camera and Rendering

How trackers, the camera controls and rendering can be used, will be explained in the example part of this documentation. Each feature will be explained in detail through a real usage example.