Konfiguration

TreatmentConsultant akzeptiert eine einzige optionale Prop config, eine tief-partielle Version von TreatmentConsultantConfig. Alles, was Sie nicht angeben, fällt auf sinnvolle Standardwerte zurück, sodass die meisten Integrationen nur eine Handvoll Felder überschreiben müssen.

Lieber per Mausklick? Der Konfigurationsgenerator schreibt eine Ausgangskonfiguration für Sie.

<TreatmentConsultant
  :config="{
    behaviour: { autoAdvance: true },
    text: { cta: { bookHref: `/book-appointment` } },
  }"
/>

Zusammenführung

Die drei Strukturen auf oberster Ebene in TreatmentConsultantConfig werden unterschiedlich zusammengeführt:

Verhalten

Schritte des Assistenten

Der Assistent hat intern 7 Schrittindizes. „Anwendungsart“ wird automatisch übersprungen, wenn die Kundschaft bei der Wunschfarbe „keine“ wählt. „Schnitt“ und „Behandlungen“ lassen sich jeweils über behaviour oben vollständig deaktivieren.

Texte

Alle für Nutzer sichtbaren Texte im Widget befinden sich unter text: Schrittüberschriften, Navigationsbeschriftungen, die Ergebnisansicht, die Zusammenfassung in der Seitenleiste und der abschließende Call-to-Action. Überschreiben Sie nur die Schlüssel, die Sie brauchen. Alles andere fällt auf die englischen Standardwerte zurück. Die vollständige Struktur finden Sie in der TextConfig-Referenz.

Wie Sie das Widget in einer anderen Sprache anzeigen, erfahren Sie unter Sprachen.

Sprachen

Das Widget erkennt und übersetzt nichts von sich aus. Jeder angezeigte Text, einschließlich Optionsbeschriftungen und Farbempfehlungen, stammt aus text und ist standardmäßig Englisch. Um es in einer anderen Sprache anzuzeigen, müssen Sie also diese Texte bereitstellen. Übersetzung ist in jedem Tarif enthalten.

Integrierte Sprachpakete

Das Paket liefert fertige Sprachpakete mit, die alle Texte im Widget übersetzen. Jedes Paket ist ein DeepPartial<TextConfig> und kann daher direkt in text übergeben werden.

Der integrierte Text ist britisches Englisch. Das Paket für amerikanisches Englisch enthält nur die abweichenden Texte: amerikanische Schreibweisen wie color, gray und -ize sowie Salonvokabular wie bangs statt fringe. Verwenden Sie es wie jedes andere Sprachpaket.

Wenn Ihre Website immer nur in einer Sprache angezeigt wird, übergeben Sie das Paket in Ihrer Plugin-Konfiguration:

import { createHairTreatments } from "srcdev-hair-treatments"
import { fr } from "srcdev-hair-treatments/locales/fr"

createHairTreatments({
  licenseKey: "YOUR_LICENSE_KEY",
  text: fr,
})

Ein Sprachpaket lässt Einstellungen weg, die zu Ihrer Website und nicht zu einer Sprache gehören: text.header.brand, text.cta.bookHref und die Symbole in text.results.suitability. Was Sie dafür festlegen, bleibt beim Sprachwechsel erhalten. Um einen Text zu ändern, den das Paket setzt, übernehmen Sie das Paket per Spread und überschreiben Sie darüber:

text: {
  ...fr,
  cta: { ...fr.cta, bookLabel: "Prendre rendez-vous" },
}

Sprache wechseln

Die Plugin-Konfiguration wird einmalig beim Start Ihrer App gelesen und kann daher keinem Sprachumschalter folgen. Behalten Sie Ihre feste Einrichtung (Lizenzschlüssel, Optionen, Theme) im Plugin und übergeben Sie das Sprachpaket über die Prop config der Komponente aus einem computed, das der Sprache Ihrer Website folgt. Die Prop wird über die Plugin-Konfiguration gelegt und aktualisiert sich bei jeder Änderung:

