• Getting Started
  • Install the plugin
    • Android specifics
    • iOS specifics
  • Overview
• A working example
  • Setup
  • Products and catalog
    • Your first catalog
    • Query and load products
  • Visualize
• Full API
  • Prepare Session
    • AugmentPlayer tracking status
    • AugmentPlayer model’s gestures
  • Augment Player’s methods
  • Limitations
• Feedback and Contact
• Android FAQ
  • What if the minSdkVersion of my app is lower than the required by the SDK?

Getting Started

This is the official Augment plugin for react-native, it will allow you to use Augment Mobile SDK on iOS and Android within a react-native App.

Install the plugin

npm install react-native-augment --save
react-native link react-native-augment

Android specifics

(AugmentAndroidSDK: 3.0.0-beta.x)

To enable Augmented reality feature you have to add the following code to the Android Manifest at android/app/src/main/AndroidManifest.xml:

    <uses-permission android:name="android.permission.INTERNET"/>
    <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" />

Also, because of the automatic initialization of the SDK, the credentials must be put in the android/app/src/main/AndroidManifest.xml too:

<application>
  <meta-data
       android:name="@string/augment_sdk_app_id"
       android:value="357fee36746668573ceb2f5957c4869ee1a62a112639bac9b0fae43c7c431692" />
   <meta-data
       android:name="@string/augment_sdk_app_client"
       android:value="80ae1420e164e0440d5329067bcdd953e9fa6c63b75c001c06d169a4f11268c5" />
</application>

and then edit your Project gradle at android/build.gradle to add:

allprojects {
    repositories {
        mavenLocal()
        jcenter()
        maven {
            // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
            url "$rootDir/../node_modules/react-native/android"
        }
        // Add these line
        maven { url  "https://dl.bintray.com/augment/augment" }
        maven { url 'https://jitpack.io' }
    }
}

Remember that the mobile AugmentSDK will work only on real devices, be sure to have a real device connected when starting the app with react-native run-android

iOS specifics

With iOS 10 and higher you need to add the “Privacy - Camera Usage Description” key to the Info.plist file of your project.

Add the following code:

<key>NSCameraUsageDescription</key>
<string>We need to access your Camera to show you Augmented reality</string>

Then you should import the AugmentSDK into your project using CocoaPods by adding to your Podfile:

# omit this line if you already use it
use_frameworks!

pod 'AugmentPlayerSDK', '4.0.17'

Note: Remember that the mobile AugmentSDK will work only on real devices, so you may need to start the project with XCode instead of react-native run-ios so you can choose the device.

Overview

Thanks to the Augment react-native plugin you will now have access to the AugmentPlayerSDK class in your javascript and AugmentPlayer component. With this plugin you can query if a product is available and then display it on an Augmented reality view.

A working example

This example covers how to implement a full Augmented reality session that uses Augment React-native Plugin

Setup

You need to import the component and init your instance.

import { AugmentPlayerSDK, AugmentPlayer } from 'react-native-augment';

// These are demo credentials linked to the demo catalog below
AugmentPlayerSDK.init({
    id:  "357fee36746668573ceb2f5957c4869ee1a62a112639bac9b0fae43c7c431692",
    key: "80ae1420e164e0440d5329067bcdd953e9fa6c63b75c001c06d169a4f11268c5"  
});

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

EAN are optional, pass an empty string for the demo

Query and load products

At any time after the AugmentPlayerSDK.init you can query Augment for a product.

In order to query a product: create a new product JSON object with an identifier, name, brand and optional ean and pass it to the AugmentPlayerSDK.checkIfModelDoesExistForUserProduct method.

If the product exists in Augment database, checkIfModelDoesExistForUserProduct will return an AugmentProduct instance within its success callback or null if this product does not exist. The error callback will be called only if there is an error.

// Product JSON object
var productToSearch = {
    identifier: "84",
    brand: "Whirlpool",
    name: "Fridge",
    ean: ""
};

AugmentPlayerSDK.checkIfModelDoesExistForUserProduct(productToSearch)
.then(function (augmentProduct) {
    // Check if the Augment API found a corresponding Product
    if (!augmentProduct) {
        alert('Product not found');
        return;
    }

    // We have the augmentProduct here :)
    console.log(augmentProduct);

})
.catch(function (error) {
    // Error is a JSON object {error: string}
    alert(error.error);
});

An AugmentProduct is a JSON object:

type AugmentProduct = {
    identifier: string,
    brand: string,
    name: string,
    ean?: string
}

Visualize

To start the Augment View use the view component <AugmentPlayer onPlayerReady={} loaderCallback={} />

