Setup Guide Cordova CLI

Introduction to the Augmented Reality View

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

Content developed for the AR View is written in JavaScript and HTML. The .html and .js files for the AR view are different from the Cordova .js and .html files.

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.

Prerequisites

Setup and Configuration

The setup chapter includes several guides to setup the Wikitude SDK (through the Wikitude Cordova Plugin). If you want to create an empty app with the plugin, checkout the chapter directly below. Alternatively there is a guide to add the plugin to an existing app and a guide to setup the Sample App.

Version and Compatibility

Cordova PhoneGap-iOS PhoneGap-Android Wikitude Cordova Plugin
4.3.0 3.8.0 3.7.1 4.1.0-3.0.x
5.0.0 3.8.0 4.0.0 4.1.0-3.1.x and newer

Creating an empty new app

Note The guide is based on Cordova version 5.0.0 (using PhoneGap-iOS 3.8.0 and PhoneGap-Android 4.0.0)
  1. Go to a directory of your choice where you want to create your app and launch the console

  2. In this directory create a new Cordova project with the Cordova CLI

     $ cordova create AugmentedRealityProject com.yourid.arsample ARProject
    

    The argument will create a directory called AugmentedRealityProject as your project directory. Two other parameters are optional and provide the package name of the app and the actual app name.

    You should see a success message like

     $ Creating a new cordova project with name "AugmentedRealityProject" and id "com.yourid.arsample" at location "/Users/pete/Projects/ARProject"
     $ Downloading cordova library for www...
     $ Download complete
    
  1. Change into the project directory

     $ cd AugmentedRealityProject
    

    Your project directory now should roughly look like this:

     - AugmentedRealityProject
     |- hooks
     |- merges
     |- platforms
     |- plugins
     |- www
    
  2. Now add the platforms you like to create an app for. This depends on whether your development machine can run the corresponding native SDKs (e.g. you can't add iOS on a Windows machine). In this guide we assume your are working on a Mac want to create an app for iOS and Android.

    In the first step add the ios platform

     $ cordova platform add ios
    

    Which will result in

     $ Downloading cordova library for ios...
     $ Download complete
     $ Creating ios project...
    

    Then build the app for ios

     $ cordova build ios
    

    After the script has completed to build and compile the app you should see a success message like the following below:

     $ ** BUILD SUCCEEDED **
    

    Next add the Android platform in the same manner:

     $ cordova platform add android
     $ cordova build android
    

    Which should result in

     $ BUILD SUCCESSFUL
     $ Total time: 30 seconds
    
  3. Now add the Wikitude SDK to the project by installing the Wikitude Cordova Plugin

     $ cordova plugin add https://github.com/Wikitude/wikitude-cordova-plugin.git
    

This may take a while (more than one minute) without any update message in the command line, depending on how fast the plugin is cloned from GitHub and downloaded (more than 30MB)
The command will quit with the following success message
        $ Plugin "com.wikitude.phonegap.WikitudePlugin" fetched.
Your project directory now should roughly look like this

    - AugmentedRealityProject
    |- hooks
    |- merges
    |- platforms
        |- android
        |- ios
    |- plugins
        |- com.wikitude.phonegap.WikitudePlugin
    |- www
  1. After the Wikitude plugin has been added build the app again.

     $ cordova build
    

    You now have successfully created a new Cordova based app including the Wikitude SDK. Depending on you preference we recommend to work with Xcode for the iOS part and Android Studio for Android development.

    • Android
      • Start Android Studio
      • Click on Open an existing Android Studio project
      • In the open dialog navigate to your project root/platforms/android and click on choose
      • If after the last step another dialog with the title Import project from gradle pops up, remove /gradle from the path to your project and click ok
    • iOS
      • Go the the platforms/ios folder and open the Xcode project by clicking the .xcodeproject file.
  2. Start to use the Wikitude Plugin in your Cordova application

Setup adding the plugin to an existing app


Note again, that this guide has been written based on Cordova 5.0.0 and the tools it brings. If you are using a different version this method might not work for you.
  1. Open a console and go to your project directory
  2. Run the cordova plugin add command

     $ cordova plugin add https://github.com/Wikitude/wikitude-cordova-plugin.git
    

    This will add the plugin to your application.

  3. After the Wikitude plugin is added build the app

     $ cordova build
    

Wikitude Sample App - Getting Started quickly

Wikitude offers a fully-configured example application as Cordova app. The application demonstrates the usage of the Wikitude Cordova Plugin as well as the usage of the ARchitectView. Furthermore the application includes several augmented reality examples which are described in more detail in the Example section of this documentation.

Automatic Setup of Sample App

  1. Download the binary of the Sample App from GitHub
  2. Unzip the binary file (wikitude-phonegap-samples-master.zip)
  3. Open the console and change to the directory where you unzipped the binary
  4. In the console run the CreateSampleApp.sh script. Use the -d flag to specify where the Sample App should be created. The -ios and -android flags control which platform should be compiled after creating the app.

     Linux/Mac OS X:
     $ ./CreateSampleApp.sh -d ~/Path/Where/The/App/Should/Be/Created -ios true -android true
    
     Windows:
     $ ./CreateSampleApp.cmd -d ~/Path/Where/The/App/Should/Be/Created -ios true -android true
    


    This may take a while (more than one minute) without any update message in the command line, depending on how fast the plugin is cloned from GitHub and downloaded (more than 30MB)

    The script might run for some minutes without feedback as it is downloading more than 30MB from GitHub. It will finish with the following success message:

     $ *** DONE - SUCCESS ***
    
  5. Open the project in Xcode (iOS) or Android Studio (Android) and run it on your device.
  6. Done

Add Samples manually to your App

In case you want to add sample code to your own existing app you need to copy the following resources to your app and re-build the app

  1. Download the binary of the Sample App from GitHub
  2. Unzip the binary file (wikitude-cordova-plugin-samples-master.zip) which will create a directory called SampleAppResources
  3. Copy the following files

    • All files from SampleAppResources/css into your www/css directory
    • All files from SampleAppResources/js into your www/js directory
    • The entire directory SampleAppResources/jquery into your www/ directory
    • The entire directory SampleAppResources/world into your www/ directory
    • Copy index.htmlfrom SampleAppResources/ into your www/ directory (overwrite)

      Your project directory now should roughly look like this

      • PROJECT_DIRECTORY |- hooks |- merges |- platforms |- plugins |- com.wikitude.phonegap.WikitudePlugin |- www |- css |- index.css |- jquery.mobile.structure-1.3.2.min.css |- index.html |- jquery
          |- (more files)
        
        |- js
          |- index.js
        
        |- world
          |- (more files)                                              
        
  4. Rebuild the project

Using the Wikitude Plugin to create your own augmented reality experience

Now that the Wikitude Plugin is added you can start using it inside the Cordova application to load and display your own augmented reality experience.

Enter your license key

Before that you need to add a license key to your application. Otherwise the application will show an Unlicensed watermark across the camera. Each developer is provided with a free trial license key, which will remove the Unlicensed watermark and enable the trial mode.

  1. Go to License Page and download your personal license key for the Wikitude SDK
  2. Open the downloaded file and replace the text ENTER-YOUR-KEY-HERE for the property this._sdkKey in WikitudePlugin.js in line 12.

Remember that although the Cordova application as well as the augmented reality experience are written in HTML and JavaScript, both parts can't communicate directly with each other. This is because the Wikitude SDK is using its own web view and not the one which is driving the Cordova application. Therefore we added functionality to communicate between the two parts using a callback mechanism which is explained in more detail later on.

The code in the next section is assumed to run somewhere in your Cordova application. It could for example be in index.js.

Loading your augmented reality experience

The WikitudePlugin.js is the file a developer is typically working with while using the Wikitude Plugin. To create an instance of the Wikitude Plugin, call the cordova.require() function with our Plugin ID.

cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin")

One option to place this is the onDeviceReady() function provided by Cordova. This functions returns a reference which then can be stored as variable - in our sample we store it in the app object defined in index.js. The complete call will then look like the following:

app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin")

After the Plugin is created, the first thing to do is to check if your device is capable of running the augmented reality experience (see the Supported Devices for detailed requirements of the Wikitude SDK). You can use the isDeviceSupported(successCallback, errorCallback, requiredFeatures) function, providing a callback whether the device is supported or not and which features you would like to check. To show all available options for the required features list we define that this AR experience uses both image recognition ("2d_tracking") and geo ("geo"). If your AR experience only uses one or the other exclusively please only pass one of the two strings in the array. Otherwise you might deny an device without a compass, like many currently available Android tablets, to run an image recognition only experience. The complete call will then look like:

var app = {

    requiredFeatures: [ "2d_tracking", "geo" ],
    // ... some code ...

    onDeviceReady: function() {
        app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin");
        app.wikitudePlugin.isDeviceSupported(app.onDeviceSupported, app.onDeviceNotSupported, app.requiredFeatures);
    },
    onDeviceSupported: function() {
        // ... code that is executed if the device is supported ...
    },
    onDeviceNotSupported: function(errorMessage) {
        // ... code that is executed if the device is not supported ...
    },

    // ... some more code ...

};

In the success callback you can then load the augmented reality experience from either the application bundle or a remote URL. The function to use is loadARchitectWorld(loadedSuccessful-Callback, loadError-Callback, "path/to/your/experience", requiredFeatures, startupConfiguration).

With the first two parameters you can set callback functions that are called when either the AR experience is loaded or the URL is not reachable. The third parameter defines the url/path to your AR experience. The fourth parameter defines which features are required by this particular AR experience you are about to load. The fifth and last parameter lets you define additional startup settings. Again we activate both currently available features. In the startup configuration JSON object we define that the back camera should be used. If you would like to use the front camera define 'camera_position' as front instead. Please note that if the device only has one or the other the available one will be used regardless of what you defined. The camera_position setting is the only setting you can define right now, more settings might follow in later versions of the Wikitude SDK. The complete call will then look like this:

var app = {

    requiredFeatures: [ "2d_tracking", "geo" ],
    arExperienceUrl: "www/experience/index.html",
    isDeviceSupported: false,
    startupConfiguration: 
    {
        "camera_position": "back"
    },

    // ... some code ...

    onDeviceReady: function() {
        app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin");
        app.wikitudePlugin.isDeviceSupported(app.onDeviceSupported, app.onDeviceNotSupported, app.requiredFeatures);
    },
    onDeviceSupported: function() {
        app.wikitudePlugin.loadARchitectWorld(
            app.onARExperienceLoadedSuccessful, 
            app.onARExperienceLoadError,
            app.arExperienceUrl,
            app.requiredFeatures,
            app.startupConfiguration
        );
    },

    // ... some code ...

    onARExperienceLoadedSuccessful: function(loadedURL) {
        // ... do something when the augmented reality experience finished loading
    },
    onARExperienceLoadError: function(errorMessage) {
        // ... react on failures. That could be happen when the local path is wrong or the remote url returned an error code
    }

    // ... some code ...

};

This is all that has to be done to load your augmented reality experience. Please check out the complete code of this example below.

var app = {

    // Url/Path to the augmented reality experience you would like to load
    arExperienceUrl: "www/experience/index.html",
    // The features your augmented reality experience requires, only define the ones you really need
    requiredFeatures: [ "2d_tracking", "geo" ],
    // Represents the device capability of launching augmented reality experiences with specific features
    isDeviceSupported: false,
    // Additional startup settings, for now the only setting available is camera_position (back|front)
    startupConfiguration: 
    {
        "camera_position": "back"
    },
    // Application Constructor
    initialize: function() {
        this.bindEvents();
    },
    // Bind Event Listeners
    //
    // Bind any events that are required on startup. Common events are:
    // 'load', 'deviceready', 'offline', and 'online'.
    bindEvents: function() {
        document.addEventListener('deviceready', this.onDeviceReady, false);
    },
    // deviceready Event Handler
    onDeviceReady: function() {
        app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin");
        app.wikitudePlugin.isDeviceSupported(app.onDeviceSupported, app.onDeviceNotSupported, app.requiredFeatures);
    },
    // Callback if the device supports all required features
    onDeviceSupported: function() {
        app.wikitudePlugin.loadARchitectWorld(
            app.onARExperienceLoadedSuccessful, 
            app.onARExperienceLoadError,
            app.arExperienceUrl,
            app.requiredFeatures,
            app.startupConfiguration
        );
    },
    // Callback if the device does not support all required features
    onDeviceNotSupported: function(errorMessage) {
        alert(errorMessage);
    },
    // Callback if your AR experience loaded successful
    onARExperienceLoadedSuccessful: function(loadedURL) {
        /* Respond to successful augmented reality experience loading if you need to */ 
    },
    // Callback if your AR experience did not load successful
    onARExperienceLoadError: function(errorMessage) {
        alert('Loading AR web view failed: ' + errorMessage);
    }

};

app.initialize();

The Wikitude Plugin offers some more advanced functionality which is explained in the following section.

Adding communication between Cordova and ARchitect

In order to communicate with the augmented reality experience from within the Cordova application the Wikitude Plugin offers the callJavaScript(javaScript) function. The JavaScript will be evaluated in the context of the augmented reality experience. If the augmented reality experience is not fully loaded at the time this function is called, it will be evaluated as soon at the experience is loaded. A complete call will look like the following:

var app = {

    // ... some code ...

    onDeviceReady: function() {
        // ... onDeviceReady implementation
    },
    onDeviceSupported: function() {
        // ... code that is executed if the device is supported ...
    },
    onDeviceNotSupported: function(errorMessage) {
        // ... code that is executed if the device is not supported ...
    },
    onARExperienceLoadedSuccessful: function() {
        // NOTE: The 'createCircle(location, color)' function is defined in the AR experience
        app.wikitudePlugin.callJavaScript('createCircle(new AR.RelativeLocation(null, -10, 0), \'#97FF18\');');
    }
    // ... some more code ...

};

The Wikitude SDK defines a custom url scheme which can be used to communicate from the augmented reality experience to the Cordova application. You can set a Cordova application function that is called each time a document.location = architectsdk:// load request is done. The Wikitude Plugin setOnUrlInvokeCallback(callback) function can be used to set the callback. This can be done right before the augmented reality experience is loaded.

var app = {

    // ... some code ...

    onDeviceReady: function() {
        // ... onDeviceReady implementation
    },
    onDeviceSupported: function() {

        // setting up a callback to communicate from ARchitect into PhoneGap
        app.wikitudePlugin.setOnUrlInvokeCallback(app.onURLInvoked);

        app.wikitudePlugin.loadARchitectWorld(
            app.onARExperienceLoadedSuccessful, 
            app.onARExperienceLoadError,
            app.arExperienceUrl,
            app.requiredFeatures,
            app.startupConfiguration
        );
    },
    onDeviceNotSupported: function(errorMessage) {
        // ... code that is executed if the device is not supported ...
    },
    // ... some more code ...

};

The Wikitude Cordova Plugin offers 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 the WikitudePlugin.js to see how these functions can be used.

Further developer resources