<script setup lang="ts">
import { TreatmentConsultant } from "srcdev-hair-treatments"
import { fr } from "srcdev-hair-treatments/locales/fr"
import { de } from "srcdev-hair-treatments/locales/de"
import { enUS } from "srcdev-hair-treatments/locales/en-US"

const { locale } = useI18n()
const localePacks = { fr, de, "en-US": enUS }
type LocalePackCode = keyof typeof localePacks

const consultantConfig = computed(() => {
  const pack =
    localePacks[locale.value as LocalePackCode] ??
    localePacks[locale.value.split("-")[0] as LocalePackCode]
  return pack ? { text: pack } : {}
})
</script>

<template>
  <TreatmentConsultant :config="consultantConfig" />
</template>

Übergeben Sie über die Prop nur text. Options-Arrays werden vollständig ersetzt, ein dort übergebenes Array würde also die Liste des Plugins ersetzen und entfernte Optionen zurückbringen. Sprachpakete enthalten nie Arrays und lassen sich daher immer gefahrlos so übergeben. Das Beispiel prüft zuerst den genauen Sprachcode, damit ein regionales Paket wie „en-US“ Vorrang hat, und dann nur seinen ersten Teil, sodass „fr“ und „fr-FR“ beide Französisch anzeigen. Eine Sprache ohne Paket, auch „en-GB“, bleibt britisches Englisch.

Der Konfigurationsgenerator schreibt beide Teile für Sie: Wählen Sie unter „Sprachen“ mehr als eine Sprache aus.

Eigene Übersetzungen

Für eine Sprache ohne Paket oder für eigene Formulierungen stellen Sie die Texte selbst bereit, zum Beispiel aus Ihren eigenen i18n-Nachrichten, nach demselben Prop-Muster wie oben. Der Großteil von text besteht aus einfachen Texten, die in der TextConfig-Referenz aufgeführt sind. Ein guter Ausgangspunkt ist, defaultConfig.text oder ein vorhandenes Paket zu kopieren und zu übersetzen. Zwei Bereiche erfordern mehr Sorgfalt: Optionsbeschriftungen und Farbempfehlungen.

Optionsbeschriftungen

Haartypen, Farben, Farbtöne, Behandlungen, Schnitte und die übrigen Optionen werden unter text.options übersetzt, geordnet nach Liste und dann nach Options-ID. Übergeben Sie keine übersetzten Kopien der Options-Arrays:

const consultantConfig = computed(() => ({
  text: {
    options: {
      hairTypes: { straight: { label: t("hair.straight") } },
      treatments: {
        perm: { label: t("perm.label"), description: t("perm.description"), notes: [t("perm.note")] },
      },
      cuts: {
        fringe: { warnings: { coily: { note: t("fringe.coilyNote"), detail: t("fringe.coilyDetail") } } },
      },
    },
  },
}))

Jedes Feld, das Sie angeben, ersetzt den entsprechenden Wert der Option, alles Weggelassene bleibt erhalten. text.options ändert immer nur Formulierungen: Es fügt nie Optionen hinzu, entfernt oder sortiert sie um, und IDs, die nicht in der Liste stehen, werden ignoriert. notes ersetzt die Hinweise einer Behandlung als ganze Liste, während warnings pro Haartyp und pro Feld zusammengeführt wird.

Vollständige Struktur: OptionTextConfig.

Farbempfehlungen

Die Farbempfehlungen in der Ergebnisansicht stammen aus text.recommendations, geordnet nach Naturfarbe und dann nach Wunschfarbe, jeweils mit Methode, Hinweisen und Details. Sie werden wie der Rest von text tief zusammengeführt. Geben Sie beim Übersetzen also jede Kombination an: Alle weggelassenen bleiben auf Englisch. Welche Kombinationen als geeignet bewertet werden, entscheidet das Widget selbst. Nur die Formulierung lässt sich ändern.

Drei weitere Texte vervollständigen die Ergebnisse: recommendationFallback (für jede Kombination ohne eigenen Eintrag), texturedHairNote (ergänzt bei lockigem und krausem Haar) und sameShadeNoteFormat (ergänzt, wenn Natur- und Wunschfarbton übereinstimmen, wobei {shade} für den Namen des Farbtons steht).