The onPlayerReady props will give you the AugmentPlayer instance, on this object you have access to the player’s methods like .recenterProducts, .addProduct
and with the loaderCallback props you can handle the loading progress of the 3D model

class Example extends Component {

    loader(loaderStatus) {
        // Product and AR general loading
        // This is here to allow you to give feedback to your user
        // {progress: int, show: bool}
        console.log(loaderStatus);
        this.setState({
            loaderShow: loaderStatus.show,
            loaderText: "Loading " + loaderStatus.progress + "%"
        });
    }

    business(player, error) {
        if (error) {
            console.error(error);
            return;
        }

        this.playerInstance = player;
        player.addProduct(productToSearch)
        .then(() => {
            console.log("The product has been added to the ARView");
        })
        .catch((error) => {
            console.error(error);
        });
    }

    render() {
        return (
            <AugmentPlayer style={styles.augmentPlayer}
                onPlayerReady={this.business.bind(this)}
                loaderCallback={this.loader.bind(this)}
            />
        );
    }
}

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

Full API

Prepare Session

AugmentPlayerSDK.init: (credentials: AugmentPlayerSDKInit) => void;

Init the Augment Plugin, it needs to be called before anything else.

AugmentPlayerSDK.checkIfModelDoesExistForUserProduct: (product: AugmentProduct) => Promise <Error, ?AugmentProduct>;

Query Augment servers to check if a given product exists, returns the product (or null if not found) in the promise.

<AugmentPlayer ... />

Start the Augmented View and create the Augment Player

AugmentPlayer tracking status

When AR is available, the AugmentPlayer will notify a tracking status to let you know what’s happening internally. Here are the all the possible AugmentPlayer.Constants.TrackingStatus values:

initializing, //The underlying AR system is getting set-up.
normal, //The AR tracking is working properly and the discovery mode is active.
notAvailable, //The AR tracking is not available; try reseting the player.
limitedExcessiveMotion, //Tracking is limited due to a excessive motion of the camera.
limitedInsufficientFeatures, //Tracking is limited due to a lack of features (illumination or details) visible to the camera.
featuresDetected*, //Some features has been detected. Invite the user to explorer a little more to detected a plane to place the product.
planeDetected*, //Your camera is pointing right over a surface. Invite the user to tap to place the product on the plane.
error, //Something went wrong with the player, this message will tell you what.

* = only on iOS

You can track these by passing onTrackingStatusChanged:

    render() {
        return <AugmentPlayer onTrackingStatusChanged={this.onTrackingStatusChanged.bind(this)} ... />
    }

    onTrackingStatusChanged = ({ status, message }) => {
        switch (status) {
          case AugmentPlayer.Constants.TrackingStatus.error:
            console.log('An error occurred during tracking: ' + message);
            break;
          // ...
          default:
            console.error('Unrecognized status ' + status);
        }
    }

type TrackingStatusChangedEvent = {
    status: integer,
    message?: string
}

AugmentPlayer model’s gestures

The AugmentPlayer will also notify the model’s gestures:

AugmentPlayer.Constants.ModelGesture.added
AugmentPlayer.Constants.ModelGesture.translated
AugmentPlayer.Constants.ModelGesture.rotated

You just have to use pass onModelGesture with props:

    render() {
        return <AugmentPlayer onModelGesture={this.onModelGesture.bind(this)} ... />
    }

    onModelGesture = (event) => {
        switch (event.gesture) {
        case AugmentPlayer.Constants.ModelGesture.added:
            console.log('Model with uuid ' + event.model_uuid + " has been placed");
            break;
        default:
            break;
        }
    }

The received event contains both a gesture and the corresponding model3D’s UUID.

type ModelGestureEvent = {
    gesture: integer,
    model_uuid: string
}

Augment Player’s methods

The AugmentPlayer component expose a few methods to interact with Augmented Reality. You can save a reference to the current player component this way:

<AugmentPlayer ref={ref => { this.augmentPlayer = ref; }} ... />

this.augmentPlayer.addProduct: (product: AugmentProduct) => Promise<Error, Void>;

Add a product to the Augmented View (player), it could be a product you got back from the API, or it could be a product you want to search for (in that case the error management will be handled by the Augmented View).

this.augmentPlayer.recenterProducts: () => void;

Allows the user to recenter products in the Augmented View (player).

this.augmentPlayer.takeScreenshot: () => Promise<Error, String>;

Allows the user to save a screenshot; it returns the absolute path of the saved image.

Limitations

Due to some dependency constraints, Augment Plugin will only works on real devices

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
}