Documentation

Setup Guide Android

Project Setup Android Studio

You can start either off with a blank project. The necessary steps are provided below. Alternatively you can use the SampleProject that is already bundled with the SDK, where the necessary configuration steps have already been made.

  • Create a new Android Application Project

  • Copy the file Library/wikitudesdk.aar into the libs folder of your module. (<project-root>/<module-name>/libs)

  • Open build.gradle from your module, make sure the minSdkVersion is 23 or higher, add the wikitudesdk.aar as a dependency and tell gradle to search the libs folder, like in the code below.

android {
    ...
    defaultConfig {
        minSdkVersion 23
        ...
    }
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation (name: 'wikitudesdk', ext:'aar')
    implementation 'com.android.support:appcompat-v7:27.1.0'
    implementation 'com.google.ar:core:1.29.0'
}

repositories {
    flatDir{
        dirs 'libs'
    }
}

Optionally you can include the Wikitude SDK using our custom maven repository instead.

  • Add https://cdn.wikitude.com/sdk/maven as maven source to your project. This is usually done in the top level build.gradle.
buildscript {
    repositories {
        mavenCentral()
        google()
        maven {
            url 'https://cdn.wikitude.com/sdk/maven'
        }
    }
    ...
}

allprojects {
    repositories {
        mavenCentral()
        google()
        maven {
            url 'https://cdn.wikitude.com/sdk/maven'
        }
    }
}
  • Open build.gradle from your module and add com.wikitude:js:9.13.0 as a dependency like in the code below.
android {
    ...
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'com.wikitude:js:9.13.0'

    implementation 'com.android.support:appcompat-v7:27.1.0'
    implementation 'com.google.ar:core:1.29.0'
}
  • If you already purchased a license, please set the applicationId to the package name you provided us with.
    defaultConfig {
        applicationId "xxxx"
    }
  • Add the following permissions to your AndroidManifest.xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_GPS" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" />
<uses-feature android:name="android.hardware.camera" android:required="true" />
<uses-feature android:name="android.hardware.location" android:required="true" />
<uses-feature android:name="android.hardware.sensor.accelerometer" android:required="true" />
<uses-feature android:name="android.hardware.sensor.compass" android:required="true" />
<uses-feature android:glEsVersion="0x00020000" android:required="true" />
  • The Activity holding the AR-View (called architectView in the following) must have set ConfigurationChanges = Android.Content.PM.ConfigChanges.Orientation | Android.Content.PM.ConfigChanges.KeyboardHidden | Android.Content.PM.ConfigChanges.ScreenSize e.g. from the Wikitude Xamarin examples:
[Activity(Label = "SimpleArActivity", ConfigurationChanges = Android.Content.PM.ConfigChanges.Orientation | Android.Content.PM.ConfigChanges.KeyboardHidden | Android.Content.PM.ConfigChanges.ScreenSize)]
public class SimpleArActivity : Activity
{
    ...
}

AR View in Activity

Keep in mind that the Wikitude SDK is not a native Android SDK as you know from other SDK's. The basic concept is to add an architectView to your project and notify it about lifecycle events. The architectView creates a camera surface and handles sensor events. The experience itself, sometime referred to as ARchitect World, is implemented in JavaScript and packaged in your application's asset-folder (as in this project) or on your own server. The experiences are written in HTML and JavaScript and call methods in Wikitude's AR-namespace (e.g. AR.GeoObject).

You have to include

 <script src="https://wikitude.com/libs/architect.js"></script>

in your HTML files to use the AR namespace and the architectView will handle them properly. To test an ARchitect World on a desktop browser, you must include ade.js tool instead to avoid JavaScript errors and see a development console.

It is recommended to handle your augmented reality experience in a separate Activity. Declare the architectView inside a layout XML. E.g. Add this within FrameLayout's parent tags.

<com.wikitude.architect.ArchitectView android:id="@+id/architectView"
   android:layout_width="fill_parent" android:layout_height="fill_parent"/>

ArchitectView is creating a camera surface so ensure to properly release the camera in case you're using it somewhere else in your application. Besides a camera (front or back-facing) the ArchitectView also makes use of compass and accelerometer values, for a full list of requirements refer to the list of supported devices.

ArchitectView.isDeviceSupported(Context context) checks whether the current device has all required hard- and software in place or not.

Note: Make AR-View only accessible to supported devices

It is very important to notify the ArchitectView about life-cycle events of the Activity. Call architectView's onCreate(), onPostCreate(), onPause(), onResume(), onDestroy() inside your Activity's lifecycle methods. Best practice is to define a member variable for the architectView in your Activity. Set it right after setContentView in Activity's onCreate(), and then access architectView via member-variable later on.

this.architectView = (ArchitectView)this.findViewById( R.id.architectView );
final ArchitectStartupConfiguration config = new ArchitectStartupConfiguration();
config.setLicenseKey( * license key */ );
this.architectView.onCreate( config );
Note: Since Android 6.0+ you need to make sure your app has the camera runtime permission before calling architectView.onCreate( config ).

Activity's onPostCreate() is the best place to load the AR experience.

this.architectView.onPostCreate();
this.architectView.load( "YOUR-AR-URL" );

The architectView.load() argument is the path to the html file that defines your AR experience. It can be relative to the asset folder root or a web-url (starting with http:// or https://). e.g. architectView.load('arexperience.html') opens the html in your project's assets-folder, whereat architectView.load('http://your-server.com/arexperience.html') loads the file from a server.

Note: You can only pass arguments to the HTML file when loading it via URL. The following will not work: architectView.load('arexperience.html?myarg=1')