Browser SDK#

The GoKarla Browser SDK is a lightweight JavaScript library that enables seamless integration of GoKarla's tracking and resolution features into your website. With just a few lines of code, you can embed order tracking, order finding, and resolution workflows directly into your customer experience.

Features#

• Zero Dependencies: Pure JavaScript implementation with no external dependencies
• Universal Compatibility: UMD format works with all modern browsers and build systems
• Responsive Design: Automatically adapts iframe heights for desktop and mobile devices
• Multiple Entry Points: Support for order tracking, order finder, and resolution workflows
• W3C Compliant: Supports both standard data- attributes and legacy formats
• Minimal Bundle Size: Optimized for fast loading with < 10KB minified

Installation#

Add the GoKarla Browser SDK to your website using our CDN:

<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
></script>

Version Management#

We recommend using the latest version if you want to receive automatically the latest updates, we ensure backwards compatibility for stable versions:

<!-- Latest version -->
<script src="https://browser.gokarla.io/latest/bundle.min.js"></script>

<!-- Specific version -->
<script src="https://browser.gokarla.io/0.0.8/bundle.min.js"></script>

Basic Configuration#

Minimal Setup#

The simplest integration requires only your shop slug and a container div:

<div id="karla-container"></div>

<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
></script>

Full Configuration#

Configure all available options for complete control:

<div id="karla-container"></div>

<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
  data-order-number="12345"
  data-zip-code="10119"
  data-token="eyJhbGciOi..."
  data-starter-page="order-tracking"
  data-debug="true"
></script>

Configuration Options#

Required Attributes#

Optional Attributes#

Starter Page Options#

Integration Methods#

Method 1: Standard Integration (Recommended)#

Let the SDK handle all iframe configuration:

<div id="karla-container"></div>

<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
></script>

Method 2: Custom Iframe (More Control)#

For advanced use cases where you need more control over the iframe element:

<iframe
  id="karla-frame"
  style="width: 100%; border: none;"
  title="GoKarla Tracking"
></iframe>

<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
></script>

Method 3: Dynamic Parameters#

Pass order information from your backend:

<!-- Example with PHP (token-based) -->
<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
  data-order-number="<?php echo $order->number; ?>"
  data-token="<?php echo $order->tracking_token; ?>"
></script>

<!-- Example with PHP (ZIP code-based) -->
<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
  data-order-number="<?php echo $order->number; ?>"
  data-zip-code="<?php echo $order->zip; ?>"
></script>

<!-- Example with JavaScript -->
<script>
  // Add attributes dynamically
  document.addEventListener("DOMContentLoaded", function () {
    const script = document.getElementById("karla-bundle");
    script.setAttribute("data-order-number", orderData.number);
    script.setAttribute("data-token", orderData.trackingToken);
  });
</script>

Advanced Configuration#

Custom Window Configuration#

Control the behavior through the global KARLA_CONFIG object:

<script>
  window.KARLA_CONFIG = {
    hideHeader: true,        // Hide the GoKarla header
    hideAllWidgets: false,   // Show promotional widgets
  };
</script>

<!-- Container must be present first -->
<div id="karla-container"></div>

<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
></script>

Debug Mode#

Enable debug mode to troubleshoot integration issues:

<div id="karla-container"></div>

<script
  src="https://browser.gokarla.io/latest/bundle.min.js"
  id="karla-bundle"
  data-shop-slug="your-shop-slug"
  data-debug="true"
></script>

Debug mode logs:

• Configuration details
• URL construction
• Height adjustments
• Event communications

URL Parameter Support#

The SDK automatically reads URL parameters as fallbacks when data-* script attributes are not set:

// URL: https://yoursite.com/tracking?orderNumber=12345&zipCode=10119&lang=de

// These parameters are automatically detected:
// - orderNumber → data-order-number
// - zipCode → data-zip-code
// - token → data-token
// - orderName → data-order-name
// - externalId → data-external-id
// - orderId → data-order-id
// - lang → Language preference
// - flowType → Resolution flow type (for resolve page)

