Skip to main content

Embedding options

Tracking pages can be embedded in your shop website with our JavaScript SDK.

See Browser SDK for technical information about our JavaScript bundle.

The simplest way to embed Karla is to add a container div and let the SDK handle all iframe configuration:

<div id="karla-container"></div>
<script
  id="karla-bundle"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="my-shop-slug"
></script>
Why use karla-container?
  • Simpler integration - Just one div, no iframe attributes to remember
  • Automatic configuration - SDK handles security, permissions, and sizing
  • Future-proof - SDK updates won't require changes to your code
  • Dynamic height - Works seamlessly with automatic height adjustment

Alternative approach​

Deprecated

While supported for backwards compatibility, we recommend using the karla-container approach above for new integrations.

If you prefer to define the iframe directly, place it before the script with the karla-frame id:

<iframe
  id="karla-frame"
  style="width: 100%;"
  frameborder="0"
  allow="clipboard-read clipboard-write fullscreen"
  sandbox="allow-same-origin allow-scripts allow-forms allow-modals allow-popups"
></iframe>
<script
  id="karla-bundle"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="my-shop-slug"
></script>

By default, the tracking page url will be generated from the query parameters defined in the parent page.

  • orderNumber: The order number as it is defined in your shop. Can be overridden by script parameters.
  • zipCode: The zip code to serve as validation to show the tracking details. Can be overridden by script parameters.
  • lang (optional): An ISO 639-1 language code. If the language code is supported, the page will be forced to that language even if the user browser has a different locale configured. If not defined, the page will be shown based on user preferences (fallback is en).

Script parameters​

The bundle.min.js script accepts the following attributes:

Required attributes​

  • data-shop-slug: Your unique shop slug (can be browsed in your shop profile in portal).
    • Legacy format shop-slug is still supported for backwards compatibility

Optional attributes​

  • data-order-number: The order number as it is defined in your shop. If not provided, the parent page URL must include an orderNumber query parameter.
  • data-zip-code: The zip code to serve as validation to show the tracking details. If not provided, the parent page URL must include a zipCode query parameter.
  • data-starter-page: The initial page to display (finder, tracking-updates, resolve, order-tracking). If not provided, defaults to order-tracking.
  • data-debug: Enable debug logging.
W3C Compliance

All attributes use the W3C-compliant data- prefix. While shop-slug, starter-page, and debug still support legacy formats for backwards compatibility, we strongly recommend using the W3C-compliant format for better HTML validation.

Container placement​

important

The karla-container div must be placed before the script tag in your HTML. The script runs immediately and looks for the container when it executes.

Why W3C compliance matters

Using non-standard attributes can cause:

  • Failed HTML validation - Many enterprises require valid HTML for compliance
  • SEO penalties - Search engines may rank invalid HTML lower
  • Build failures - Some build tools and CI/CD pipelines enforce HTML validation
  • Accessibility issues - Screen readers and assistive technologies expect valid HTML
  • Future compatibility - Non-standard attributes may conflict with future HTML specifications

Testing the iFrame​

Now that we've created a new page (e.g. https://your-shop-domain/tracking), we can add our URL parameters to the URL so that the iframe is loading the given order details in the background.

Example:

  • Base tracking page URL: https://your-shop-domain/tracking/tracking
  • Adding URL parameters: https://your-shop-domain/tracking/tracking?orderNumber=00001&zipCode=10119

Order finder​

You can add the order finder iframe with the following snippet:

<iframe
  id="karla-frame"
  style="width: 100%;"
  frameborder="0"
  allow="clipboard-read clipboard-write fullscreen"
  sandbox="allow-same-origin allow-scripts allow-forms allow-modals allow-popups"
></iframe>
<script
  id="karla-bundle"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="my-shop-slug"
  data-starter-page="order-finder"
></script>
note

Make sure that data-starter-page="order-finder" is defined in the script.

Using our API​

See our API Docs to create your own tracking page.