Installation

Paket installieren

npm install srcdev-hair-treatments

Styles importieren

In dist/ werden zwei Stylesheets mitgeliefert: das eigene CSS der Komponente und ein Satz Farb-Tokens, die sie ausliest. Importieren Sie beide einmalig und global im Einstiegspunkt Ihrer App oder in Ihrem globalen CSS:

@import "srcdev-hair-treatments/dist/style.css";
@import "srcdev-hair-treatments/dist/tokens.css";

tokens.css definiert die Farbverläufe, die die Komponente verwendet: --brand-00 bis --brand-10 sowie --accent-* (der ausgewählte Zustand), --success-*, --warning-* und --error-*. Lassen Sie diesen Import weg und geben Sie eigene Werte an, wenn das Widget von Anfang an zu Ihrer Marke passen soll. Siehe Gestaltung.

Bilder kopieren

Farbfelder für Haartyp und Haarfarbe können echte Fotos zeigen. Das Paket liefert einen vollständigen Satz Standardbilder mit, diese müssen aber aus dem public/-Verzeichnis Ihrer eigenen App ausgeliefert und nicht aus node_modules gelesen werden. Fügen Sie Ihrer package.json ein Skript hinzu und führen Sie es nach der Installation einmal aus:

"setup:assets": "cp -r node_modules/srcdev-hair-treatments/public/. public/"

Kopieren Sie den ganzen Ordner, nicht nur die Bilder. Er enthält die Bilder in public/images/treatment-consultant/ und das Modell für die virtuelle Anprobe in public/models/treatment-consultant/. Wenn Sie nur public/images/ kopieren, fehlt das Modell.

Binden Sie es in einen postinstall-Hook ein, damit es bei jedem npm install synchron bleibt und bei einem Paket-Update neue oder geänderte Bilder übernimmt:

"postinstall": "npm run setup:assets"

Unter Gestaltung → Bilder erfahren Sie, wie Sie diese pro Option durch eigene Fotos ersetzen.

Plugin registrieren

createHairTreatments() ist ein Vue-Plugin, das jeder TreatmentConsultant-Instanz in Ihrer App eine Standard-config bereitstellt. Die Übergabe einer Konfiguration ist hier optional. Sie können sie auch direkt als Prop pro Instanz übergeben (siehe Konfiguration). Außerdem kann es Ihren Lizenzschlüssel enthalten, damit Sie ihn nicht für jede Instanz wiederholen müssen. Siehe Lizenzierung.

import { createApp } from "vue"
import { createHairTreatments } from "srcdev-hair-treatments"
import App from "./App.vue"

const app = createApp(App)
app.use(createHairTreatments())
app.mount("#app")

Komponente verwenden

<template>
  <TreatmentConsultant @complete="onComplete" />
</template>

<script setup lang="ts">
import { TreatmentConsultant } from "srcdev-hair-treatments"
import type { ConsultationSelections } from "srcdev-hair-treatments"

function onComplete(selections: ConsultationSelections) {
  console.log(selections)
}
<\/script>

Nuxt

Registrieren Sie das Plugin unter app/plugins/ (nicht in einem plugins/-Verzeichnis auf oberster Ebene: Das Standard-srcDir von Nuxt 4 ist app/, und ein Plugin außerhalb davon wird stillschweigend nicht registriert):

// app/plugins/hair-treatments.ts
import { createHairTreatments } from "srcdev-hair-treatments"

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(createHairTreatments())
})

Fügen Sie beide Stylesheets dem css-Array in nuxt.config.ts hinzu und umschließen Sie die Komponente selbst mit <ClientOnly>, denn TreatmentConsultant ist nicht SSR-sicher. Alle Details unter SSR & ClientOnly.

Virtuelle Anprobe: Sicherheits-Header

