Documentación para desarrolladores

Inicio rápido #

Un script y una etiqueta. No hay una segunda forma de hacerlo, así que aquí no se puede elegir mal.

<script src="https://3d-lion.com/viewer/loader.js" defer></script>

<glb-viewer
  share-token="prj_your_token"
  style="display: block; width: 100%; height: min(78svh, 760px)">
</glb-viewer>

<script
  src="https://3d-lion.com/viewer/loader.js"
  data-token="prj_your_token" defer></script>

Listo. Las zonas de color, el tour de cámara y los controles ya funcionan — no escribes nada de JavaScript.

El token del proyecto (prj_…) está en la página del proyecto, dentro de tu panel. No hace falta nada más: tu dominio se verifica en el servidor.

Casos habituales #

Lo que más se pide se activa con un solo atributo. Copia la línea dentro de la etiqueta.

<glb-viewer
  share-token="prj_your_token"
  tour="scroll">
</glb-viewer>

<section style="height: 240vh">
  <glb-viewer share-token="prj_your_token"></glb-viewer>
</section>

.model-stage {
  height: var(--glb-stage-free, 100svh);
}

@media (min-width: 1024px) {
  .model-stage {
    height: min(var(--glb-stage-free, 100svh), 760px);
  }
}

.model-stage {
  --glb-stage-top: 72px;
}

Los marcados como «en vivo» en la tabla de arriba se pueden cambiar en cualquier momento con setAttribute — el visor aplica el cambio sin recargar el modelo.

Atributos #

Defínelos en el HTML o cámbialos en tiempo real — todo lo marcado como «en vivo» se aplica al instante.

Los que no llevan marca deciden QUÉ es el visor, no cómo se comporta: el catálogo llega del servidor ya cortado por scenario, la forma del panel queda fijada antes de mostrar el modelo, y un idioma es otro documento. Cambia uno de esos y el visor se vuelve a abrir en una dirección nueva, en lugar de ignorarte en silencio.

API de JavaScript #

El elemento expone exactamente un objeto, congelado, con ocho espacios de nombres. Todo lo demás dentro del visor sigue siendo privado, así que tu integración sobrevive a las actualizaciones.

const viewer = document.querySelector('glb-viewer');
const { colors, options, tour, camera, animations } = await viewer.ready;

// Every call is a promise: the model runs in its own frame and answers from there.
await colors.getZones();                 // [{ id, label, group, palette, defaultColor, hasView }]
await colors.selectZone('seats');        // flies to the view the author saved for the zone
await colors.selectZone(null);           // visitor left the zone — flies back out
await colors.setColor('seats', '#d8c9a6');
await colors.setColor('seats', '#d8c9a6', { focus: false });  // recolour, camera stays put
await colors.setColors({ seats: '#d8c9a6' });  // whole colourway, camera untouched
await colors.reset();

await options.getGroups();               // the non-colour choices the project carries
await options.select(groupId, optionId);

await tour.play(); await tour.togglePause(); await tour.stop();
await tour.setSpeed(2.4);
await tour.setResumePrompt(false);       // you draw your own resume control

await camera.home();                     // back to the opening view
await camera.setAutoRotate(true);
await camera.setMode('orbit');           // 'orbit' | 'free' | 'walk'
await camera.setLimits({ minDistance: 2, maxPolarAngle: 1.5 });

await animations.getEntries();           // [{ id, label }]
await animations.play(id); await animations.stop(id);

Con await viewer.ready no hay nada que comprobar ni con qué competir: devuelve la misma API cuando la pidas, antes del arranque del visor o mucho después.

Todos los espacios de nombres están siempre, y cada llamada devuelve una promesa, porque la respuesta llega desde el propio marco del visor. Pide a un proyecto sin zonas que recoloree una y la promesa se rechaza: nunca devuelve undefined en silencio.

Un panel a tono con tu sitio #

El panel del comprador se pinta con tu color y con ningún otro. Estar a tono con cualquier sitio es para lo que sirve la transparencia — y esa transparencia tiene un suelo calculado, porque el panel debe sostener su propio texto a 4.5:1 sobre aquello en lo que se apoya.

const { panel } = await viewer.ready;

panel.setSkin({
  surface: '#faf7f2',        // your colour — null follows the side your page is on
  surfaceOpacity: 0.7,       // a request: the floor below may raise it
  blur: 30,                  // 0…40 px, dropped once nothing shows through anyway
  accent: '#c07a3e',         // the chosen option and the primary button
  radius: 14,                // 0…32 px
  side: 'right',             // 'right' | 'left' | 'below'
});

// What the panel is standing on. Buys density, never colour.
panel.setBackdrop('#faf7f2');
panel.setBackdrop('#101010', { live: true });  // video, slideshow — counts as nothing said
panel.setBackdrop(null);                       // take the answer back

panel.setOptionDisplay('tiles');  // 'flat' | 'tiles'
panel.getSkin();

La opacidad que fijas es una petición, no un resultado. Sin un fondo declarado, la legibilidad hay que garantizarla sobre cualquier fondo que exista — así que el panel se asienta más denso de lo pedido. Declara el fondo y la petición se cumple.

