<viewer-3dvue> é um Web Component nativo. Sem dependências, sem framework necessário. Funciona em qualquer lugar onde possa colar HTML — uma secção Liquid, theme.liquid ou um template de produto.
<!-- Em <head> ou antes de </body> --> <script src="https://cdn.jsdelivr.net/gh/3dvue/api@v4/viewer-3dvue-min.js"></script>
<viewer-3dvue name="monViewer" src="https://app.3dvue.fr/view?p=AB01-CD02" ></viewer-3dvue> <!-- É tudo. -->
Um Web Component nativo — sem React, Vue nem bundler necessário. Funciona em qualquer ambiente que aceite HTML.
Adicione o script ao seu theme.liquid, dentro de <head> ou mesmo antes de </body>. Uma única inclusão cobre todas as suas páginas de produto.
src no componente <viewer-3dvue> é o URL específico do seu configurador — fornecido pela 3DVue ao entregar o seu projeto.
<script src="https://cdn.jsdelivr.net/gh/3dvue/api@v4/viewer-3dvue-min.js"></script>
Cole a tag <viewer-3dvue> onde quiser mostrar o configurador — na sua secção Liquid de produto, um bloco personalizado ou uma secção dedicada. São necessários dois atributos: name (identificador único) e src (URL do seu configurador).
name é usado para apontar para este visor a partir de botões HTML ou da API JS. Use um identificador único por página se tiver múltiplos visores.
<!-- Atributos necessários --> <viewer-3dvue name="monViewer" src="https://app.3dvue.fr/view?p=AB01-CD02" ></viewer-3dvue> <!-- Opcional: ativa logs de consola --> <viewer-3dvue name="monViewer" src="https://app.3dvue.fr/view?p=AB01-CD02" debug ></viewer-3dvue>
Adicione atributos viewer-3dvue nos seus botões ou selects existentes para ativar mudanças de material. Sem JavaScript para escrever — o componente escuta automaticamente os eventos click e change.
<!-- Botão que muda o tecido ao clicar --> <button viewer-3dvue="monViewer" viewer-3dvue-clic="setMaterial" viewer-3dvue-meshs-materials='{"1":"0n","2":"1a"}' > Azul meia-noite </button> <!-- Select que muda a cor --> <select viewer-3dvue="monViewer" viewer-3dvue-change="setMaterial" viewer-3dvue-mesh="2,4" > <option value="0n">Vermelho</option> <option value="1a">Azul</option> <option value="2b">Verde</option> </select>
O componente escuta automaticamente os eventos click e change em qualquer elemento que tenha os atributos corretos. Ideal para ligar com os seus swatches Shopify existentes.
<button viewer-3dvue="monViewer" viewer-3dvue-clic="setMaterial" viewer-3dvue-meshs-materials='{"1":"0n","3":"2b","5":"1c"}' > Tema madeira natural </button> // {"meshIndex": "materialId"} // O índice 0 está reservado — começar em 1
viewer-3dvue-mesh.<select viewer-3dvue="monViewer" viewer-3dvue-change="setMaterial" viewer-3dvue-mesh="2,4" > <option value="0n">Vermelho</option> <option value="1a">Azul</option> </select> // viewer-3dvue-mesh="2,4" // aplica-se à malha 2 E à malha 4
Quando precisa de controlo programático — carregamento dinâmico de modelos, captura de imagem, exportação SVG. Todos os métodos verificam que o visor está pronto antes de executar.
const viewer = document.querySelector('viewer-3dvue[name="monViewer"]'); // Todos os métodos verificam que o visor está carregado (LOAD_COMPLETE) // Se não estiver pronto → aviso na consola, chamada ignorada
// No objeto 0 (por omissão) viewer.setMaterial({ "1": "0n", "3": "2b" }); // Num objeto específico (multi-segmento) viewer.setMaterial({ "1": "1a" }, 1); // setMaterial(materialList, objectIndex = 0)
// Carregar um novo modelo (substitui o atual) viewer.loadModel("AB01-CD02"); // Adicionar um segmento ao modelo existente viewer.addModel("EF03"); viewer.addModel("EF03-GH04"); // Eliminar um segmento pelo seu índice viewer.removeModel(1); // ⚠ Não é possível eliminar o último segmento restante
viewer.captureToBase64(); viewer.addEventListener("onCaptureBase64Complete", (e) => { const { base64, error } = e.detail; if (error) { console.error(error); return; } // base64 = "data:image/png;base64,..." document.querySelector("#preview").src = base64; });
// Devolve a câmara à sua posição inicial viewer.resetCamera(); // Pausa manual (poupa GPU) viewer.pauseRenderer(); viewer.startRenderer(); // ℹ Estes métodos são geridos automaticamente // quando o componente sai/entra no viewport
A API SVG permite-lhe adicionar texto e imagens diretamente sobre o produto 3D através de zonas de colocação definidas no modelo. Usa-se para produtos personalizáveis — marcação, gravação de texto, carregamento de logo do cliente.
| Método | Descrição |
|---|---|
addSVGText(text, opts) |
Adiciona texto a uma zona de colocação. Opções: fill, fontFamily, selectable |
addSVGImage(source, opts) |
Adiciona uma imagem (File ou ArrayBuffer) a uma zona de colocação. Sem cópia via Transferable Objects. |
setSVGElementParam(param, value, id) |
Modifica um parâmetro de um elemento SVG existente. id=null aponta para o elemento selecionado. |
exportSVG() |
Gera o ficheiro SVG do produto configurado — prova pronta para imprimir. |
// 1. Adicionar texto sobre o produto viewer.addSVGText("O meu texto", { fill: "#ffffff", fontFamily: "Arial", dropzone: "dropzone001", selectable: true }); // 2. Carregar logo a partir de um input de ficheiro const file = input.files[0]; await viewer.addSVGImage(file, { dropzone: "dropzone001" }); // 3. Exportar a prova SVG viewer.exportSVG(); viewer.addEventListener("onSVGExportComplete", (e) => { const { path, error } = e.detail; // path = URL do ficheiro SVG gerado });
Referência API, atributos HTML, eventos, exemplos Liquid do Shopify. Tudo está documentado e mantido atualizado.
Ver documentaçãoSem sistema de tickets automatizado. Fala diretamente com o Matthieu, o programador que concebeu a API. Resposta em 24 horas.
Marcar uma chamadaExperimente o configurador em condições reais antes de o integrar. Veja exatamente o que os seus clientes verão na sua loja.
Ver demoVocê gere o código do lado Shopify, nós tratamos de todo o resto — modelização, materiais, configuração. Em 30 minutos, mostramos-lhe o que podemos fazer com o seu catálogo.