# Setup Guide

This guide will explain in detail how to get started with the Wikitude Unity SDK.

# Prerequsities

Please note that the Wikitude Unity SDK currently supports following Unity version, render APIs and OS versions:

Requirements
Unity Editor Unity 2020.3.2f1 LTS or higher
Compatible devices iOS Version 12.0 or higher
Android Version 5.1 or higher
Rendering Engines
  • OpenGL ES 2
  • OpenGL ES 3.x
  • Metal (iOS only)

# Import the plugin

The latest version can be downloaded as an archive from the Wikitude website (opens new window).

The archive includes a pre-configured project with samples and an Unity package (which also includes the samples). If the plugin is intended to be imported into an existing project jump to the section import Wikitude.unitypackage. Otherwise, continue with the next section (and skip importing the Unity package afterwards).

# Open the Sample Project

The sample project included in the archive can be opened by adding it in the Unity Hub as another project. The location of the project is inside the downloaded archive's Examples folder. The Unity version for the project should be set to a supported version.

Two steps remain to be done after opening the project in order to be able to test the samples in the Editor or to export an application:

  • A license key has to be set
  • The build target has to be either iOS or Android. This setting can be found in the File dropdown menu by choosing Build Settings.

After these steps the samples can be tested by either building a mobile app or by hitting the play button in a sample scene. There are multiple live preview modes available for testing in the Unity Editor.

# Import the Wikitude.unitypackage

The included .unitypackage file is not to be confused with a package in the package manager. Therefore, it can't be added through the package manager but with the usual Unity package import procedure described below.

In your Unity project, open the Assets dropdown menu and choose Import Package > Custom Package.

Import Package Menu

Select the .unitypackagefile in the presented browser and click open. If the samples are not needed, the Samples and StreamingAssets folder can be deselected from the list. They can always be re-imported later through the Package Manager.

Import Unity package

Three steps remain to be done after importing the assets into the project in order to be able to test the samples in the Editor or to export an application:

  • A license key has to be set
  • The build target has to be either iOS or Android. This setting can found in the File dropdown menu by choosing Build Settings.
  • Additionally, the following Player settings have to be set (by opening the Projects settings in the Edit dropdown menu and under Player > iOS/Android > Other Settings).
    • The bundle identifier for iOS and Android has to be changed to com.wikitude.sampleapp.unityexpertedition.
    • The toggle Allow 'unsafe' code should be enabled (required for the Wikitude SDK Extension - AR Foundation package).
    • For Android, the minimum API level should be set to 5.1 or higher and the Scripting Backend should be set to IL2CPP with ARM64 enabled in the Target Architectures.
    • For iOS, the minimum targeted iOS version should be set to 12.0 or higher and a Camera Usage Description as well as a Location Usage Description should be provided. Additionally, the Architecture should be set to ARM64.

Location Usage Description requirement

The location usage description is required because location services are used for Geo AR purposes in the iOS plugin. Wikitude uses a common codebase throughout the products and even though this functionality is not exposed for Unity developers at the moment, Xcode still detects the presence of Geo AR, triggering a warning if the description is missing.

Building for Android 11

If Android 11 (API Level 30) support is required, additional settings might be required depending on the used Unity version. Please refer to the Google documentation (opens new window) therefore.

Required Unity Player settings

# Re-import sample assets from the Package Manager

The sample assets can always be re-imported via the package manager. This might be useful to get insights how certain concepts have been solved before and to use or tailor sample assets or scripts. There are two packages provided in the downloaded archive. The Wikitude SDK Core package provides the needed runtimes (both for an export and the Editor), whereas the Wikitude SDK Extension - AR Foundation package provides additional assets to run the Wikitude SDK in an AR Foundation environment.

Package Manager Import

# Exporting for iOS and Android

The sample project already has every necessary setting for exporting to iOS or Android applied in the Player Settings. For a manual setup, the settings described in the import Wikitude.unitypackage section should be applied before an export can be issued.

Additionally, the support modules for the targeted platform should be installed for the used Unity version. This can also be done after the Unity installation by pressing the menu button on the Unity version (in the Installs panel) and choosing Add Modules.

Unity platform support modules

# Export a Xcode project for iOS

  1. Open the Build Settings (which can be found in the File dropdown menu).
  2. Make sure iOS is the current build target. If not, select iOS from the list and click Switch Platform.
  3. Click Build and Run and choose where to save the Xcode project. In order to run the application on a device, please refer to the Apple documentation (opens new window).

# Export an .apk file for Android

If you don't need an Android Studio project, building directly from Unity is the fastest way to run your app on an Android device.

  1. Open the Build Settings (which can be found in the File dropdown menu).
  2. Make sure Android is the current build target. If not, select Android from the list and click Switch Platform.
  3. Click Build And Run and choose where to save the .apk file. If you have an Android device connected, it will also install the app on it.

# Export an Android Studio project

  1. Open the Build Settings (which can be found in the File dropdown menu), enable the Export Project option and click Export. Build Settings Menu

  2. Ensure the project folder contains no space, otherwise you will have trouble deploying the project.

  3. Open Android Studio and click Open an existing Android Studio project

    Android Studio

  4. Within the file selection dialog, navigate to the folder where you exported the project and select the folder named after your app.

  5. Android Studio may ask you to upgrade gradle, accept.

  6. Android Studio may complain about minSdk version and targetSdk version being set. Remove the line from the AndroidManifest.xml ( <uses-sdk android:minSdkVersion="23" android:targetSdkVersion="30" />), and re-run gradle.

  7. The project is now running in Android Studio