Market --- 3D-Produktvorschau (GLB-Modelle)

Ein Market-Produkt kann optional ein 3D-Modell enthalten. Ihr Shop liest dessen öffentliche URL aus der externen Katalog-API und rendert einen interaktiven Viewer: Kunden drehen per Ziehen und zoomen per Scrollen oder Pinch. Ohne Modell (oder ohne WebGL im Browser) zeigt der Shop das normale Produktbild.

Verfügbar ab Mailoo 1.34.13.

Modell im Dashboard hochladen

1. Öffnen Sie Dashboard → Projekte → Ihr Projekt → Market-Integration → Produkte und bearbeiten Sie ein Produkt.
2. Suchen Sie auf dem Tab Allgemein den Block 3D-Modell.
3. Ziehen Sie eine .glb-Datei in die Zone (oder klicken Sie darauf und wählen Sie die Datei). Während des Uploads wird ein Fortschrittsbalken angezeigt.
4. Klicken Sie auf Veröffentlichen (oder Als Entwurf speichern), um das Modell am Produkt zu speichern.

Nach dem Upload zeigt der Block Dateiname und Media-ID, einen Link Öffnen (öffentliche Modell-URL) und Entfernen. Eine weitere Datei ersetzt das Modell; Entfernen löst es beim nächsten Speichern vom Produkt.

Dateianforderungen

• Format: nur .glb --- binäres glTF 2.0. Der Dateiinhalt wird geprüft (glTF-Header, Version 2); umbenannte Dateien anderer Formate werden abgelehnt. .gltf mit externen Texturen, .obj, .fbx, .usdz werden nicht akzeptiert --- zuerst nach GLB konvertieren (z. B. Blender → Export glTF 2.0, Format glTF Binary).
• Größe: bis 50 MB pro Datei (unabhängig vom Bildlimit). Für mobile Kunden sind wenige MB mit komprimierten Texturen ideal.
• Isolation: Ein Modell gehört zur Market-Integration, in die es hochgeladen wurde, und kann nur Produkten desselben Projekts und derselben Integration zugeordnet werden.

Externe URL (veraltet)

Solange kein Modell hochgeladen ist, bietet der Block zusätzlich ein Feld für eine externe Modell-URL (veraltet) --- einen öffentlichen https-Link zu .glb / .gltf. Das Feld ist veraltet; bevorzugen Sie den Upload. Ein hochgeladenes Modell hat immer Vorrang.

Was der Shop erhält

Produkte aus der externen Katalog-API (siehe market-catalog-external-api{.interpreted-text role="doc"}) enthalten zwei Felder:

• model3dUrl --- die effektive Modell-URL oder null. Für ein hochgeladenes Modell ist es die öffentliche Mailoo-URL {baseUrl}/api/v1/public/models/{mediaId}, sonst die veraltete externe URL.
• model3dMediaId --- ID des hochgeladenen GLB oder null.

{
  "id": "mailoo_dev_market_demo_product",
  "attributes": { "name": "Mailoo Demo Widget" },
  "model3dUrl": "https://api.mailoo.app/api/v1/public/models/yblrqe9jgdkv1a3g5913cptv",
  "model3dMediaId": "yblrqe9jgdkv1a3g5913cptv"
}

Der öffentliche Modell-Endpunkt benötigt keinen API-Schlüssel; der Browser lädt ihn direkt. Er streamt model/gltf-binary mit CORS *, Cross-Origin-Resource-Policy: cross-origin und einem unveränderlichen Cache von einem Jahr (beim Ersetzen ändert sich die URL).

3D-Viewer auf Ihrer Website

Jeder glTF-Viewer funktioniert. Die Referenzimplementierung in der Integrator-Demo nutzt Google <model-viewer> <https://modelviewer.dev/>, bei Bedarf nachgeladen:

'use client'
import { createElement, useEffect, useState } from 'react'

const MODEL_VIEWER_SRC =
  'https://ajax.googleapis.com/ajax/libs/model-viewer/4.0.0/model-viewer.min.js'

export function Product3DViewer({ modelUrl, fallbackImageUrl, alt }: {
  modelUrl?: string | null
  fallbackImageUrl?: string | null
  alt: string
}) {
  const [ready, setReady] = useState(false)
  useEffect(() => {
    if (!modelUrl || customElements.get('model-viewer')) return setReady(!!modelUrl)
    const s = document.createElement('script')
    s.type = 'module'
    s.src = MODEL_VIEWER_SRC
    s.onload = () => setReady(true)
    document.head.appendChild(s)
  }, [modelUrl])

  if (!modelUrl || !ready) {
    return fallbackImageUrl ? <img src={fallbackImageUrl} alt={alt} /> : null
  }
  return createElement('model-viewer', {
    src: modelUrl,
    alt,
    poster: fallbackImageUrl ?? undefined,
    'camera-controls': '',   // drag to rotate, scroll/pinch to zoom
    'auto-rotate': '',
    'touch-action': 'pan-y', // keep vertical page scroll on mobile
    loading: 'lazy',
    'shadow-intensity': '1',
    style: { width: '100%', aspectRatio: '1 / 1' },
  })
}

Verwendung mit einem Produkt aus der Katalog-API:

<Product3DViewer
  modelUrl={product.model3dUrl}
  fallbackImageUrl={product.previewImageUrl}
  alt={product.attributes.name}
/>

Die vollständige Demo-Komponente (tests/integrator-demo/src/components/product-3d-viewer.tsx) ergänzt:

• Lazy Loading --- die Bibliothek (~1 MB) wird erst geladen, wenn der Viewer sichtbar wird (IntersectionObserver).
• Fallback auf das 2D-Bild, wenn model3dUrl leer ist, WebGL fehlt oder das Modell nicht lädt (error-Event).

Fehlerbehebung

• „Only .glb (binary glTF 2.0) files are supported" / „File is not a valid GLB" --- als glTF Binary (.glb), glTF 2.0 exportieren.
• „Model too large" --- Datei größer als 50 MB; Polygone reduzieren oder Texturen komprimieren (z. B. gltf-transform optimize).
• Shop zeigt nur das Bild --- prüfen, ob das Produkt veröffentlicht ist, model3dUrl in der API-Antwort nicht null ist und der Browser WebGL unterstützt.