Getting Started with Vuforia Engine for Android Development

Setting Up the Android Development Environment

Supported development platforms

Please refer to the Vuforia Engine Supported Versions page for details on the latest supported versions of Android and Android tools such as Java Development Kit (JDK) and Android Studio.

NOTE: This setup guide was written for the Win10 32/64-bit platform with special notes for other operating systems.

Steps:

If you have already set up the Android SDK and NDK, go directly to Installing Vuforia Engine for Android.

Vuforia Engine requires the Android SDK for Java and the Android NDK for C++. The SDK and NDK communicate over the Java Native Interface (JNI).

To set up the development environment, install these components in the following order, using the latest versions of the tools with Vuforia Engine:

  1. JDK (Java SE)
  2. Android Studio IDE
  3. Android SDK packages
  4. Optional; Android NDK
  5. Vuforia Engine for Android

If you are planning on developing in Android Studio with C++, install the Android NDK from the SDK Manager. See the Android SDK Packages section.

JDK

Mac OSX: The JDK is already integrated into the Mac OS X operation system.

For Windows systems:

  1. Download the Java SE Development Kit (JDK) from this site: http://www.oracle.com/technetwork/java/javase/downloads/
  2. Click Download from the JDK section of the 'Java Platform, Standard Edition' table.
  3. Install the JDK environment with default settings.

Detailed installation instructions and system requirements can be found at: http://www.oracle.com/technetwork/java/javase/index-137561.html

Install Android Studio

Android Studio provides everything you need to start developing apps for Android, including the Android Studio IDE and the Android SDK tools.

1.       Download the Android Studio installer from: https://developer.android.com/studio choosing your preferred operating system and 32-bit or 64-bit.

  1. Once the download has completed, run the installer executable, and follow the official installation instructions to install the IDE.
  2. Pay attention to the following installation steps:
    • In the Configuration Settings Install Locations step of the install wizard the default directory that will be used is C:\Program Files\Android\Android Studio. We suggest to select or create a path that is easier to find such as C:\Development\Android. The SDKs and Vuforia Engine can hereafter be installed in that directory.

Android SDK Packages

Android Studio includes a SDK manager that allows you to install additional SDK components, besides the ones installed with Android Studio, and to update your Android SDK tools.
We recommend running the SDK Manager after the installation of Android Studio, in order to download the necessary components for developing with Vuforia Engine.

  1. Launch Android Studio
  2. In the Welcome to Android Studio, click on Configure and select SDK Manager or 
  3. In Android Studio, click on the SDK Manager icon in the Toolbar. 
Vuforia Image
  1. In the dialog window that opens, set Android SDK Location to C:\Development\Android\android-sdk
  2. Select the desired tools:
Vuforia Image
  • Tools:
    • Android SDK Tools (latest rev.)
    • Android SDK Build Tools (latest rev.)
    • Android SDK Platform-Tools (latest rev.)
  • Extras:
    • Google USB Driver (Windows only)
    • Android API matching that of your own Android device.
    • Android NDK

NOTE: the NDK is for developers implementing C++ programming in their native applications. If you plan to only use the Java API, installing the NDK is not necessary.

Once you've selected all the desired packages, continue to click install and accept the license agreements.

NOTE: the downloads progress is shown at the bottom of the SDK Manager window. Do not exit the SDK Manager or it will cancel the download.

Setting the System Environment Variables

If you have chosen a different folder directory than the default, it is necessary to add those directories to your Windows Path:

  1. In the File Explorer, right-click This PC and select Properties.
  2. Click the Advanced system settings button to open the System Properties window
  3. Under the Advanced tab, select Environment Variables and select Variable Path in the System variables window.
  4. After pressing Edit, scroll to the end of Variable value: and add New variable. Add the full path to the directory at the end of the path, separated by a semicolon from the previous path. In the above example, you would add:
C:\Development\Android\android-sdk\tools\;C:\Development\Android\android-sdk\platform-tools\

NOTE: The last "\" at the end of the Path variable must be included.

Mac OSX: Update the PATH variable to point to the Android SDK Platform-tools directory in the /etc/rc.common file or ~/.bash_profile:

export PATH=$PATH:~/Development/Android/android-sdk/tools:~/Development/Android/android-sdk/platform-tools

Linux: Update your PATH to point to the Android SDK Platform-tools directory. If you use bash shell, add the following to ~/.bashrc :

export PATH=$PATH:/opt/android-sdk/tools:/opt/android-sdk/platform-tools

Installing Vuforia Engine for Android

Clean installation

Vuforia Engine is distributed as a ZIP package for the following platforms:

  • Windows
  • Mac OS

To start developing with the Vuforia Engine SDK:

  • Download Vuforia Engine for Android
  • Extract the contents of the SDK ZIP archive, placing it in your Android development root folder (e.g. C:\Development\Android on Windows, or /Users/[account]/Development/Android on OSX or Linux)
  • As a convention, we will refer to the root directory of your Vuforia Engine for Android development environment as DEVELOPMENT_ROOT

Extracting the SDK will create a directory structure for your Android development environment. This structure ensures that Vuforia Engine sample apps can easily be built and deployed using the Android SDK, Android NDK, and the Android Studio development environment.

Upgrading from a previous version

Resulting directory structure

To streamline development, we have defined a directory structure that maintains Vuforia Engine and your applications in separate directory trees. This enables the SDK to be updated without the need to modify your source tree.

