Skip to main content

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:

Quick Setup
<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:

Versioned Installation
<!-- 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:

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

<!-- The SDK will automatically create or use this iframe -->
<iframe id="karla-frame"></iframe>

Full Configuration

Configure all available options for complete control:

Full Configuration Example
<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-starter-page="order-tracking"
data-debug="true"
></script>

<iframe id="karla-frame"></iframe>

Configuration Options

Required Attributes

AttributeTypeDescription
data-shop-slugstringYour unique shop identifier provided by GoKarla

Optional Attributes

AttributeTypeDefaultDescription
data-order-numberstringURL paramPre-fill order number for tracking
data-zip-codestringURL paramPre-fill ZIP code for validation
data-starter-pagestringorder-trackingInitial page to display
data-debugbooleanfalseEnable debug logging

Starter Page Options

Order Tracking Page
<script
data-starter-page="order-tracking"
data-shop-slug="your-shop-slug"
...
></script>

Displays the order tracking interface where customers can view their shipment status.

Integration Methods

DOM Order Requirement

The iframe or container element must exist in the DOM before the script loads. The SDK executes immediately upon loading and looks for these elements. If they don't exist yet, the SDK will fail to initialize.

Method 1: Automatic Iframe Creation

The SDK can automatically create an iframe inside a container div:

Automatic Iframe Creation
<!-- Just add 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>

Method 2: Pre-existing Iframe

Use your own iframe for more control:

Custom Iframe
<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:

Server-Side Integration
<!-- Example with PHP -->
<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-zip-code", orderData.zip);
});
</script>

Advanced Configuration

Custom Window Configuration

Control the behavior through the global KARLA_CONFIG object:

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

<!-- Remember: iframe must be present first -->
<iframe id="karla-frame"></iframe>

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

Debug Mode
<iframe id="karla-frame"></iframe>

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

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

// These parameters are automatically detected:
// - orderNumber → data-order-number
// - zipCode → data-zip-code
// - lang → Language preference
// - flowType → Resolution flow type (for resolve page)
note

This configuration is very often used in public links

Migration Guide

From Legacy Attributes

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

<script
id="karla-bundle"
shop-slug="your-shop-slug"
starter-page="order-tracking"
debug
></script>

Attribute Migration Reference

Legacy AttributeW3C CompliantNotes
shop-slugdata-shop-slugRequired
merchant-slugdata-shop-slugAlias supported
starter-pagedata-starter-pageOptional
debugdata-debugSet to "true"
order-numberdata-order-numberNot supported in legacy
zip-codedata-zip-codeNot supported in legacy

Best Practices

1. Load Timing

Optimal 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

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

/* The SDK handles iframe styling automatically */
#karla-frame {
/* Styles are applied by the SDK */
}

3. Error Handling

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:

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

Iframe not displaying
  1. Verify your shop slug is correct
  2. Check browser console for errors
  3. Ensure the script has id="karla-bundle"
  4. Confirm container element exists
Height not adjusting properly
  1. The SDK automatically manages heights
  2. Ensure no conflicting CSS on the iframe
  3. Check if JavaScript errors prevent height updates
  4. Enable debug mode to see height calculations
Order data not pre-filling
  1. Verify attribute names are correct (data-order-number, not order-number)
  2. Check URL parameters as fallback
  3. Ensure values are properly encoded
  4. Enable debug mode to see parameter parsing
Page showing multiple errors or not loading

If the tracking page displays multiple errors or fails to load:

  1. Wait a few minutes before trying again
  2. Avoid making rapid repeated requests
  3. Check your implementation isn't triggering multiple loads
  4. Ensure you're not automatically refreshing the page
  5. If the issue persists after waiting, contact support

This typically occurs when our system detects unusual activity patterns.

Order finder shows instead of tracking page

If you see the order finder form when expecting the tracking page:

  1. Verify the order number and ZIP code are correct
  2. Ensure the order exists in the system
  3. Check that order data has been synchronized
  4. Confirm the parameters are being passed correctly
  5. Try again after a few minutes if the order was just placed

The system displays the order finder when it cannot locate the specified order or encounters an error during lookup. This is obfuscated by design, to prevent order enumeration attacks.

Order finder fails to locate order

If the order finder cannot find your order after submitting:

  1. Double-check the order number format and ZIP code
  2. Ensure the order exists and has been processed
  3. Verify the ZIP code matches the shipping address
  4. Wait a few minutes if the order was recently placed
  5. Check for any special characters or spaces in the order number

The same security mechanism that shows the order finder instead of the tracking page also prevents the finder from revealing whether an order exists when incorrect details are provided.

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 applies appropriate sandbox attributes:

Security Attributes
<iframe
sandbox="allow-same-origin allow-scripts allow-forms allow-modals allow-popups"
allow="clipboard-read clipboard-write fullscreen"
></iframe>

Browser Support

BrowserMinimum Version
Chrome90+
Firefox88+
Safari14+
Edge90+
Mobile SafariiOS 14+
Chrome Android90+

Performance

Bundle Size

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

Loading Strategy

Performance Optimization
<!-- 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

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

Changelog

Version 1.x

  • 1.2.0: Added W3C-compliant data- attributes
  • 1.1.0: Resolution center support
  • 1.0.0: Initial release with order tracking