Nur nötig, wenn Sie behaviour.experimentalTryOn aktivieren (siehe Konfiguration). Die Anprobe lädt ihre MediaPipe-Laufzeit von cdn.jsdelivr.net und fragt dann nach der Kamera der Besucherin oder des Besuchers. Wenn Ihre Website eine Content-Security-Policy sendet, erlauben Sie sowohl das Skript als auch die Datei, die es herunterlädt:

// Content-Security-Policy: allow the MediaPipe wasm loader script and wasm binary
"script-src": ["'self'", "'wasm-unsafe-eval'", "https://cdn.jsdelivr.net" /* ...your other sources */],
"connect-src": ["'self'", "https://cdn.jsdelivr.net" /* ...your other sources */],

Manche Sicherheitskonfigurationen verweigern die Kamera auch grundsätzlich mit einer Permissions-Policy von camera=(), was der Standard in nuxt-security ist. Erlauben Sie sie für Ihre eigenen Seiten:

// nuxt.config.ts, with nuxt-security
security: {
  headers: {
    permissionsPolicy: {
      camera: ["self"],
    },
  },
},

Wenn Sie die Laufzeitdateien über behaviour.tryOnWasmBaseUrl selbst hosten, erlauben Sie anstelle von jsDelivr Ihren eigenen Host.

Reines HTML ohne Build-Schritt

Keine Vue-App, kein Bundler? Ein separates dist/embed.js-Bundle liefert alles Nötige mit, Vue inklusive. So kann eine reine HTML-Seite die Beratung mit einem <div>, einem Stylesheet-Link und einem <script>-Tag einbinden. Beim Laden über ein CDN wie jsDelivr ist die URL an eine Paketversion gebunden, es gibt also keinen Cache zu invalidieren, wenn eine neue Version erscheint. Erhöhen Sie einfach die Version in der URL, wenn Sie sie möchten.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/srcdev-hair-treatments@1.5.1/dist/embed-style.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/srcdev-hair-treatments@1.5.1/dist/tokens.css" />

<div data-hair-treatments data-license-key="YOUR_LICENSE_KEY"></div>

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/srcdev-hair-treatments@1.5.1/dist/embed.js"
></script>

Jedes Element auf der Seite, das [data-hair-treatments] entspricht, wird automatisch eingebunden, sobald das Skript geladen ist. Sonst müssen Sie nichts schreiben. Die oben genannte Version 1.5.1 wird aus der installierten Abhängigkeit dieser Website gelesen und ist daher immer aktuell. Übernehmen Sie sie unverändert oder ersetzen Sie sie durch die Version, die Sie selbst festgelegt haben. Woher der Lizenzschlüssel kommt, erfahren Sie unter Lizenzierung.

Übergeben Sie die Konfiguration pro Instanz mit einem JSON-codierten data-config-Attribut. Welche Struktur es akzeptiert, steht unter Konfiguration:

<div
  data-hair-treatments
  data-license-key="YOUR_LICENSE_KEY"
  data-config="{"text": {"heading": "Find your perfect colour"}}"
></div>

Hier gibt es keine Vue-App, an die sich @complete/@change anhängen könnten. Das Embed-Bundle löst sie daher stattdessen als native CustomEvents auf dem Mount-Element aus. Hören Sie mit addEventListener darauf:

document
  .querySelector("[data-hair-treatments]")
  .addEventListener("hair-treatments:complete", (event) => {
    console.log(event.detail) // ConsultationSelections
  })

Sie aktivieren die Anprobe in einem Embed? Ihr Standardwert behaviour.tryOnModelPath erwartet die von setup:assets kopierte Modelldatei, aber eine Embed-Website hat keinen Build-Schritt, um es auszuführen. Verweisen Sie in data-config stattdessen auf die Kopie bei jsDelivr, gebunden an dieselbe Version wie das Skript:

<div
  data-hair-treatments
  data-config='{"behaviour":{"experimentalTryOn":true,"tryOnModelPath":"https://cdn.jsdelivr.net/npm/srcdev-hair-treatments@1.5.1/public/models/treatment-consultant/hair_segmenter.tflite"}}'
></div>