Order lookup methods#

The SDK supports multiple ways to identify an order. The tracking and resolve pages will use whichever identifiers are provided:

All lookup methods are protected against enumeration attacks. Invalid or mismatched parameters result in a generic response that does not reveal whether an order exists.

Migration Guide#

From Legacy Attributes#

If you're using non-W3C compliant attributes, migrate to the standard format:

Attribute Reference#

Best Practices#

1. Load Timing#

<!-- Load SDK after page content for better performance -->
<body>
  <!-- Your page content -->

  <div id="karla-container"></div>

  <!-- Load SDK at the end of body -->
  <script
    src="https://browser.gokarla.io/latest/bundle.min.js"
    id="karla-bundle"
    data-shop-slug="your-shop-slug"
    async
  ></script>
</body>

2. Container Styling#

/* Ensure proper container sizing */
#karla-container {
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
  padding: 20px;
}

/* The SDK handles iframe creation and styling automatically */

3. Error Handling#

<script>
  // Listen for SDK errors
  window.addEventListener('error', function(e) {
    if (e.target && e.target.id === 'karla-bundle') {
      console.error('Failed to load GoKarla SDK');
      // Implement fallback logic
    }
  });
</script>

4. Content Security Policy#

If using CSP headers, allow the GoKarla domains:

Content-Security-Policy:
  script-src 'self' https://browser.gokarla.io;
  frame-src 'self' https://app.gokarla.io;
  connect-src 'self' https://api.gokarla.io;

Troubleshooting#

Common Issues#

Debug Checklist#

1. Script Loading

   // Check if SDK loaded
   console.log(document.getElementById("karla-bundle"));

2. Configuration

   // View current configuration (in debug mode)
   window.KARLA_CONFIG;

3. Network Requests

   • Check browser Network tab
   • Verify requests to app.gokarla.io
   • Ensure no CORS errors

Security Considerations#

Data Handling#

• Order numbers and ZIP codes are transmitted securely over HTTPS
• No sensitive payment information is handled by the SDK
• All data is processed according to GDPR requirements

Abuse Prevention#

GoKarla implements multiple security measures to protect merchant and customer data:

• Rate Limiting: Excessive requests from a single source may be temporarily restricted
• Order Enumeration Protection: The system intentionally provides generic responses to prevent discovering valid order numbers
• Activity Monitoring: Suspicious patterns are automatically detected and may result in access restrictions
• IP-based Protection: Sources exhibiting abusive behavior may be blocked

If you're implementing automated testing or monitoring, please:

• Use reasonable request intervals
• Contact support for proper API access if needed
• Avoid attempts to enumerate or discover order information

Violations of these security measures may result in permanent access restrictions.

Iframe Sandboxing#

The SDK automatically applies appropriate sandbox attributes when creating the iframe:

• allow-same-origin
• allow-scripts
• allow-forms
• allow-modals
• allow-popups
• Clipboard permissions: clipboard-read clipboard-write
• Fullscreen support

Browser Support#

Performance#

Bundle Size#

• Minified: < 10KB
• Gzipped: < 4KB
• Zero runtime dependencies

Loading Strategy#

<!-- Async loading -->
<script async src="https://browser.gokarla.io/latest/bundle.min.js"></script>

<!-- Defer loading -->
<script defer src="https://browser.gokarla.io/latest/bundle.min.js"></script>

<!-- Preconnect for faster loading -->
<link rel="preconnect" href="https://browser.gokarla.io" />
<link rel="preconnect" href="https://app.gokarla.io" />

Support#

Getting Help#

• Documentation: docs.gokarla.io
• Support: [email protected]
• Status Page: status.gokarla.io

Reporting Issues#

When reporting issues, please include:

1. Your shop slug
2. Browser and version
3. Console errors (if any)
4. Network requests (HAR file if possible)
5. Steps to reproduce