Wie binde ich den Konfigurator auf meiner Webseite oder meinem Shop ein?

Voraussetzungen

• Sie haben einen Konfigurator fertig erstellt und veröffentlicht.

Einbindung

Sie möchten den Konfigurator natürlich in Ihrer Webseite oder Ihrem Shop nutzen.

• Klicken Sie in der linken Seitenleiste auf "Optionen", dann auf "Einbetten"
• Ihnen werden die Möglichkeiten gezeigt:
  • Die technische Einbindung: web component(empfohlen), IFrame oder Link
  • Wollen Sie mit einer definierten Konfiguration starten? (=Inspiration)
  • Wollen Sie den Konfigurator selbst nutzen oder einer Ihrer Händler?
  • In welcher Sprache soll der Konfigurator angezeigt werden?
• Wenn Sie Ihre Auswahl getroffen haben, wird Ihnen rechts der Code angezeigt, den Sie in Ihrer Webseite einfügen müssen.

Im folgenden besprechen wir Detail und Vor- und Nachteile der einzelnen Möglichkeiten:

Verwendung als Web Component (empfohlen)

Der K3 kann direkt als HTML-Element <k3-view> auf jeder beliebigen Seite verwendet werden. Dadurch lässt sich der Konfigurator vollständig ins Layout integrieren – ohne Cross-Origin-Einschränkungen oder visuelle Brüche.

Zur Einbindung genügt ein einfaches HTML-Tag:

<k3-view app="mein-app-code"></k3-view>

Alternativ kann auch ein Inspirations-Code statt eines app-Attributs verwendet werden:

<k3-view code="inspirations-code"></k3-view>

Falls Sie ihre Seite mit einem dynamischen Inspirationscode aufrufen wollen, z.B. als https://mein-unternehmen.de/konfigurator?code=ZTRIZTIUZ, dann fügen Sie direkt unter der Web Component noch folgenden Code ein:

<script>
document.addEventListener("DOMContentLoaded", () => {
  const el = document.querySelector("k3-view");
  const url = new URL(window.location.href);
  const code = url.searchParams.get("code");

  if (el && code) {
    el.setAttribute("code", code);
    el.removeAttribute("app");
  }
});
</script>

Alle zusätzlichen Attribute, die sonst in der Konfiguratorl-URL, können dem Tag übergeben werden (z. B. lang, dealer, etc.)

Damit das HTML-Element zur Verfügung steht, muss das K3 JavaScript geladen werden.

<script type="module" src="https://k3.objectcode.de/app/index.js"></script>

info

In Erweiterungen wie Veranda muss ein anderes Script genutzt werden - schauen Sie in der Einbettungshilfe nach.

Vorteile:

• Optimale Einbettung in Ihre Seite, kein Medienbruch.
• Volle SEO-Relevanz und Tracking-Hoheit.
• Der Nutzer bleibt auf Ihrer Seite.
• Die Adresse des Konfigurators ist nicht sichtbar.

Nachteil:

• Keine

Höhe des Konfigurators

Der Konfigurator sollte den Bildschirm möglichst vollständig ausfüllen. Ist er zu niedrig, muss der Nutzer scrollen und gerät dabei in Konflikt mit der 3D-Darstellung – das erschwert die Bedienung erheblich.

Die gewünschte Höhe ist meist der Bildschirm abzüglich des Seitenheaders. Die Umsetzung hängt von der Einbindungsart ab:

Web Component

Umgeben Sie die Web Component mit einem <div>, dem Sie die Höhe per CSS zuweisen:

<div style="height: calc(100vh - 100px)">
  <k3-view app="mein-app-code"></k3-view>
</div>

IFrame

Sie können die Höhe direkt am IFrame-Element setzen:

<iframe
  id="k3"
  frameborder="0"
  title="Object Code - iFrame"
  width="100%"
  allow="fullscreen"
  src="https://k3.objectcode.de/app/?app=..."
  style="border:none;overflow:hidden;height: calc(100vh - 80px);"
