Augmented Reality API

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

PreviousFor eCommerce

Last updated 10 months ago

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

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.log('TEST AR STATUS', arStatus);
        }
    });

};

Step 6 - Enjoy your AR experience

QR Generation, PC->Mobile Handling

We offer a solution that automatically generates a popup with a QR code for PC users, so mobile phone users can scan the QR code and come to your solution. You only need to specify a qr.url in the form https://urltosolution.com/?autoStart=true. This is the URL the scanning mobile user will be redirected to.

Here is how you can specify it in code:

arButton.onclick = () => {

    ...

    mazingArApi.startAR({
        glb: blobURL,
        qr: {
           url: yourQRCodeURL preferrably with a ?autoStart=true parameter
        }
        callback: (arStatus) => {
            console.log('TEST AR STATUS', arStatus);
        }
    });

};

Important Autostart Handling

Regardless of your solution if you want to automatically autostart the AR function after the scan of your QR code you need to call mazingArApi.startAR() with the autoStartRequest Parameter set to true. Autostart of AR in Android is only allowed with an in-between step, but this one is automatically handled for you.

mazingArApi.startAR({
    qr: {
        url: ``,
    },
    autoStartRequest: autoStart, // autoStart should be true if scanned by mobile

Example Autostart

This is a concrete example of how this two features could look like in combination:


mazingArApi.startAR({
    qr: {
        url: `https://mazing.link/?pr=eXOCkwXrOZ&autoStart=true`,
    },
    autoStartRequest: new URLSearchParams(window.location.search).get('autoStart') === 'true',
    ....
}

Alternative: Manual QR Generation

If you don't want to use the Mazing built-in QR Code popup and compatibility solution, we offer a QR creation library in our AR API.

<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 10 months ago

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.

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.

Augmented Reality AgencyMazing

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 or in BabylonJS with the , in Verge3D you can use the .

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.log('TEST AR STATUS', arStatus);
        }
    });

};

Step 6 - Enjoy your AR experience

QR Generation, PC->Mobile Handling

Here is how you can specify it in code:

arButton.onclick = () => {

    ...

    mazingArApi.startAR({
        glb: blobURL,
        qr: {
           url: yourQRCodeURL preferrably with a ?autoStart=true parameter
        }
        callback: (arStatus) => {
            console.log('TEST AR STATUS', arStatus);
        }
    });

};

Important Autostart Handling

mazingArApi.startAR({
    qr: {
        url: ``,
    },
    autoStartRequest: autoStart, // autoStart should be true if scanned by mobile

As an example, if you start our Mazing link with the autoStart Parameter, the QR popup is shown instantly or AR is started, or the in-between step is shown on Android phones or AR is started on iOS phones.

Example Autostart

This is a concrete example of how this two features could look like in combination:


mazingArApi.startAR({
    qr: {
        url: `https://mazing.link/?pr=eXOCkwXrOZ&autoStart=true`,
    },
    autoStartRequest: new URLSearchParams(window.location.search).get('autoStart') === 'true',
    ....
}

Alternative: Manual QR Generation

If you don't want to use the Mazing built-in QR Code popup and compatibility solution, we offer a QR creation library in our AR API.

If as an example the ar-status returns, false/pc-detected-show-qr as you can see , 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

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);
            }
        });
    });

Overview

Features

Integration Example

Step 1 - Request API access

Step 2 - Integrate Script

Step 3 - Authenticate with the API

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

Step 5 - Call the AR API

Step 6 - Enjoy your AR experience

QR Generation, PC->Mobile Handling

Automatic QR Code Popup

Important Autostart Handling

Example Autostart

Alternative: Manual QR Generation

API Details

General Options

success/types

AR Options

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

Overview

Features

Integration Example

Step 1 - Request API access

Step 2 - Integrate Script

Step 3 - Authenticate with the API

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

Step 5 - Call the AR API

Step 6 - Enjoy your AR experience

QR Generation, PC->Mobile Handling

Automatic QR Code Popup

Important Autostart Handling

Example Autostart

Alternative: Manual QR Generation

API Details

General Options

success/types

AR Options

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