# Augmented Reality API ## **Übersicht** Viele **Web-Viewer** oder **Konfiguratoren** basieren auf **WebGL-Technologien**.\ Die am häufigsten verwendeten Frameworks sind **ThreeJS** und **BabylonJS**, aber auch andere wie **PlayCanvas** oder **Verge3D** werden oft genutzt. Jedes dieser Frameworks bietet Möglichkeiten, **AR (Augmented Reality)** zu implementieren – allerdings meist mit wenig Anleitung. Das führt dazu, dass 3D-Entwickler häufig **fehlerhafte Lösungen aus dem Internet kopieren** und versuchen, diese in ihre Frameworks zu integrieren, ohne ein tiefes Verständnis von AR zu haben. Wenn das Smartphone des Hauptkunden zufällig mit dieser „Hack“-Lösung funktioniert, scheint zunächst alles gut – aber was ist mit den **tausenden anderen AR-fähigen Geräten**?\ Was ist mit **Apple Vision Pro** oder **Meta Quest 3**?\ Was ist mit **nicht unterstützten Browsern**, wie dem Instagram- oder Facebook-In-App-Browser? Kann eine solche Lösung ohne AR-Expertise wirklich **zuverlässig** sein? 👉 Genau hier kommt unsere **Mazing AR API** ins Spiel:\ Sie ist auf allen wichtigen Geräten und Browsern getestet und ermöglicht AR auf **allen kompatiblen Geräten weltweit**.\ Wir nutzen diese API auch in unserem eigenen Viewer – somit kannst du sicher sein, dass immer **State-of-the-Art-Technologie** eingesetzt wird. ## **Features** * Unterstützung für **Quest 3** und **Vision Pro** * Unterstützung für alle gängigen Smartphones (**iOS 13+**, **iPadOS 13+**, **Android mit ARCore 1.9+**) * **Browser-Breakout-Funktion** für nicht unterstützte Browser * Integrierte **QR-Code-Generierung** für Desktop-Nutzung * **Status-Events** für Loader, Dialoge und Modals * Übersetzungen für **Deutsch, Englisch, Französisch und Tschechisch**

Android AR in Action

iOS AR in Action

Vision Pro in Action

Browser Breakout

## **Integrationsbeispiel** ### **Schritt 1 – API-Zugang anfordern** Du erhältst eine **Customer UID** und eine **Product UID**, um die API zu nutzen.\ Klicke auf den untenstehenden Link und buche ein Meeting. {% embed url="" %} ### **Schritt 2 – Skript integrieren** Füge das **AR API-Skript** in den **``-Bereich** deiner Website ein: ``` ... ``` ### **Schritt 3 – API authentifizieren** Nach dem Laden der Seite und der Integration von **`mzg-ar-api.js`** musst du die API mit deinen Zugangsdaten initialisieren: ``` mazingArApi.initialize({ auth: { customerUid: 'GiVeN_Uid', productUid: 'GivEn_ProducT-UID', } }) ``` ### **Schritt 4 – Szene als GLB/GLTF Blob-URL exportieren** In den meisten WebGL-Frameworks kannst du deine Szene als **GLB/GLTF** exportieren. Beispiele: * **ThreeJS** → GLTFExporter * **BabylonJS** → Babylon GLTFExporter * **Verge3D** → Export GLB Puzzle Nach dem Export erhältst du meist ein **Blob-Objekt**. Daraus kannst du in JavaScript eine **Blob-URL** erzeugen: 
arButton.onclick = () => {

    const blobURL = URL.createObjectURL( exportedBlob );
    ...
}
Diese **blobURL** wird im nächsten Schritt benötigt. ### **Schritt 5 – AR API aufrufen** Mit der erzeugten **blobURL** kannst du AR starten: ``` arButton.onclick = () => { ... mazingArApi.startAR({ glb: blobURL, arOptions: { disableZoom: true }, callback: (arStatus) => { console.log('TEST AR STATUS', arStatus); } }); }; ``` ### **Schritt 6 – AR erleben** Genieße deine **AR-Erfahrung** 🚀 ## **QR-Generierung & Desktop-zu-Mobile Handling** ### **Automatisches QR-Code-Popup** Wir bieten eine Lösung, die automatisch ein **QR-Code-Popup** für Desktop-Nutzer generiert. * Nutzer scannen den Code mit ihrem Smartphone * Weiterleitung zur mobilen AR-Erfahrung Du musst lediglich eine **QR-URL** angeben:

QR Code popup example

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); } }); }; ``` ### **Wichtige Autostart-Behandlung** Unabhängig von deiner Lösung gilt: Wenn du die **AR-Funktion automatisch nach dem Scannen eines QR-Codes starten** möchtest, musst du **`mazingArApi.startAR()`** mit dem Parameter **`autoStartRequest` auf `true`** aufrufen. Der automatische Start von AR ist auf **Android** nur mit einem Zwischenschritt erlaubt – dieser wird jedoch **automatisch für dich gehandhabt**. ``` mazingArApi.startAR({ qr: { url: ``, }, autoStartRequest: autoStart, // autoStart should be true if scanned by mobile ``` Als Beispiel: Wenn du unseren Mazing-Link\ `https://mazing.link/eXOCkwXrOZ&autoStart=true`\ mit dem Parameter **`autoStart`** startest, wird entweder direkt das **QR-Popup angezeigt**, **AR gestartet** oder – auf Android-Geräten – der notwendige **Zwischenschritt eingeblendet**, während auf iOS direkt AR gestartet wird.

Double confirmation needed for Android

### **Beispiel Autostart** Dies ist ein konkretes Beispiel, wie diese beiden Features kombiniert aussehen können: ``` mazingArApi.startAR({ qr: { url: `https://mazing.link/?pr=eXOCkwXrOZ&autoStart=true`, }, autoStartRequest: new URLSearchParams(window.location.search).get('autoStart') === 'true', .... } ``` ### **Alternative: Manuelle QR-Code-Generierung** Wenn du das integrierte **Mazing-QR-Code-Popup** und die **Kompatibilitätslösung** nicht verwenden möchtest, stellen wir eine **QR-Code-Generierungsbibliothek** in unserer AR API bereit. Wenn z. B. der **AR-Status** `false/pc-detected-show-qr` zurückgibt, bedeutet das, dass die Lösung auf einem **Desktop-Gerät** aufgerufen wurde.\ Der übliche Ablauf ist dann, dass ein **QR-Code angezeigt wird**, den der Nutzer mit seinem Smartphone scannt, um zur AR-Erfahrung weitergeleitet zu werden. Wir bieten dir die Möglichkeit, einen **QR-Code selbst zu generieren**, sodass du keine zusätzliche QR-Code-Logik implementieren musst. Du musst lediglich einen Container erstellen, in dem der QR-Code gerendert wird: 
<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** ### **Allgemeine Optionen** #### **glb** Hier kannst du das **3D-Modell** angeben, das gerendert werden soll.\ Es kann entweder eine **Blob-URL** oder eine **Server-URL** sein.\ Wenn du eine Server-URL verwendest, stelle sicher, dass dein Server **CORS-Anfragen unterstützt**. *** #### **usdz (optional)** Normalerweise werden **USDZ-Dateien automatisch aus dem GLB generiert**.\ Du kannst jedoch auch eine eigene **USDZ/Reality-Datei-URL** angeben.\ Diese kann ebenfalls als **Blob- oder Server-URL** bereitgestellt werden. *** #### **environment** Aktuell werden folgende Umgebungen unterstützt: **`neutral`** und **`standard`**.\ \&#xNAN;**`neutral`** ist das Standard-HDR. *** #### **callback** Der Callback liefert Informationen über den **AR-Status** zurück.\ Das Rückgabeformat sieht wie folgt aus und kann z. B. verwendet werden, um **Loader oder Modals zu steuern**: ``` { type: string, success: boolean, } ``` ### **Status / Typen** #### **Fehlerfälle** * `false/auth-missing` → Authentifizierung fehlt * `false/pc-detected-show-qr` → AR kann nicht gestartet werden, da Gerät ein PC ist * `false/unsupported-browser` → Browser wird nicht unterstützt * `false/ar-not-supported` → Gerät unterstützt AR nicht * `false/ar-failed` → AR-Start ist fehlgeschlagen #### **Erfolgsfälle** * `true/ar-will-be-started` → Vorbereitung abgeschlossen * `true/ar-started` → AR wurde erfolgreich gestartet ## **AR-Optionen** #### **disableZoom** 3D-Modelle können standardmäßig gezoomt werden.\ Wenn du diesen Wert auf **`true`** setzt, wird der Zoom deaktiviert und das Modell wird **maßstabsgetreu dargestellt**.\ Standard: Zoom aktiviert. #### **wallPlacement** 3D-Modelle können auch an **Wänden platziert** werden (z. B. Bilder oder hängende Objekte).\ Wenn du diesen Wert auf **`true`** setzt, wird dieser Modus aktiviert.\ Standard: deaktiviert. **callToAction** Du kannst eine **Call-to-Action** definieren, die innerhalb der **Augmented Reality** angezeigt wird. Eine CTA besteht aus folgenden Bestandteilen: * **title**: kurzer Titel (z. B. „Neues Angebot“) * **subtitle**: längerer Beschreibungstext (z. B. „Tisch mit 4 Stühlen im Angebot“) * **button**: Button-Beschriftung (z. B. „Jetzt kaufen“) * **callback**: Link, der nach Klick geöffnet wird (z. B. `https://link-to-offer.com`) ### Hier ist ein vollständiges Beispiel, wie ein solcher Call aussehen kann: ``` 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); } }); }); ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://mazingxr.gitbook.io/mazing-world/de/apis/augmented-reality-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.