>
</iframe>

Alternativ können Sie die Höhe einem umgebenden Element per CSS geben:

height: calc(100vh - 80px);

100vh ist die Bildschirmhöhe, der zweite Wert die Höhe Ihres Seitenheaders – passen Sie diesen an.

caution

In manchen Browsern sind die Leerzeichen rund um das - in calc() entscheidend – ohne sie wird die Höhe nicht korrekt berechnet.

Einbindung per IFrame

tip

Ein IFrame ist die technische Möglichkeit, eine Webseite innerhalb einer anderen anzuzeigen.

Sie können auf einer Seite Ihres Shops/Ihrer Webpräsenz den Konfigurator anzeigen. Dazu können Sie eine beliebige Seite auswählen oder eine spezielle Seite neu anlegen, z.B. /konfigurator.

Auf der Seite fügen Sie dann den Code ein, der unter Optionen im Tab Einbetten als IFrame angezeigt wird. Das können Sie in Ihrem Web-Editor normalerweise mit einem generischen HTML-Element tun. Der Code sieht etwa so aus:

<iframe id="k3"
    frameBorder="0"
    title="Object Code - iFrame"
    width="100%"
    height="100%"
    allow="fullscreen"
    src="https://k3.objectcode.de/app/?app=2d01a48d-85a4-4f8e-938f-3208b4bd70b9"
    style="border:none;overflow:hidden;">
</iframe>

Die einzelnen Zeilen bedeuten folgendes:

• <iframe>: Ist der technische Befehl zum Anzeigen einer anderen Webseite.
• frameBorder="0": Es soll kein Rahmen um den Konfigurator gezeigt werden.
• title="Object Code - iFrame": Ist optional - der Titel wird nicht angezeigt.
• width="100%": Der Konfigurator nimmt die gesamte verfügbare Breite ein.
• height="100%": Der Konfigurator nimmt die gesamte verfügbare Höhe ein.
• allow="fullscreen": Der Konfigurator darf sich im Vollbild-Modus zeigen.
• src=...": Das ist die eigentliche Adresse der Konfiguratorseite
• style="border:none;overflow:hidden": Es wird kein Rahmen gezeigt (neuere Browser). Und alles, was zu groß zum Anzeigen ist, wird versteckt.

Achten Sie darauf, dass die Höhe korrekt gesetzt ist.

Kontrollieren Sie nach der Einbindung den Pagespeed-Index der Seite. Ein 3D-Konfigurator lädt naturgemäß eine Weile - das beeinflusst die Performance-Messung.

Vorteile:

• Der Nutzer bleibt auf Ihrer Seite.
• Die Adresse des Konfigurators ist nicht sichtbar.

Nachteil:

• Die Anbindung ist technisch ein wenig aufwändiger.
• Die Ladezeit wird Ihrer Webseite angelastet.

Einbindung als Link

Natürlich können Sie auf Ihrer Seite (in Ihrem Shop) einfach auf den Konfigurator verlinken. Dazu setzen Sie einfach einen Link auf die Adresse der Live-Version.

Der Weg zurück zu Ihrem Shop funktioniert über die Abschluss-Aktionen: Im Konfigurator gibt es die Knöpfe, um die Konfiguration bei Ihnen per Mail anzufragen oder in den Warenkorb zu legen. In letzterem Fall landet der Nutzer wieder in Ihrem Shop.

Ob Sie den Konfigurator in einem neuen Tab öffnen wollen oder ob er Ihre Webseite ersetzen soll, können Sie frei wählen. Ihr Web-Editor wird dazu Optionen anbieten.

Vorteile:

• die Einbindung ist einfach
• die Nutzung ist - besonders auch mobil - optimal, da der Konfigurator die gesamte Seite nutzen kann und keine Störungen beim Scroll-Verhalten auftreten.

