Overview of the SDK

This document presents the basic principles and different classes of the Android version of the SDK.

SDK Structure overview

For each SDK release, a package is provided as a tar-gzipped file. Uncompress to get access to the SDK library and sample code.

The SDK package contains two directory with the following content:

• libs/ containing the SDK library (as a AAR file) which is needed to be embedded in your project.
• demos/ containing a sample demo application using the SDK.

Embedding the SDK in an application

To embed the SDK in your Android application using Android Studio, follow the below steps:

1. Create, if not existing, a libs directory in the app/ directory of your project.
2. Copy the file vdarsdk-release.aar residing in the libs/ directory of the SDK into the newly created libs/ directory of your project.
3. In the build.gradle file of your application, add the following lines:

   repositories {
       mavenCentral()
       flatDir {
           dirs 'libs'
       }
   }
   
   dependencies {
       implementation name:'vdarsdk-release', ext:'aar'
       implementation 'com.android.support:appcompat-v7:28.0.0'
       implementation 'com.github.mhiew:android-pdf-viewer:3.2.0-beta.1'
       // your own dependencies are here
   }
                   

Your first Augmented Reality Activity

The SDK comes with a view class VDARAnnotationView rendering the camera view and the annotations. The best practice is to embed this view in an "Augmented Reality Activity" in your application. When the user wants to use the augmented reality part of the application, you can then launch this AR activity accordingly.

You AR activity would typically perform the following task when created (in the Activity onCreate(Bundle) method):

1. Start the SDK Controller by calling the startSDK(Context, String, String) method.
   This method will start the whole Augmented Reality system by loading the locally saved AR & Beacon contents and setting up everything for the rendering. This loading process is done asynchronously to the call. That's why you should make sure to check the result of isLoaded() before calling any functions of the SDK Controller.
   
   You can also schedule a task to be run when the loading process is over by calling the addNewAfterLoadingTask(Runnable) method. All the tasks scheduled will be run on the main UI thread.
   
   Note that starting the VDARSDKController if it has already been started has no effect. Moreover, the VDARSDKController is a singleton instance and, therefore, will be the same instance for the whole application life.
2. Set your activity as the main AR activity using the SDK Controller (only one activity can use the SDK Controller at a time):

   VDARSDKController.getInstance().setActivity(this);
   

3. [Optional] Enable QR Code recognition:

   VDARSDKController.getInstance().setEnableCodesRecognition(true);
   

   Note that this not only provide to your activity the ability to recognize standard QR code but the SDK understands special QR codes that can be used to trigger the download of a specific content, to trigger a tag-based synchronization of contents or even to switch the used servers to the Vidinoti Test Servers. See the setEnableCodesRecognition(boolean) method documentation for more information.

4. [Optional] Enable Push Notifications. For that follow the Enabling Push Notifications guide.

5. Start the download of some contents from your V-Director account. You can start a synchronization so that all contents you have published on V-Director platform will be available on the users devices. When you delete / add new contents in your account, the corresponding contents will also be added/deleted on users devices. The best practice is to launch a synchronization every time the application is launched, even if the AR activity is not opened. This allows a seamless user interactino as the user won't need to wait for the content to be loaded when the AR activity is opened.

   The following sample code shows how to make a synchronization:

   //We schedule a task to be run after the manager it is loaded as it is more or less sure tha
   //the loading process is not yet done.
   VDARSDKController.getInstance().addNewAfterLoadingTask(new Runnable() {
   
                   public void run() {
                           VDARRemoteController.getInstance().syncRemoteContextsAsynchronouslyWithPriors(null, new Observer() {
   
                                   public void update(Observable observable, Object data) {
                                           ObserverUpdateInfo info = (ObserverUpdateInfo) data;
   
                                           if (info.isCompleted()) {
                                                   Log.v("MyActivity", "Done syncing. Synced " + info.getFetchedContexts().size() + " contents:");
                                                   for (String mID : info.getFetchedContexts()) {
                                                           Log.v("MyActivity", mID);
                                                   }
                                           }
   
                                   }
                           });
                   }
           });
   

6. A camera object has to be created to allow the SDK to get access to the camera. The camera is automatically registered within the SDK upon creation:

   DeviceCameraImageSender imageSender = new DeviceCameraImageSender();
   

7. Embed a VDARAnnotationView into your activity view layout using the CustomView element of the Android Interface builder.
8. You should now add the onResume() and onPause() call on the VDARAnnotationView that you have embedded as soon as your activity is paused / resumed. Not doing so will make your application crash.

9. To be compatible with Android 6, you have to redirect the calls to onRequestPermissionsResult() in your activity to the SDK. Put this in your activity: