Getting Started
A working example
Advanced
- Errors
- Limitations
Feedback and Contact
Android FAQ
- What if the minSdkVersion of my app is lower than the required by the SDK?

Getting Started

Import the SDK

Add Augment maven repository to your app’s build.gradle

repositories {
    maven {
        url  "https://dl.bintray.com/augment/augment"
    }
    maven { url 'https://jitpack.io' }
}

Add Augment Player as a dependency

dependencies {
    compile "com.ar.augment:augment-player-sdk:2.0.0-beta[x]"
}

Tracker resources

To make the Augment Player SDK fully functional, you also need to download this file, unzip it, copy extracted the files into src/main/assets of your project directory.

Overview

ProductDataController :

You can query product by it’s identifier, name and brand as mandatory and as optional it’s EAN which are set in a ProductQuery using a builder, it returns you Product instances.

AugmentPlayerSDK :

You can add model 3Ds to AugmentPlayerSDK with Product instances from ProductDataController

AugmentPlayer :

Once you add model 3Ds to AugmentPlayer via AugmentPlayerSDK you can resume or pause rendering

That’s all!

A working example

This example covers how to implement a simple Activity that uses Augment Player SDK

Setup

You need to create an AugmentPlayerSDK instance. This can be done anywhere in your app.

// These are demo credentials linked to the demo catalog below
String APP_ID = "357fee36746668573ceb2f5957c4869ee1a62a112639bac9b0fae43c7c431692";
String APP_SECRET = "80ae1420e164e0440d5329067bcdd953e9fa6c63b75c001c06d169a4f11268c5";
String VUFORIA_KEY = "ATQqCM7/////AAAAGXLs+GRi0UwXh0X+/qQL49dbZGym8kKo+iRtgC95tbJoCWjXXZihDl5pzxoca2JxLcYxBJ2pIeIE4dNcK0etMeb1746L7lq6vSFen43cS7P1P/HXjwHtUouV5Xus2U0F7WHUTKuO629jKFO13fBQczuY52UJcSEhsu9jHPMaupo5CpqQT3TFTQjlhzHhVXiVMEqq7RI+Edwh8TCSfGAbNRdbIELTfK+8YDYqwEHDbp62mFrs68YnCEQZDrpcLyC8WzFCVZtnUq3Cj3YBUfQ6gNnENYiuLf06gAAF/FcaF65VYveGRBbp3hpkqolX28bxPiUYNVknCSFXICPHciVntxF+rcHW5rrX7Cg/IVFGdNRF";
augmentPlayerSDK = new AugmentPlayerSDK(
    this.getApplicationContext(), APP_ID, APP_SECRET, VUFORIA_KEY
);

Initialize environment

The SDK needs some permissions to work properly so add those required permissions in your manifest or ask for those permissions at runtime for Android 6+

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Activity Lifecycle

You need to bind AugmentPlayer lifecycle to your Activity’s lifecycle.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // prepare your layout
    startARSession(); // Please refer to the section below
}

@Override
public void onResume() {
    super.onResume();
    augmentPlayerSDK.getAugmentPlayer().resume();
}

@Override
public void onPause() {
    augmentPlayerSDK.getAugmentPlayer().pause();
    super.onPause();
}

@Override
protected void onDestroy() {
    augmentPlayerSDK.getAugmentPlayer().stop();
    super.onDestroy();
}

Important! You have to pause the AugmentPlayer in the onPause() of your Activity

Products and catalog

Your first catalog

Augment SDK work with catalogs, when you ask for an API KEY we create a catalog on our server that will link between your references and our models.

To help you test our SDK we provide a demo catalog containing some demo references, here are the data

Identifier	Brand	Name
81	Samsung	TV
82	Lenovo	Yoga 900
83	Samsung	Washer
84	Whirlpool	Fridge
86	FINLANDEK	Couch
89	Restoration Hardware	Chair
90	Restoration Hardware	Table
91	Target	Chair
92	Target	Outdoor Chair
93	Bed Bath	Table
94	Bed Bath	Curtains
95	Sun Lounger	Frontgate
96	Ballard	Table
97	Adidas	Shoe
98	Nintendo	Switch

EAN are optional, pass an empty string for the demo

Query product

Use ProductDataController in order to query a product by its identifier , name and brand at least and for optional its ean (these 4 args are contained in a ProductQuery object ) over Augment database If the product exists in Augment database, ProductDataController returns an Product instance within completion block

public ProductQuery getProductQueryFor(String identifier, String brand, String name, String ean) {
    return new ProductQuery.Builder(identifier, brand, name).setEan(ean).build();
}

public void queryAndAddProductToAugmentPlayerWithUserIdentifier(final ProductQuery query) {
    ProductDataController dataController = augmentPlayerSDK.getProductDataController();
    dataController.checkIfModelDoesExistForUserProductQuery(
        query,
        new ProductDataController.ProductQueryListener() {
            // Called when the request completed successfully.
            @Override
            public void onResponse(@Nullable Product product) {
                if (product == null) {
                    // The request was successful but no product with given
                    // identifier exists on Augment Database
                    Log.e(LOGTAG, "Product is not available.");
                    Toast.makeText(MainActivity.this, "Product is not available.", Toast.LENGTH_LONG).show();
                } else {
                    // We have a product we can load in AR
                    addProductToAugmentedReality(product);
                }
            }

            // Called when the request failed
            @Override
            public void onError(WebserviceException error) {
                // Something went wrong while requesting the product
                // possible reasons: bad credentials, no network, ...
                Log.e(LOGTAG, "Product is not available.");
                Toast.makeText(MainActivity.this, error.getMessage(), Toast.LENGTH_LONG).show();
            }
    });
}

Load product

/**
 * Download and add existing Product to Augmented Reality scene
 * @param product existing Product instance returned by SDK's ProductDataController
 */
private void addProductToAugmentedReality(@NonNull final Product product) {
    augmentPlayerSDK.addModel3DToAugmentPlayerWithProduct(product, new LoaderCallback() {
        @Override
        public void onSuccess(String modelIdentifier) {
            // Save the identifier and hide the dialog.
            // You are now ready ready to visualise your product in Augmented Reality!
        }

        @Override
        public void onError(WebserviceException error) {
            // Show error. You could just end AR session as well since there is
            // nothing to visualise
        }

        @Override
        public void onDownloadProgressUpdate(Long progress) {
            // Display progress update
        }

        @Override
        public void onPreparingModel() {
            // Display some feedback to the user saying the download is starting
        }
    });
}

You can test it with an entry from the demo catalog

this.queryAndAddProductToAugmentPlayerWithUserIdentifier(
    getProductQueryFor(
        "84",
        "Whirlpool",
        "Fridge"
    )
);

Visualize

To start an Augmented Reality session, you need to initialise AugmentPlayer in your Activity. This is done in backgrounds and it calls your InitializationListener’s onInitARDone(GLSurfaceView surfaceView, AugmentPlayerException exception) upon completion.

You have to provide the initAR with a GLSurfaceView from your layout to display augmented reality. The SDK will set your glSurfaceView up automatically :

public void startARSession() {
    augmentPlayer.initAR(this, glSurfaceView, new InitializationListener() {

        @Override
        public void onInitARDone(GLSurfaceView surfaceView, AugmentPlayerException exception) {
            if (exception == null) {
                try {
                    augmentPlayer.start();
                    augmentPlayer.resume();
                } catch (AugmentPlayerException e) {
                    e.printStackTrace();
                }
            } else {
                Log.e(LOGTAG, exception.getString());
                showInitializationErrorMessage(exception.getString());
            }
        }

    });
}

After this step, you should be seeing the model on your screen

Important! Do NOT forget to pause the AugmentPlayer in onPause()!

Re-centering products

It happens that users lose sight of their product while looking away in augmented reality. You can re-center the products at any time by calling:

public void recenterProducts(View v) {
    augmentPlayerSDK.getAugmentPlayer().recenterProducts();
}

Detecting Gestures

You can listen and react to the user’s gestures using the SDK interface OnModelGestureListener.java, which let you know when the model is clicked, moved, rotated or rescaled.

augmentPlayer.addOnModelGestureListener(new OnModelGestureListener() {
    @Override
    public void onClick(float x, float y) {
        // add your code
    }

    @Override
    public void onModelMoved(float distanceX, float distanceY) {
        // add your code
    }

    @Override
    public void onModelRotated(float angle) {
        // add your code
    }

    @Override
    public void onModelRescaled(float scale) {
        // add your code
    }
});

Taking a screenshot

Using augmentPlayer.takeScreenshot(ScreenshotTakerCallback callback), will give you a picture of what is in the player, only including the logo on the top left corner. By default, pictures are saved on the public external storage of the device, more specifically, on the Environment.DIRECTORY_PICTURES in a folder called Augment. There’s a method that let you change this, augmentPlayer.setScreenshotsConfig(File parentFolder, String filenamePrefix);; parameters are self explanatory.

augmentPlayer.takeScreenshot(new ScreenshotTakerCallback() {
    @Override
    public void onScreenshotSaved(File picture) {
        // use the picture
    }

    @Override
    public void onError(Throwable throwable) {
        // this will be call if something goes wrong
    }
});

Advanced

We provide a fully working sample ready to be compiled at https://github.com/Augment/Samples

Errors

You can find everything about Augment Player SDK errors in AugmentPlayerException and WebserviceException

Limitations

Due to some dependency issues, Augment Player SDK is only available for armv7a and can NOT run on simulators. Please add this to your application build.gradle file:

android {
    defaultConfig {
        ndk {
            abiFilters "armeabi-v7a"
        }
    }
}

Feedback and Contact

We are always interested in your feedback and suggestions for how we can improve this documentation. Please email us at support@augment.com.

layout: page title: Augment Mobile SDK - Android FAQ permalink: /android-sdk-faq platform: Android —

Android FAQ

What if the `minSdkVersion` of my app is lower than the required by the SDK?

The android framework let you force the use of a library with a higher minSDK by adding this to the Manifest:

<manifest>
  ...
  <uses-sdk tools:overrideLibrary="com.ar.augment" />
  <!-- if you're using RN bridge, use: -->
  <!-- <uses-sdk tools:overrideLibrary="com.ar.augment, com.augment.reactplugin" /> -->
  <application/>
<manifest/>

Then, you must do a manual validation before launching the AR to avoid Runtime Errors:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
  // you may open the AR
}