Options-Arrays

hairTypes, naturalColours, desiredColours, treatments, applicationTypes, cuts, greyCoverageOptions, shades und naturalShades definieren die auswählbaren Optionen in jedem Schritt. Wenn angegeben, ersetzen sie die Standardwerte vollständig. Eine teilweise Überschreibung ist also nicht möglich, geben Sie die vollständige Liste an. Die jeweilige Struktur finden Sie in der Referenz der Optionstypen.

Um Optionsbeschriftungen zu übersetzen, schreiben Sie diese Arrays nicht neu. Verwenden Sie stattdessen Optionsbeschriftungen, das Ihre gewählten Optionen unverändert lässt.

Modus „Detaillierter Farbtonkatalog“

Erfordert eine Premium-Lizenz. Standardmäßig zeigen Wunschfarbe und Naturfarbe jeweils ihr Raster mit 7 groben Kategorien. Wenn Sie behaviour.dreamColourMode und/oder behaviour.naturalColourMode auf "granular" setzen, wechselt dieser Schritt zu einem Katalog einzelner benannter Farbtöne mit Reitern (config.shades für die Wunschfarbe, config.naturalShades für die Naturfarbe), gruppiert in Reiter, die sich aus den in den Daten vorkommenden Kategorie-IDs ergeben. Die beiden Modi sind voneinander unabhängig.

Bei einer Basic- oder Standard-Lizenz (oder ohne bzw. mit ungültiger Lizenz) wird "granular" stillschweigend als "basic" behandelt, ohne Fehler und ohne gesperrte Elemente oder Upgrade-Hinweise. Derselbe Fallback greift bei einer Premium-Lizenz, wenn der jeweilige Katalog leer ist. Die Auswahl eines Farbtons entspricht für die Eignungsbewertung der Auswahl seiner groben Kategorie. Der konkrete Farbton wird zusätzlich als ConsultationSelections.desiredShade / .naturalShade erfasst. Wie Lizenzstufen durchgesetzt werden, erfahren Sie unter Lizenzierung.

Scrollbare Farbfeldreihe

const config = { behaviour: { swatchLayout: "scroll-tablet" } };

Standardmäßig werden die Farbfeldschritte (Haartyp, Naturfarbe und Wunschfarbe, im einfachen wie im detaillierten Modus) als umbrechendes Raster dargestellt. "scroll-mobile" macht daraus eine einzelne horizontal scrollende, einrastende Reihe, solange die Komponente schmaler als 640px ist. "scroll-tablet" tut dasselbe unterhalb von 1024px. Die nächste Karte ist am Rand der Reihe angeschnitten sichtbar und dient als Hinweis zum Scrollen, und das ausgewählte Farbfeld wird in den sichtbaren Bereich gescrollt, wenn ein Schritt geöffnet oder ein Farbton-Reiter gewechselt wird. Schritte, deren Karten Beschreibungen haben (Anwendungsart, Schnitt, Behandlungen), bleiben immer ein Raster.

Die Breakpoints beziehen sich auf die Breite der Komponente selbst (Container Queries), nicht auf die des Viewports. Eine Instanz in einer schmalen Seitenleiste scrollt also auch auf einem breiten Bildschirm.

Wenn Sie behaviour.swatchLayout setzen, erhält das Wurzelelement eine Klasse swatch-layout-<name>, an der das CSS ansetzt. Um es stattdessen über das Markup zu aktivieren, übergeben Sie diese Klasse selbst:

<TreatmentConsultant style-class-passthrough="swatch-layout-scroll-mobile" />

Wie viele Karten in die sichtbare Reihe passen, steuern Sie mit --swatch-scroll-visible (Standard 2.5 unter 640px und 3.5 ab 640px). Behalten Sie eine ,5 bei, damit immer eine Karte angeschnitten sichtbar ist:

.treatment-consultant {
  --swatch-scroll-visible: 1.5;
}

Der Breakpoint selbst kann keine Custom Property sein, da Bedingungen in Container und Media Queries kein var() akzeptieren. Deshalb wird das Layout über einen Konfigurationswert oder eine Klasse gewählt und nicht über eine CSS-Variable.

Virtuelle Anprobe (experimentell)

Experimentell. Mit der virtuellen Anprobe kann die Kundschaft Wunschfarbtöne in einer Live-Kameraansicht des eigenen Haares ausprobieren. Sie ist standardmäßig deaktiviert: Setzen Sie behaviour.experimentalTryOn auf true, um in jedem Schritt einen Anprobe-Button im Header hinzuzufügen, dazu einen größeren im Schritt „Wunschfarbe“. Solange sie experimentell ist, können sich Aussehen und Funktionsweise in jeder Version ändern.

const config = { behaviour: { experimentalTryOn: true } };

Alles läuft im Browser der Besucherin oder des Besuchers. Das Kamerabild wird auf dem eigenen Gerät verarbeitet und nirgendwohin gesendet, auch nicht an GuideMyHair.

Ein Tippen auf einen Farbton zeigt ihn in der Vorschau und wählt ihn gleichzeitig aus. Die Anprobe schließt sich und kehrt mit dieser Farbe ausgewählt zum Schritt „Wunschfarbe“ zurück. Sie wird als konkreter Farbton in ConsultationSelections.desiredShade erfasst, wenn Ihr Tarif den detaillierten Katalog enthält, andernfalls als grobe Farbe. Die Kundschaft klickt weiterhin selbst auf „Weiter“: Eine Auswahl in der Anprobe bringt den Assistenten nie von sich aus weiter.

Die Anprobe ist in jedem Tarif verfügbar. Ihre Palette zeigt unabhängig vom Tarif immer den vollständigen config.shades-Katalog, als Vorschau auf die Farbtöne, die eine Premium-Lizenz im detaillierten Farbtonkatalog freischaltet. Setzen Sie behaviour.tryOnShowShadeImages auf false, um statt Farbtonfotos einfarbige Farbfelder anzuzeigen.

Sie benötigt eine Modelldatei zur Haarsegmentierung, die das Skript setup:assets in Ihre App kopiert. Alternativ verweisen Sie mit behaviour.tryOnModelPath auf Ihre eigene Kopie. Wenn Ihre Website eine Content-Security-Policy sendet oder den Kamerazugriff blockiert, müssen auch diese Header sie zulassen: siehe Installation: virtuelle Anprobe.

Ihre Texte (Button-Beschriftungen, Beschriftungen der Schieberegler und Meldungen) befinden sich unter text.tryOn und werden wie die übrigen Texte zusammengeführt. Siehe TextConfig-Referenz.

Grauabdeckung

Eine zweite, unabhängige Frage unterhalb der Farbfelder für die Naturfarbe: config.greyCoverageOptions (Standard: Keine / Etwas / Deutlich / Überwiegend grau). Sie wird als ConsultationSelections.greyCoverage erfasst und als eigene Zusammenfassungskarte im Ergebnis angezeigt. Anders als Haartyp, Naturfarbe und Wunschfarbe fließt sie aber nie in die Eignungsmatrix ein und löst nie autoAdvance aus.

Header-Text & der Header-Slot

text.header.brand (ein leerer String blendet ihn aus) und text.header.title legen den integrierten Header über dem Schrittinhalt fest: Marken- bzw. Salonname plus ein dauerhafter Titel, daneben eine aktuelle Fortschrittsanzeige. Um das Markup des Headers vollständig zu ersetzen (eigenes Logo, eigener Fortschrittsbalken), verwenden Sie stattdessen den Scoped Slot #header. Siehe Slot-Referenz.

Standardmäßig reichen der Header und der Hero-Bereich darunter beide von Rand zu Rand des Widgets. Setzen Sie behaviour.fullBleedHeader oder behaviour.fullBleedHero auf false, um einen davon einzurücken.

Events