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 Android Studio.

NOTE: This setup guide was written for the Windows 10 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 and the Android NDK for C++ development.

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

  1. Android Studio IDE
  2. Android SDK
  3. Android NDK
  4. Vuforia Engine for Android

In order to develop in Android Studio with C++, install the Android NDK from the SDK Manager. See the Android SDK Packages section.

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.
  2. Once the download has completed, run the installer executable, and follow the official installation instructions to install the IDE.
  3. 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 in Android Studio, click on the SDK Manager icon in the Toolbar. 

  1. In the dialog window that opens, set Android SDK Location to C:\Development\Android\android-sdk
  2. Select the desired tools:

  • 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
  1. Once you have 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 plan to work outside of Android Studio and use tools like adb directly, you will need to manually configure Environment Variables on your system for Android development.
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
  
  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.

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 is accessible through a C++ API. The sample applications demonstrate the Image Targets and Model Targets features of Vuforia Engine and shows how an application written in Kotlin can use the C++ API.

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

The Vuforia-sample-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 source code 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.

  1. Browse to the \…\vuforia-sdk-android-xx-yy-zz\samples\Vuforia-samples-x-y-z\Android 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:

  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.

  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.

Upon startup of the Vuforia Engine Sample app, a main menu is shown on your device, from which you can select between the Image Targets or Model Targets feature:

Select the Image Targets feature to get started.

You have successfully deployed your first application with Vuforia Engine!

Tap the screen once to trigger the camera to focus, or double-tap to go back to the main menu.

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.

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.

Can this page be better?
Share your feedback on our community forum