Setup Guide PhoneGap Plugin

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 PhoneGap .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 PhoneGap 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.

Creating an empty new app

Note The guide is based on PhoneGap version 3.5.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 PhoneGap project with the PhoneGap 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 PhoneGap Plugin

     $ cordova plugin add https://github.com/Wikitude/wikitude-phonegap.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 PhoneGap based app including the Wikitude SDK. Depending on you preference we recommend to work with Xcode for the iOS part and Eclipse for Android development.

    • Android
      • Start Eclipse
      • Inside Eclipse select File > Import to start the import wizard
      • Select Existing Android Code Into Workspace and click Next >
      • Browse to your project directory and select the platforms/android directory
      • Click Select All and then Finish to complete the import
    • 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 PhoneGap application

Setup adding the plugin to an existing app


Note again, that this guide has been written based on PhoneGap 3.5.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-phonegap.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 PhoneGap app. The application demonstrates the usage of the Wikitude PhoneGap SDK 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.

     $ ./CreateSampleApp.sh -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 Eclipse (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-phonegap-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 PhoneGap application to load and display your own augmented reality experience. Remember that although the PhoneGap 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 PhoneGap 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 PhoneGap 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 PhoneGap. 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) function, providing a callback whether the device is supported or not. The complete call will then look like:

var app = {

    onDeviceReady: function() {

        // ... some code ...

        // create a Wikitude Plugin instance
        app.wikitudePlugin = cordova.require("com.wikitude.phonegap.WikitudePlugin.WikitudePlugin");

        // check if the current device is able to launch augmented reality experiences
        app.wikitudePlugin.isDeviceSupported(app.onDeviceSupported, app.onDeviceNotSupported);
    },
    onDeviceSupported: function() {
        // ... code that is executed if the device is supported ...
    },
    onDeviceNotSupported: function() {
        // ... code that is executed if the device is not supported ...
    }
};

In the success callback you can then load the ARchitect World from either the application bundle or a remote URL. The function to use is loadARchitectWorld("path/to/your/world"). You can set callback functions on the Wikitude Plugin that are called when either the world is loaded or the URL is not reachable. A complete call will then look like:

var app = {

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

        // setting callback functions that are called when the ARchitect World finished launching or failed.
        app.wikitudePlugin._onARchitectWorldLaunchedCallback = app.onARchitectWorldLaunched;
        app.wikitudePlugin._onARchitectWorldFailedLaunchingCallback = app.onARchitectWorldFailedLaunching;

        // load an ARchitect World
        app.wikitudePlugin.loadARchitectWorld("www/res/ARchitect/SimpleCircle.html"); // load an ARchitect World from the application bundle
    },
    onDeviceNotSupported: function() {
        // ... code that is executed if the device is not supported ...
    }
    onARchitectWorldLaunched: function() {

        // ... do something when the ARchitect World finished loading
    },
    onARchitectWorldFailedLaunching: function() {
        // ... react on failures. That could be happen when the local path is wrong or the remote url returned an error code
    }
};

This is all that has to be done to load your augmented reality experience.

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

Adding communication between PhoneGap and ARchitect

In order to communicate with the augmented reality experience from within the PhoneGap 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 = {

    onDeviceReady: function() {
        // onDeviceReady implementation
    },
    onDeviceSupported: function() {
        // onDeviceSupportedCallback implementation
    },
    onDeviceNotSupported: function() {
        // onDeviceNotSupportedCallback implementation
    },
    onARchitectWorldLaunched: function() {
        // NOTE: The 'createCircle(location, color)' function is defined in the ARchitect World
        app.wikitudePlugin.callJavaScript('createCircle(new AR.RelativeLocation(null, -10, 0), \'#97FF18\');');
    }
    // ... onWorldFailedLaunchingCallback implementation...
};    

The Wikitude SDK defines a custom url scheme which can be used to communicate from the ARchitect World to the PhoneGap application. You can set a PhoneGap 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 ARchitect World is loaded.

var app = {

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

        // setting callback functions that are called when the ARchitect World finished launching or failed.
        app.wikitudePlugin._onARchitectWorldLaunchedCallback = app.onARchitectWorldLaunched;
        app.wikitudePlugin._onARchitectWorldFailedLaunchingCallback = app.onARchitectWorldFailedLaunching;

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

        // load an augmented reality experience
        app.wikitudePlugin.loadARchitectWorld("www/res/ARchitect/SimpleCircle.html"); // load an ARchitect World from the application bundle
    },
    onURLInvoked: function(url) {
        alert('Wikitude AR => PhoneGap ' + url);
    }
    // ... onDeviceNotSupported & onARchitectWorldLaunched & onARchitectWorldFailedLaunching implementation ...
};

The Wikitude 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.

Trial and commercial license

By default the Wikitude SDK is shipped with a trial license (empty license key), which enables all features of the Wikitude SDK but displays a watermark across the AR view. For commercial usage of the Wikitude SDK in your product please check out the Wikitude SDK product page and have a look at the pricing plan for commercial licenses.

Then enter your Wikitude SDK license key in the WikitudePlugin.js file at line 9.

Further developer resources