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 thewikitudesdk.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 levelbuild.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 addcom.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 setConfigurationChanges = 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
{
...
}
- Enter a valid trial license key. Read the chapter on how to obtain a free trial key.
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.
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 );
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.
architectView.load('arexperience.html?myarg=1')