> For the complete documentation index, see [llms.txt](https://mazingxr.gitbook.io/mazing-world/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mazingxr.gitbook.io/mazing-world/de/apis/augmented-reality-api.md). # 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); } }); }); ```