Augment Mobile SDK - Cordova

Getting Started

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

Install the plugin

cordova plugin add augment-cordova

iOS specifics

Get Augment SDK via Cocoapods

Right after the installation you need to install our iOS SDK with Cocoapods.

Go to your Cordova directory and cd platforms/ios then run pod install

If you need more information about Cocoapods, check the official website: https://cocoapods.org/

Android specifics

Ask for camera permissions

You are responsible to ask for the Camera permission, it has to be done before starting the Augment Player otherwise it will fail to start.

Overview

Thanks to the Augment Cordova plugin you will now have access to the AugmentCordova global in your javascript. 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 Cordova Plugin

Setup

The following code needs to be started after Cordova has been fully initialized (after app.onDeviceReady)

You need to init your instance.

// These are demo credentials linked to the demo catalog below
AugmentCordova.init({
    id:  "357fee36746668573ceb2f5957c4869ee1a62a112639bac9b0fae43c7c431692",
    key: "80ae1420e164e0440d5329067bcdd953e9fa6c63b75c001c06d169a4f11268c5",
    vuforia: "ATQqCM7/////AAAAGXLs+GRi0UwXh0X+/qQL49dbZGym8kKo+iRtgC95tbJoCWjXXZihDl5pzxoca2JxLcYxBJ2pIeIE4dNcK0etMeb1746L7lq6vSFen43cS7P1P/HXjwHtUouV5Xus2U0F7WHUTKuO629jKFO13fBQczuY52UJcSEhsu9jHPMaupo5CpqQT3TFTQjlhzHhVXiVMEqq7RI+Edwh8TCSfGAbNRdbIELTfK+8YDYqwEHDbp62mFrs68YnCEQZDrpcLyC8WzFCVZtnUq3Cj3YBUfQ6gNnENYiuLf06gAAF/FcaF65VYveGRBbp3hpkqolX28bxPiUYNVknCSFXICPHciVntxF+rcHW5rrX7Cg/IVFGdNRF"
});

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

IdentifierBrandName
81SamsungTV
82LenovoYoga 900
83SamsungWasher
84WhirlpoolFridge
86FINLANDEKCouch
89Restoration HardwareChair
90Restoration HardwareTable
91TargetChair
92TargetOutdoor Chair
93Bed BathTable
94Bed BathCurtains
95Sun LoungerFrontgate
96BallardTable
97AdidasShoe
98NintendoSwitch

EAN are optional, pass an empty string for the demo

Query and load products

At any time after the AugmentCordova.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 AugmentCordova.checkIfModelDoesExistForUserProduct method.

If the product exists in Augment database, checkIfModelDoesExistForUserProduct will return an AugmentCordovaProduct 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: ""
};

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

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

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

An AugmentCordovaProduct is a JSON object:

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

Visualize

To start the Augment View use AugmentCordova.startPlayer

The success callback of startPlayer will give you a AugmentCordovaPlayer instance, on this object you have access to the player’s methods like .recenterProducts, .shareScreenshot and more.

AugmentCordova.startPlayer(function (player) {
    // 1- `product` could be an AugmentCordovaProduct that you got with `.checkIfModelDoesExistForUserProduct` so you know it will show up because the query has been done and succeed
    // 2- `product` could be a Product JSON object, the query will be done for you and the error management will be handled by the player (Augmented View)
    player.addProduct(product, function (success) {
        // The product will be visible, let's dance :)
    }, function (error) {
        // Error is a JSON object {error: string}
        alert(error.error);
    });
}, function (error) {
    // Error is a JSON object {error: string}
    alert(error.error);
});

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

Of course you can finish/close the Augment Session with player.stop

Full API

Prepare Session

AugmentCordova.init: (credentials: AugmentCordovaInit) => void;

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

AugmentCordova.checkIfModelDoesExistForUserProduct: (product: AugmentCordovaProduct, productCallback: AugmentCordovaProductCallback, errorCallback: AugmentCordovaErrorCallback) => void;

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

AugmentCordova.startPlayer: (playerCallback: AugmentCordovaPlayerCallback, errorCallback: AugmentCordovaErrorCallback) => void;

Start the Augmented View and create the Augment Player

Augment Player

player.addProduct: (product: AugmentCordovaProduct) => 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).

player.recenterProducts: () => void;

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

player.showAlertMessage: (title: string, message: string, buttonText: string) => void;

Allows you to show a message to your user on top of the Augmented View.

player.stop: (successCallback: AugmentCordovaSuccessCallback) => void;

Stop the player and get back to your application.

Advanced

UIElements

On the init method you can pass with your credentials a uiElements JSON array of JSON object.
This object will allow you to define buttons associated to your own javascript business logic. These buttons will be added to the Augmented View at the bottom.

A valid button definition would be:

{
    title: "My Button",
    code: function (player) {
        // My valid javascript code to execute
        // you have a valid player instance here
    },
    // Optional
    color: "#FF0000",           // Title color #XXXXXX format string
    borderSize: "3",            // Border size in point, has to be a string
    borderRadius: "5",          // Border radius in point, has to be a string
    borderColor: "#00FFFF",     // Border color #XXXXXX format string
    fontSize: "22",             // Font size in point, has to be a string
    backgroundColor: "#0000FF"  // Background color #XXXXXX format string
}

When the user will click on these button the code will be ran on your website, in you method you will be given a valid player instance.

For example you can add a Share button, or a Center product button, but also a Buy button …

var uiElements = [
    {
        title: "Share",
        code: function (player) {
            player.shareScreenshot();
        }
    },
    {
        title: "Alert",
        code: function (player) {
            player.showAlertMessage("My alert", "My message", "yay!");
        }
    },
    {
        title: "Buy",
        code: function (player) {
            // This method comes from your business logic
            addProductToCart(productToSearch);
            // Then close the player
            player.stop(function (success) {
                // Not much to do :)
            });
        }
    },
    {
        title: "Center",
        code: function (player) {
            player.recenterProducts();
        }
    }
];

// Then
AugmentCordova.init({
    id:  "357fee36746668573ceb2f5957c4869ee1a62a112639bac9b0fae43c7c431692",
    key: "80ae1420e164e0440d5329067bcdd953e9fa6c63b75c001c06d169a4f11268c5",
    vuforia: "ATQqCM7/////AAAAGXLs+GRi0UwXh0X+/qQL49dbZGym8kKo+iRtgC95tbJoCWjXXZihDl5pzxoca2JxLcYxBJ2pIeIE4dNcK0etMeb1746L7lq6vSFen43cS7P1P/HXjwHtUouV5Xus2U0F7WHUTKuO629jKFO13fBQczuY52UJcSEhsu9jHPMaupo5CpqQT3TFTQjlhzHhVXiVMEqq7RI+Edwh8TCSfGAbNRdbIELTfK+8YDYqwEHDbp62mFrs68YnCEQZDrpcLyC8WzFCVZtnUq3Cj3YBUfQ6gNnENYiuLf06gAAF/FcaF65VYveGRBbp3hpkqolX28bxPiUYNVknCSFXICPHciVntxF+rcHW5rrX7Cg/IVFGdNRF",
    uiElements: uiElements
});

Limitations

Due to some dependency issues, 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.