How do I embed the configurator on my website or in my online store?

Prerequisites

• You have created a configurator and veröffentlicht.

Integration

Of course, you’ll want to use the configurator on your website or in your online store.

• Click “Options” in the left sidebar, then click “Embed.”
• You’ll see the following options:
  • Technical integration options: web component (recommended), IFrame, or link
  • Do you want to start with a predefined configuration? (=Inspiration)
  • Do you want to use the configurator yourself or assign it to one of your Händler?
  • In which Sprache should the configurator be displayed?
• Once you’ve made your selection, the code you need to insert into your website will be displayed on the right.

Below, we’ll discuss the details, as well as the pros and cons of each option:

Use as a Web Component (recommended)

The K3 can be used directly as an HTML element <k3-view> on any page. This allows the configurator to be fully integrated into the layout—without cross-origin restrictions or visual breaks.

A simple HTML tag is all it takes to embed it:

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

Alternatively, an inspiration code can be used instead of an app attribute:

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

If you want to load your page with a dynamic inspiration code, e.g., as https://mein-unternehmen.de/konfigurator?code=ZTRIZTIUZ, then insert the following code directly below the web component:

<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>

All additional attributes that would otherwise be included in the configurator URL can be passed to the tag (e.g., lang, dealer, etc.)

For the HTML element to be available, the K3 JavaScript must be loaded.

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

info

In extensions such as Veranda, a different script must be used— check the embedding guide.

Advantages:

• Seamless integration into your page, no disruption to the user experience.
• Full SEO relevance and tracking control.
• The user remains on your page.
• The configurator’s URL is not visible.

Disadvantage:

• None

Height of the configurator

The configurator should fill the screen as completely as possible. If it is too short, the user will have to scroll, which interferes with the 3D display—making it significantly more difficult to use.

The desired height is usually the screen height minus the page header. The implementation depends on the embedding method:

Web Component

Enclose the web component in a <div>, to which you assign the height via CSS:

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

IFrame

You can set the height directly on the IFrame element:

<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>

Alternatively, you can set the height of a surrounding element using CSS:

height: calc(100vh - 80px);

100vh is the screen height; the second value is the height of your page header—adjust this as needed.

caution

In some browsers, the spaces around the - in calc() are crucial— without them, the height will not be calculated correctly.

Embedding via IFrame

tip

An IFrame is a technical method for displaying one webpage within another.

You can display the configurator on a page of your store or website. To do this, you can select any page or create a new page, such as /konfigurator.

On that page, insert the code displayed as an IFrame under Options in the Embed tab. You can usually do this in your web editor using a generic HTML element. The code looks something like this:

<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>

The individual lines mean the following:

• <iframe>: This is the technical command to display another webpage.
• frameBorder="0": No border should be displayed around the configurator.
• title="Object Code - iFrame": This is optional—the title will not be displayed.
• width="100%": The configurator takes up the entire available width.
• height="100%": The configurator takes up the entire available height.
• allow="fullscreen": The configurator may be displayed in full-screen mode.
• src=...": This is the actual URL of the configurator page.
• style="border:none;overflow:hidden": No frame is displayed (in newer browsers). And anything that is too large to display is hidden.

Make sure that the height is set correctly.

After integration, check the page’s PageSpeed Index. A 3D configurator naturally takes a while to load—this affects performance metrics.

Advantages:

• The user stays on your page.
• The configurator’s URL is not visible.

Disadvantage:

• The integration is technically a bit more complex.
• The loading time is attributed to your website.

Integration as a Link

Of course, you can simply link to the configurator on your page (in your store). To do this, just set up a link to the address of the live version.

The user can return to your store via the Abschluss-Aktionen: The configurator includes buttons to request the configuration via email or add it to the shopping cart. In the latter case, the user is redirected back to your store.

You can choose whether you want the configurator to open in a new tab or replace your website; your web editor will offer options for this.

Advantages:

• Integration is simple
• The user experience is optimal—especially on mobile devices— since the configurator can utilize the entire page and there are no issues with scrolling behavior.

Disadvantage:

• Users feel as though they are leaving your site
• The configurator’s URL is visible in the address bar

Loading Animation

When the configurator is embedded in a page via a web component or an IFrame, it sends events when loading begins and ends.

To do this, the surrounding page must listen for so-called IFrame events (as with 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);

The phases are as follows:

• First, the app itself is loaded. During this time, K3 displays a loading animation.
• Now the K3AppLoaded event is sent.
• K3 then begins loading all data: the configurator, the Inspiration section (if applicable), and all models and images.
• When this is fully complete, the K3FullyLoaded event is sent.

Track Changes

The configurator also reports every change the user makes to the embedding page. This allows you to analyze your users’ behavior, for example in Google Analytics or a tag manager.

The events are enabled unless you disable them:

• Open your configurator’s editor.
• Click
  Loading...
  in the sidebar.
• Switch to the Embed tab.
• There you will find the Enable JavaScript Events toggle.

The events are received via window.addEventListener("message", ...) as described above.

What events are available?

K3VariableChanged – the user has changed a feature. Fields:

• key: The attribute’s key, or alternatively its name. Attributes within Komponenten are reported as a path with the component’s number, e.g., fenster[1].rahmen[0].breite.
• value: the new value—the value object for selections, the number for numeric values, and the text for text fields.
• data: type-specific additional information, if any, e.g., font and color for text or cropping and scaling for images.
• applied: false if the rule engine did not apply the change—meaning the user encountered a conflict. In this case, attempted contains the value the user intended to select. If the user subsequently accepts the conflict, the event is triggered a second time with applied: true.

K3InstanceAdded and K3InstanceRemoved – the user has added or removed a component. In addition to key, value, and applied, they contain instance, which is the position in the list (0, 1, 2, ...).

K3Undo and K3Redo – the user has undone or repeated a change. keys lists the characteristics whose values have changed as a result.

What You Should Know

• Only the change made by the user is reported. Changes to other attributes triggered by the rule engine are not reported— so you see the intent, not the consequences.
• Text entries are aggregated and reported only shortly after the last entry, so that “Müller” does not result in six separate events.
• Changes from Erweiterungen look exactly like user clicks and cannot be distinguished from them.
• Uploaded images are reported only as a reference, never as file content.