setBackdrop compra densidad y nunca color. El panel en tu página y el panel en la de otro son del mismo color; conocer el fondo solo cambia cuánto se ve a través. A pantalla completa responde la escena: tu página ya no está detrás del panel allí.

Declara surface de forma explícita. El visor está en un marco propio, y nada se hereda a través del borde de un marco: lee su propio documento, no la página de debajo, así que no puede adivinar si tu sitio es claro u oscuro.

El acento nunca se adapta. Un botón que cambió de color por una fotografía de la página es un error a ojos de cualquier marca.

Leer el estado #

Cada espacio de nombres responde a getState() con su instantánea actual. Úsalo para valores que cambian demasiado a menudo como para difundirlos — el progreso del tour, la posición de la cámara — o para ponerte al día si te suscribiste tarde.

const { colors, options, tour, camera, animations } = await viewer.ready;

await colors.getState();      // { zones, colors, selectedZoneId }
await options.getGroups();    // [{ id, label, options: [{ id, chosen, unmet }] }]
await tour.getState();        // { isPlaying, isPaused, progress, hasWaypoints }
await camera.getState();      // { position: [x, y, z], target: [x, y, z] }
await animations.getState();  // { entries: [{ id, label, status }] }

Eventos #

El visor te cuenta lo que ha pasado, así que nunca lo consultas en bucle. Todo llega como un evento DOM corriente en el elemento: addEventListener, y los datos están en e.detail.

const viewer = document.querySelector('glb-viewer');

viewer.addEventListener('glb-viewer:zones', (e) => e.detail.zones);
viewer.addEventListener('glb-viewer:zone', (e) => e.detail.zoneId);   // null = deselected
viewer.addEventListener('glb-viewer:color', (e) => e.detail);          // { zoneId, hex }
viewer.addEventListener('glb-viewer:colors', (e) => e.detail.colors);
viewer.addEventListener('glb-viewer:options', (e) => e.detail.selection);
viewer.addEventListener('glb-viewer:tour:status', (e) => e.detail.isPlaying);
viewer.addEventListener('glb-viewer:build', (e) => e.detail.url);
viewer.addEventListener('glb-viewer:error', (e) => e.detail.code);

Dominios y acceso #

Tu clave está ligada a tus dominios, y la página del visor a esa misma lista a nivel de navegador. Un fragmento copiado en el sitio de otro no funciona allí.

POST /api/v1/viewer/auth/verify
403  { "error": "Domain not allowed" }   // the origin is not on the allowlist

GET /api/v1/viewer/prj_your_token
403  { "code": "PRIVATE_PROJECT" }       // the project is not shared publicly
404  { "code": "NOT_PUBLISHED" }         // the project has never been published

La lista de dominios la mantenemos nosotros: dinos qué direcciones añadir y la actualizamos. Todavía no hay gestión autónoma en el panel.

Qué guarda el widget #

El widget funciona en tu página, así que es a ti a quien pregunta el visitante. Aquí está todo lo que escribimos en su dispositivo y guardamos en el nuestro, con las mismas palabras que puedes llevar a tu política.

Esto describe cómo funciona el widget; no es un documento legal. Acuerda la redacción de tu política con tu propio abogado, sobre todo si tienes visitantes en la UE, donde escribir un identificador exige consentimiento.

React, Vue y los demás #

No hay paquetes por framework ni hacen falta: <glb-viewer> es un elemento normal, así que funciona en cualquier sitio sin envoltorios.

import { useEffect, useRef } from 'react';

export function Configurator({ token }) {
  const ref = useRef(null);

  useEffect(() => {
    let cancelled = false;
    ref.current.ready.then(async ({ colors }) => {
      if (!cancelled) await colors.setColors({ seats: '#d8c9a6' });
    });
    return () => { cancelled = true; };
  }, []);

  return (
    <glb-viewer
      ref={ref}
      share-token={token}
      style={{ display: 'block', width: '100%', height: 600 }}
    />
  );
}

<template>
  <glb-viewer
    ref="viewer"
    :share-token="token"
    style="display: block; width: 100%; height: 600px"
  />
</template>

<script setup>
import { onMounted, ref } from 'vue';

const viewer = ref(null);

onMounted(async () => {
  const { colors } = await viewer.value.ready;
  await colors.setColors({ seats: '#d8c9a6' });
});
</script>

En Vue, añade glb-viewer a isCustomElement (vue.compilerOptions.isCustomElement en Nuxt) para que el compilador deje de buscar un componente con ese nombre.

Errores #

Cada error lleva un code estable — construye tu lógica sobre él. El texto message está escrito para personas y puede cambiar.

viewer.addEventListener('glb-viewer:error', ({ detail }) => {
  if (detail.code === 'WEBGL_NOT_SUPPORTED') showStaticGallery();
  else if (detail.code === 'PROJECT_NOT_FOUND') hideSection();
  else reportToMonitoring(detail.code, detail.message);
});

TypeScript #

El paquete incluye declaraciones escritas a mano para toda la superficie pública: el elemento, la API y los datos de cada evento están tipados, sin que nada interno se filtre a tu compilación.

/// <reference types="@glb-viewer/cdn" />

const viewer = document.querySelector('glb-viewer')!;  // GLBViewerElement
const { colors } = await viewer.ready;                 // GLBViewerApi
await colors.setColor('seats', '#d8c9a6');