Nachteil:

• der Nutzer verlässt gefühlt Ihre Seite
• die Adresse des Konfigurators wird in der Adresszeile sichtbar

Lade-Animation

Wenn der Konfigurator per web component oder IFrame in eine Seite eingebettet ist, sendet er Ereignisse, wenn das Laden begonnen und beendet wird.

Dazu muss die umgebende Seite auf sog. Events des IFrame lauschen (wie bei der Shop-Anbindung):

window.addEventListener("message", function (event) {
      if(event.data.type == "K3FullyLoaded"){
          console.log("Received message: " + event.data.code);
          // hier den Event bearbeiten. Z.B. ein Bild über den Konfigrator-Iframe blenden.
      }
  }, false);

Die Phasen sind dabei:

• Zunächst wird die App selbst geladen. Während der Zeit wird vom K3 selbst eine Lade-Animation gezeigt.
• Jetzt wird der Event K3AppLoaded gesendet.
• Nun beginnt der K3, alle Daten zu laden, den Konfigurator, ggf. die Inspiration sowie alle Modelle und Bilder.
• Wenn das vollständig beendet ist, wird der Event K3FullyLoaded gesendet.

Änderungen mitverfolgen

Der Konfigurator meldet auch jede Änderung, die der Nutzer vornimmt, an die einbettende Seite. Damit können Sie das Verhalten Ihrer Nutzer auswerten, etwa in Google Analytics oder einem Tag Manager.

Die Events sind eingeschaltet, solange Sie sie nicht abschalten:

• Öffnen Sie den Editor Ihres Konfigurators.
• Klicken Sie in der Seitenleiste auf
  Loading...
  .
• Wechseln Sie zu dem Tab Einbetten.
• Dort finden Sie den Schalter Javascript Events aktivieren.

Empfangen werden die Events wie oben beschrieben über window.addEventListener("message", ...).

Welche Events gibt es?

K3VariableChanged – der Nutzer hat ein Merkmal geändert. Felder:

• key: der Key des Merkmals, ersatzweise sein Name. Merkmale innerhalb von Komponenten werden als Pfad mit der Nummer der Komponente gemeldet, z.B. fenster[1].rahmen[0].breite.
• value: der neue Wert – bei Auswahlen das Wert-Objekt, bei Zahlen die Zahl, bei Texten der Text.
• data: die typspezifischen Zusatzangaben, sofern es welche gibt, z.B. Schriftart und Farbe bei Texten oder Ausschnitt und Skalierung bei Bildern.
• applied: false, wenn die Regelengine die Änderung nicht übernommen hat, der Nutzer also auf einen Konflikt gestoßen ist. Dann steht unter attempted der Wert, den er wählen wollte. Nimmt er den Konflikt anschliessend an, kommt der Event ein zweites Mal mit applied: true.

K3InstanceAdded und K3InstanceRemoved – der Nutzer hat eine Komponente hinzugefügt oder entfernt. Neben key, value und applied enthalten sie instance, die Position in der Liste (0, 1, 2, ...).

K3Undo und K3Redo – der Nutzer hat eine Änderung zurückgenommen oder wiederholt. Unter keys stehen die Merkmale, deren Wert sich dadurch geändert hat.

Was Sie dabei wissen sollten

• Gemeldet wird nur die Änderung, die der Nutzer selbst vorgenommen hat. Was die Regelengine daraufhin an anderen Merkmalen nachzieht, wird nicht gemeldet – Sie sehen also die Absicht, nicht die Folgen.
• Texteingaben werden zusammengefasst und erst kurz nach der letzten Eingabe gemeldet, damit aus "Müller" nicht sechs Events werden.
• Änderungen aus Erweiterungen sehen genauso aus wie Klicks des Nutzers und lassen sich nicht davon unterscheiden.
• Hochgeladene Bilder werden nur als Verweis gemeldet, nie als Datei-Inhalt.