👨‍💻Augmented Reality API

With this API, you can integrate Augmented Reality on all your configurators and 3d viewers even without using our Mazing Viewer.

Overview

Many web viewer or configurator implementations are based on WebGL technologies. The most common frameworks used are ThreeJS and BabylonJS, but also others like Playcanvas or Verge3D are used often.

Every framework offers possibilities to handle AR with little to no guidance, this leads to 3D developers copy/paste bad solutions available on the Internet and trying to hack them into their used frameworks, without knowing what they are doing in terms of AR.

If the main customers phone is suitable to this hack implementation, the developer seems lucky first, but what is with the other 5000 AR-capable devices available? What is with Apple's Vision Pro or Metas Quest 3 in terms of AR headsets? What is with non supporting browsers like the Instagram or Facebook App browser? Can such a non-AR expert solution be failure-proof?

Here our Mazing AR Api is coming in, which is tested on all major applications and browsers and handles AR on all capable devices worldwide. We also use this API for our in-house viewer implementation, so you can be sure that it is always state-of-the-art tech inside.

Features

  • Support for Quest 3 and Vision Pro

  • Support for all major phone brands iOS 13+, iPadOS 13+ or Android with ARCore 1.9+ required

  • Browser breakout function for unsupported browsers

  • QR Code generation library included for PC URLs

  • Status Events to handle loaders, dialogs, and modals

  • Translations for German, English, French and Czech

Integration Example

Step 1 - Request API access

You will receive a customer and a product uid to query our API. Click on the link below and book a meeting.

Step 2 - Integrate Script

Add the AR API script in the head part of your webshop or homepage.

<head> 
 ... 
<script type="text/javascript" src="https://cdn.mazing.link/mzg-ar-api.js"></script>
</head>

Step 3 - Authenticate with the API

On page load, right after integrating the mzg-ar-api.js you have to initialize the API with your given credentials.


    mazingArApi.initialize({
        auth: {
            customerUid: 'GiVeN_Uid',
            productUid: 'GivEn_ProducT-UID',
        }
    })

Step 4 - Extract your scene as GLB/GLT Blob Url

In all major WebGL frameworks you can export your current visible scene as GLB/GLTF into blob URLs. As an example with ThreeJS this works with the GLTFExporter or in BabylonJS with the Babylon GLTFExporter, in Verge3D you can use the Export GLB Puzzle.

After export, most of the time you get a blob object. In Javascript, you can easily create a blob URL from it: 

arButton.onclick = () => {

    const blobURL = URL.createObjectURL( exportedBlob );
    ...
}

The constructed blobURL is exactly what we need in the next step.

Step 5 - Call the AR API

After you generate the blobURL you can start AR with a simple snippet. This will disable object zooming, so models will be true to size and not zoomable, and take your blobURL as a model to render.

arButton.onclick = () => {

    ...

    mazingArApi.startAR({
        glb: blobURL,
        arOptions: {
            disableZoom: true
        },
        callback: (arStatus) => {
            console.error('TEST AR STATUS', arStatus);
        }
    });

};

Step 6 - Enjoy your AR experience

QR Generation

If as an example the ar-status returns, false/pc-detected-show-qr as you can see below , this means that the solution was tried to be used on a computer. The usual flow is that a QR code is shown, the customer then scans the QR code with their phone and gets redirected to the solution on a capable device. We offer the option to generate a QR code for your needs, so you don't need to embed any QR code handling in addition to the event handling. You just need to create a container, to render the QR code inside:

<div id="qr-container"></div>

<script>
    mazingArApi.generateQR({
            url: 'https://your-viewer-url.com',
            container: '#qr-container',
            width: 500,
            height: 500,
            dotsColor: '#ff0000',
    });
</script>

API Details

General Options

glb You can specify the 3d model that you want to render. It can either be a blob URL or a server URL. If you are using server URLs be sure that your server supports Cors requests. usdz (optional) Usually, usdz files are auto-generated of the glb, nonetheless, you can specify a custom usdz/reality file URL in this API which can be used. You can specify it as a blob or server URL (blob).

environment Currently, we support the following environments 'neutral' and 'standard'. Neutral is the default hdr.

callback The callback gives you information about the returned ar-status, the return code is of the format, this can be used to hide/show loading modals and more:

{
    type: string,
    success: boolean,
}

success/types

  • false/auth-missing - means that you have missed the authentication part beforehand

  • false/pc-detected-show-qr - means that ar cannot be activated, because device is a PC

  • false/unsupported-browser - ar cannot be activated, because the browser is not supported (optional: because we offer a breakout handling for unsupported browsers)

  • false/ar-not-supported - the device is unable to start AR at all

  • false/ar-failed - the devices tried to start AR but it failed

  • true/ar-will-be-started - all preparations have finished, you can for ex. disable loading screens

  • true/ar-started - everything OK, the AR session was started

AR Options

disableZoom Normally 3Dmodels can be zoomed, if you set this variable to 'true', models are unable to be zoomed and will only be rendered true-to-size. default = zoom allowed.

wallPlacement 3D models can also be placed on walls, like paintings or hanging objects. If you set this variable to 'true', you will enable this mode. default = false no wall tracking

callToAction You can specify a call to action that is visible while being inside Augmented Reality. A call to action consists of the following parts:

  • title: string = a short title string (ex. New Offer)

  • subtitle:string = a little bit longer subtitle (ex. Super table with 4 chairs discount)

  • button:string = caption for the button (ex. Buy Now)

  • callback:string = link that opens after button click (ex. https://link-to-offer.com)

Here is a full example of how a call could look like

    document.getElementById('mazing-ar-external-scene-btn').addEventListener('click', () => {
        startLoader();
        mazingArApi.startAR({
            glb: 'https://mazing-static-files.s3.eu-central-1.amazonaws.com/meetingbox.glb',
            environment: 'neutral',
            arOptions: {
                disableZoom: true,
                wallPlacement: false,
                callToAction: {
                    title: 'ABC',
                    subtitle: 'DEFGHJIJ',
                    button: 'BUY NOW',
                    callback: 'https://mazing.link/mutelabs/meetingbox'
                }
            },
            callback: (arStatus) => {
                console.error('TEST AR STATUS', arStatus);
                hideLoader(arStatus);
            }
        });
    });

PreviousFor eCommerce

Last updated