Getting Started with Vuforia for Android Development


Setting Up the Android Development Environment

Supported development platforms

  • The Vuforia SDK officially supports Android OS 4.1 and above, and OpenGL ES 2 and 3.
  • The recommended development environment is Microsoft Windows 7 or 8 32/64-bit.
  • The components of the build environment (JDK, Android Studio, Android SDK / NDK) are available for multiple platforms. 

        Note: This setup guide has been written for the Win7 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 the Vuforia Android SDK

The Vuforia SDK requires the Android SDK and the NDK. The Android NDK is an extension of the Android SDK that allows Android developers to build performance-critical parts of their applications in native code. 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 the Vuforia SDK:

  1. JDK (Java SE)
  2. Android Studio IDE
  3. Android SDK packages
  4. Cygwin environment
  5. Android NDK

JDK

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

  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

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: http://developer.android.com/sdk/index.html
  2. Once the download has completed, run the installer executable and follow the installation instructions to install the IDE in the destination directory of your choice (e.g. C:\Program Files\Android\Android Studio ); in particular, pay attention to the following steps:
    • In the Select components to install page, make sure that Android SDK option is selected;
    • In the Configuration Settings Install Locations page of the install wizard, specify the location where you want to install the Android SDK; we suggest to set it to a location like C:\Development\Android\android-sdk , where C:\Development\Android represents the base directory of your Android development environment; this is also the directory where you will want to install the Android NDK, as discussed later in this guide (note: we will refer to such base directory as <DEVELOPMENT_ROOT> in the remainder of this guide)

Android SDK Packages

By installing Android Studio, you also installed the most recent version of the Android SDK and the relevant SDK tools. However, the SDK Manager allows you to install additional / optional SDK components and to update your Android SDK and SDK tools to the latest revisions available; therefore you may want to periodically run the SDK Manager to check for the latest SDK revisions, and update to them if necessary.
We also recommend to run the SDK Manager at least once after the installation of Android Studio, to download the necessary components for developing with Vuforia:

  1. Launch Android Studio
  2. In Android Studio, click on the SDK Manager icon in the Toolbar. 
  3. In the dialog window that opens up, click on the Launch Standalone SDK Manager
  4. In the SDK Manager standalone window, select the following packages to install:
  • Tools:
    • Android SDK Tools (latest rev.)
    • Android SDK Build Tools (latest rev.)
    • Android SDK Platform-Tools (latest rev.)
  • Android 6.0 (API 23):
    • SDK Platform
    • Documentation for Android SDK
      • NOTE: These items should have been already installed during the Android Studio installation (if not, simply select them for installation)
  • Android 5.1.1 (API 22):
    • SDK Platform
      • NOTE: Vuforia 5.0.x does not fully support Android 6.0 (akas Android Marshmallow or Android M ); therefore we recommend installing the Android 5.1.1 (API 22)
  • Extras:
    • Google USB Driver (Windows only)


Once you've selected all the desired packages, continue to install:

  1. Click 'Install X packages'
  2. In the next window, double-click each package name on the left to accept the license agreement for each.
  3. Click Install.

The download 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

Add the Android SDK tools and platform-tools directories to your Windows Path:

  1. Right-click My Computer on the desktop and select Properties .
  2. Click the Advanced System settings button ab to open the System properties window
  3. Under the Advanced tab, select Environment Variables and look for the Variable Path in the System variables window.
  4. After pressing Edit, scroll to the end of Variable value: and add the full path to the directory to 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 has to 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:

 PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/libexec:/System/Library/CoreServices:/Developer/usr/bin:~/Development/Android/android-sdk/tools:~/Development/Android/android-sdk/platform-tools:export PATH


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=/opt/android-sdk/tools/:/opt/android-sdk/platform-tools/:

Cygwin environment

Linux: This section is not relevant for Linux users who have GNU make installed and in their path.
Mac OSX: This section is not relevant for Mac users who have Apple Developer Tools (XCode) installed. Install XCode if necessary from http://developer.apple.com/xcode/.

The Vuforia SDK for the Android platform includes both a Java API and a C++ API. The Java API enables the full suite of Vuforia features and functionalities and allows developers to build Android applications without having to write native C++ code.

The C++ API is meant to be used by developers with very advanced / specific requirements, such as the ability to integrate C++-based third party libraries or custom C++ software components. When this is not required, it is generally recommended to use the Java API.

If you expect to need the C++ native API, you will need a C++ GNU compiler, as explained in the following paragraph; otherwise, for pure Java based development, you can skip this section.

A GNU compiler is required to compile dynamic applications as shared libraries for the Android NDK. Android makefiles are designed to run with gcc4. On Windows, a convenient way to have the complete environment prepared for this is to install Cygwin.

Cygwin uses an installer helper to manage the installation process.

  1. Go to http://www.cygwin.com, download and run the installer (setup.exe)
  2. Select "Install from the Internet!" when prompted at "Choose a Download Source" in the installer. We recommend not changing the Root Directory in the next window, and leaving it at "C:\cygwin." The "Local Package Directory" holds the downloaded packages. You may want to keep them with the downloaded Setup.exe file in the same directory to have a Cygwin installer directory. Choose a download site with a known fast connection near you.

When the package information is downloaded you will see a hierarchical browser to select packages.

  1. Select the following package from the hierarchy for download: All -> Devel -> "make: The GNU version of the 'make' utility"
  2. Select the word skip to change it to the actual version number that will be installed
  3. Finish the installation by clicking Next.

