Setup Guide Flutter Wikitude SDK Flutter 9.10.0 Documentation

Setup Guide Flutter

From a technical point of view the SDK adds a UI component called ArchitectWidget, similar to a web view widget. In contrast to a standard web view widget the AR widget can render augmented reality content.

Content developed for the AR View is written in JavaScript and HTML.

Note In this guide we use the terminology augmented reality experience and ARchitect World synonymously - both of them refer to augmented reality parts of your application.

Known Issues

iOS

Touch interaction with the current ArchitectWidget on screen will stop responding after launching an AlertDialog.
Touch interaction with the current ArchitectWidget on screen will stop responding after switching between the app and the Control Center multiple times.

Android

Keyboard is not opened when touching an input text inside a native Webview.

Prerequisites

Install Flutter on your machine.
Visual Studio Code or Android Studio/IntelliJ IDE with Flutter extension installed.
Android SDK installed on your development machine (Android development only)
Xcode installed on your development machine (iOS development only)
Your personal trial license key from License Page

Setup and Configuration

The setup chapter includes several guides to setup the Wikitude SDK (through the Wikitude Flutter Plugin). If you want to create an empty app including the component or add it to an existing continue reading. Alternatively you can read about the packaged Example App and how to use the Wikitude Flutter Plugin.

Creating an empty new app
Using the Wikitude Flutter Plugin

Creating an empty new app

Note The guide is based on Flutter version 2.2.0 (using Dart 2.13.0)

Follow the instructions in the official Flutter website to ensure your environment is ready for iOS and/or Android development
Open a terminal session in the directory where you wish to create the app.
In this directory, create a new Flutter project with the Flutter CLI.
```
 $ flutter create my_app
```
Change into the root directory of the app you just created.
```
 $ cd my_app
```
Copy the plugin directory from our Flutter Examples app into the current directory.
```
 $ cp -r <path_to_Wikitude_Examples_app>/plugin .
```

Open my_app/pubspec.yaml with your editor of choice and add the Wikitude plugin to your dependencies.

 dependencies:
   ...

   augmented_reality_plugin_wikitude:
     path: ./plugin/augmented_reality_plugin_wikitude/

Update the Flutter packages in your app to import the Wikitude plugin.
```
 $ flutter packages get
```

Additional steps for iOS

Set the App name and Bundle Identifier in Xcode. If you already purchased a license, please set the Bundle Identifier to the package name you provided us with.
Add the following entries to your Info.plist:
- Privacy - Camera Usage Description, required to access the camera to display AR content.
- Privacy - Location When In Use Usage Description, required if using geolocation features (optional)
- Privacy - Photo Library Usage Description, required if using the screenshot saving feature (optional)

Additional steps for Android

Set the App minSdkVersion of your build.gradle to 23 or higher and the targetSdkVersion to 30 or higher as these are the minimum versions for the Wikitude Flutter Plugin.
Add the following entries to your AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<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.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" />

<uses-feature
    android:glEsVersion="0x00020000"
    android:required="true" />
<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:name="android.hardware.sensor.gyroscope"
    android:required="false" />

Camera permission is always required to access the camera to display AR content.
The minimum OpenGLES version required is 2.0.
Location and sensors are required if using geolocation features (optional).
WRITE_EXTERNAL_STORAGE is required if using the screenshot saving feature only for Android versions lower than 29 (optional).

Add Samples manually to your App

To use your local AR experience, you must import all the files in your pubspec.yaml under assets:

flutter:

  assets:
    - samples/
    - samples/01_ImageTracking_1_ImageOnTarget/
    - samples/01_ImageTracking_1_ImageOnTarget/js/
    - samples/01_ImageTracking_1_ImageOnTarget/css/
    - samples/01_ImageTracking_1_ImageOnTarget/assets/

Using the Wikitude package

Note: Everything described here can be seen in action in the Wikitude Flutter Examples.

Setup of the ArchitectWidget

First of all, import the ArchitectWidget and the initial settings class in your dart file:

import 'package:augmented_reality_plugin_wikitude/architect_widget.dart';
import 'package:augmented_reality_plugin_wikitude/startupConfiguration.dart';

Make sure you are using a StatefulWidget as you will need to handle the lifecycle methods. You must extend the State with WidgetsBindingObserver, like this:

class ArViewState extends State<ArViewWidget> with WidgetsBindingObserver {

Add the observer to your widget in the initState() and initialize the ArchitectWidget:

@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addObserver(this);

  architectWidget = new ArchitectWidget(
    onArchitectWidgetCreated: onArchitectWidgetCreated,
    licenseKey: wikitudeTrialLicenseKey,
    startupConfiguration: startupConfiguration,
    features: [ "image_tracking", "geo" ],
  );
}

onArchitectWidgetCreated: this method is called when the widget is created.
licenseKey: this is the Wikitude key you got from: License Page
startupConfiguration: these are the initial settings for the AR experience.
features: this is a list of features required by the AR experience.

You will have to add this ArchitectWidget object in your overridden build() method, as any other Flutter widget.

Override the didChangeAppLifecycleState() method and include our pause() and resume() calls.

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  switch (state) {
    case AppLifecycleState.paused:
      if (this.architectWidget != null) {
        this.architectWidget.pause();
      }
      break;
    case AppLifecycleState.resumed:
      if (this.architectWidget != null) {
        this.architectWidget.resume();
      }
      break;

    default:
  }
}

You must also override the dispose() method in your State to remove the WidgetsBindingObserver, pause and destroy the ArchitectWidget:

@override
void dispose() {
  if (this.architectWidget != null) {
    this.architectWidget.pause();
    this.architectWidget.destroy();
  }
  WidgetsBinding.instance.removeObserver(this);
  super.dispose();
}

Add a callback method in your State class that will be called by the ArchitectWidget when it is created. Within this method you are allowed to load an AR experience and to call the resume() method for the first time:

Future<void> onArchitectWidgetCreated() async {
  this.architectWidget.load("path/to/index.html", onLoadSuccess, onLoadFailed);
  this.architectWidget.resume();
}

The load() method receives two methods as arguments that will be called back to let you know if the experience has loaded successfully or not.

If you need to call Javascript methods in your AR experience from Dart, you can do this with the callJavascript() method in ArchitectWidget:

this.architectWidget.callJavascript("YourJavascriptMethod()");

Or if you expect to receive callbacks from Javascript, you can set a method that will be called from the ArchitectWidget:

this.architectWidget.setJSONObjectReceivedCallback(onJSONObjectReceived);

Feature compatibility

The plugin contains static methods that handle hardware and software compatibility.

To check if the device is compatible with the required features for your AR experience, use this:

List<String> features = [ "image_tracking", "geo" ];
WikitudeResponse response = await WikitudePlugin.isDeviceSupporting(features);

WikitudeResponse contains a boolean success with the resulting status of the call and a string message that will contain additional information about the result, if necessary.

This next method will receive your features and request the required native permissions to the device:

List<String> features = [ "image_tracking", "geo" ];
WikitudeResponse response = await WikitudePlugin.requestARPermissions(features);

Make sure to use the same feature list in both of these methods for each AR experience.

If any of these methods returns false success, the AR experience will not be able to run. Handle these failures accordingly using the detailed information in message.

The Wikitude Flutter Plugin and the Architect Widget offer more functionality like to inject a custom location or to capture the screen and generate an image that can be shared on Twitter or Facebook. Simply skim through wikitude_plugin.dart and architect_widget.dart to see how these functions can be used.

Wikitude SDK Flutter