The extracted SDK archive will create the following directory structure in the vuforia-sdk-android-[ xx-yy-zz ] folder. The pattern xx-yy-zz stands for the version number of Vuforia Engine.

  <DEVELOPMENT_ROOT>\
 
  android-ndk-rxy\
   
  android-sdk\
   
  vuforia-sdk-android-xx-yy-zz\
 
  build\                 // Vuforia Augmented Reality SDK         
 
  licenses\              // License Agreements
 
  samples\               // Sample applications with full source code
 
  assets\                // Additional assets required to use Vuforia SDK
 
  readme.txt             // Starting read-me document

Enabling Developer settings on your handheld device

Android devices require special settings for development.

You will need to:

  • Enable installing apps from unknown sources
    • On the device, go to Settings > Security and choose Unknown sources. This setting allows direct installation of unsigned APKs from within Eclipse.
  • Enable USB debugging
    • Go to Settings > Developer Options and enable the USB debugging.
Vuforia Image

Install the USB driver (Windows only)

  • Connect your device to the development PC using the USB cable.

On initial connection, Windows recognizes the new device and attempts to locate a compatible driver. The Android SDK already includes some USB drivers, others can be obtained directly from the device manufacturer.

SDK pre-packaged drivers can be located in the following directory:

<DEVELOPMENT_ROOT>\android-sdk\extras\google\usb_driver

Your device will be ready to use when the device driver installation has completed.

Compiling and Running an Android Sample

Vuforia Engine for the Android platform includes both a Java API and a C++ API. The Java samples demonstrate all the main features of Vuforia Engine; in addition, there is a C++ sample implementation of the Image Targets feature, called ImageTargetsNative-x-y-z, which shows how to use the C++ native API: found under Advanced Topics.

Sample Name

Description

API

VuforiaSamples-x-y-z Sample demonstrating all the main Vuforia Engine features JAVA
BackgroundTextureAccess-x-y-z Sample demonstrating how to access and manipulate the video background texture JAVA
Books-x-y-z Sample demonstrating an advanced use case for the Cloud Recognition feature JAVA
OcclusionManagement-x-y-z Sample demonstrating advanced rendering effects with the Multi Targets feature JAVA
VideoPlayback-x-y-z Sample demonstrating how to play videos in an AR experience with Image Targets JAVA
ImageTargets-Native-x-y-z Sample demonstrating a native C++ implementation of the Image Targets feature C++

Vuforia Engine samples can be downloaded from https://developer.vuforia.com/downloads/samples
Once downloaded, extract the sample ZIP packages and copy them into the samples folder under your Vuforia Engine installation directory (e.g., C: \...\Android\vuforia-sdk-android-xx-yy-zz\samples\ ).

The VuforiaSamples-x-y-z application is a good place to start learning about the SDK, because it shows the main features of the SDK in a single app. This section explains how to use Android Studio to build the Java sources and create the APK package that can be deployed to the device.

Building a Sample

To build a Vuforia Engine sample for the Android platform, follow these steps:

  1. Launch Android Studio.
  2. Select Open an existing Android Studio project from the Quick Start launch page
Vuforia Image
  1. Browse to the \…\vuforia-sdk-android-xx-yy-zz\samples\VuforiaSamples-x-y-z directory and click OK to open it.
  2. When opening a sample project for the first time, Android Studio may prompt a dialog asking whether you want to create a Gradle Wrapper for the project; you can answer yes by clicking the OK button:
Vuforia Image
  1. Once the project is loaded, open the Build menu and select Make Project to compile the app. This will also create the APK package for deployment; the generated APK files are stored by Android Studio in the app/build/outputs/ sub-directory of the sample project.

    Alternatively, you can click Rebuild Project to trigger a clean and full rebuild of the application.
Vuforia Image
  1. If you have not already done so, create a license key for your app.
  2. Add the license key to your app.

Running the Vuforia Engine Samples application

If you click the Run menu item on the toolbar, or on the little arrow icon next to the app menu button, the app will be compiled, installed, and launched on the target device.

Vuforia Image

Upon startup of the Vuforia Engine Samples app, a main menu is shown on your device, from which you can select a specific sample feature:

Vuforia Image
Vuforia Image

Example image of the ground plane sample where a chair can be placed on any horizontal surface.

Troubleshooting

If you encounter problems during the installation of the sample app, check the device’s connection settings in Troubleshoot device connection.

In Android Studio, you can see if the device is connected correctly via the Android Profiler, which you can activate if your device is detected and listed under Devices in Android Studio.

Vuforia Image
Vuforia Image

Installing an APK using ADB

You can install an APK onto an Android device by connecting the device to a PC with a USB cord and then connecting to the device using the Android Debug Bridge (ADB).

  1. Connect the device to the developer desktop environment with a USB cable.
  2. Open a bash shell or Windows Command Line and execute:
adb devices

The output should show the attached device:

$ adb devices

List of devices attached
HT012P123456 device

3. To install the application, navigate to the folder containing the downloaded APK. In our example C:\Temp and install APK using adb.

$ cd C:\Temp

$ adb install VuforiaSample.apk

4. If the device list is empty, or a given device is not listed, kill the ADB server by executing:

adb kill-server

5. Execute adb devices again to restart the server, re-detect devices, and try again.