Your Cygwin environment is fully set up to work with the Vuforia SDK. If you have other similar environments installed, make sure to set your Windows path variable to point to "C:\cygwin\bin" so that bash uses this version of GNU's make.exe.

Android NDK

The Android NDK is an extension of the Android SDK that lets Android developers build performance-critical parts of their applications in native code.
If you need to use the C++ API of the Vuforia SDK, you will also need to install the Android NDK which enables native C++ programming on Android. If you plan to only use the Java API, you may skip this section.

  1. Download the NDK package from http://developer.android.com/sdk/ndk/index.html
  2. Unzip the archive, and copy the contents into a directory. To be consistent with our previous setup, we recommend putting the contents in "C:\Development\Android\android-ndk-rxy\". Thus, Android SDK and Android NDK share the same parent directory. Later, we will add the Vuforia SDK and your project files. NDK requires the above directory to be added to the Windows path.
  3. Right-click My Computer on the desktop and select Properties .
  4. Click the Advanced System settings button to open the System properties window
  5. Under the Advanced tab, select Environment Variables and look for the Variable Path in the System variables window.
  6. After pressing Edit, scroll to the end of Variable value: and add the full path to the directory to the end of the path, separated by a semicolon from the previous path. In the above example, you would add:
;C:\Development\Android\android-ndk-rxy\


NOTE: Path has a semicolon at the beginning. Do not use pathnames with spaces. Alternatively, you can set a User variable with the name Path, but this is valid only for the current user. The last "\" at the end of the Path variable has to be included.

To test your installation, compile any of the NDK sample applications. Using a Cygwin bash shell, navigate to the root directory of any demo application (e.g., for the 'san-angeles' sample app without the installation path above):

cd /cygdrive/c/Development/Android/android-ndk-rxy/samples/san-angeles
ndk-build 


The compiler should produce a dynamically linked library libsanangeles.so and write it to /libs/armeabi within the application directory. NDK includes support for different architectures so you might find different subdirectories in /libs.
Now your development environment is ready to host Vuforia SDK-related content.

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

PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/libexec:/System/Library/CoreServices:/Developer/usr/bin:~/Development/Android/android-sdk-macosx/tools:~/Development/Android/android-sdk-macosx/platform-tools:~/Development/Android/android-ndk-rxy:export PATH


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

export PATH=~/bin:/opt/android-sdk-linux_x86/tools/:/opt/android-ndk-rxy:

Installing the Vuforia Android SDK

Installing the Vuforia Android SDK

Clean installation

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

  • Windows 7 or 8 32/64-bit
  • Mac OS X

To start developing with the Vuforia SDK:

  • Download the Vuforia Android SDK
  • 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 )

Extracting the SDK will create a directory structure for your Android development environment. This structure ensures that Vuforia 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 the Vuforia SDK and your applications in separate directory trees. This enables the SDK to be updated without the need to modify your source tree.

As a convention, we will refer to the root directory of your Vuforia Android development environment as

<DEVELOPMENT_ROOT>

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 the Vuforia SDK.

<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

Install the Vuforia SDK

Download
The Vuforia SDK is distributed through the Developer Portal.

Note: Although we distribute the Vuforia SDK for the platforms listed below, support for development is limited to the Win 7 32/64-bit platform.

 

  1. Download the archive file from the Downloads page.
  2. Extract the content of the archive and store it under <DEVELOPMENT_ROOT>.

Prepare test device for development

Developer settings on the 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.
https://vuforialibrarycontent.vuforia.com/Images/setup_USBdebugging.jpg

  • Enable USB debugging

Go to Settings > Developer Options and enable the USB debugging and Stay awake options.

User-added image

Note that USB debugging is mandatory, the Stay awake setting is a convenience that helps with development.

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.

 


How to Compile and Run an Android Sample

The Vuforia SDK for the Android platform includes both a Java API and a C++ API. The Java samples demonstrate all the main features of the Vuforia SDK; 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:

Sample Name

Description

API

VuforiaSamples-x-y-z Sample demonstrating all the main Vuforia SDK 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
Dominoes-x-y-z Sample demonstrating advanced touch-based interaction with the Image Targets 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++


The Vuforia 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 SDK installation directory (e.g., C: \Development\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 the Samples

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

1. Launch Android Studio
2. Select Open > File or Project from the File menu, or select Open an existing Android Studio project from the Quick Start launch page

 

3. Browse to the <DEVELOPMENT_ROOT>\vuforia-sdk-android-xx-yy-zz\samples\VuforiaSamples-x-y-z directory and click OK to open it

4. 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:

5. 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 on Rebuild Project to trigger a clean and full rebuild of the application.

Running the Vuforia Samples application

If you click on the Run menu item in 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.

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


Troubleshooting

If you encounter problems on the installation, check the device connection settings in Prepare Test Device for Development. In Android Studio, you can see if the device is connected correctly via the Android Device Monitor, which you can open by clicking on the Android icon in the toolbar. The device must be listed under Devices.

The device must be listed under Devices, and should appear with Online status.

Alternatively, open a Cygwin bash shell and execute:

adb devices


The output should show the following attached device:

$ adb devices
 
List of devices attached HT012P123456 device

*the attached device ID will reflect the Model ID of the devices attached to you ADB host.

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

adb kill-server

Execute 'adb devices' again to restart the server and re-detect devices.


How To Install 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 Cygwin 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 /cygdrive/c/temp

$ adb install thisIsTheAPKName.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.