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:
<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:
<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
Attribute | Type | Description |
---|---|---|
data-shop-slug | string | Your unique shop identifier provided by GoKarla |
Optional Attributes
Attribute | Type | Default | Description |
---|---|---|---|
data-order-number | string | URL param | Pre-fill order number for tracking |
data-zip-code | string | URL param | Pre-fill ZIP code for validation |
data-starter-page | string | order-tracking | Initial page to display |
data-debug | boolean | false | Enable debug logging |
Starter Page Options
- Order Tracking
- Order Finder
- Resolution Center
- General Finder
<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.
<script
data-starter-page="order-finder"
data-shop-slug="your-shop-slug"
...
></script>
Shows a form where customers can search for their orders using order number and ZIP code.
<script
data-starter-page="resolve"
data-shop-slug="your-shop-slug"
...
></script>
Opens the resolution workflow for returns, exchanges, or other post-purchase requests.
<script data-starter-page="finder" data-shop-slug="your-shop-slug" ...></script>
A general-purpose finder interface for various lookup scenarios.
Integration Methods
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:
<!-- 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:
<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 -->
<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:
<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:
<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: 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)
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:
- Before (Legacy)
- After (W3C Compliant)
<script
id="karla-bundle"
shop-slug="your-shop-slug"
starter-page="order-tracking"
debug
></script>
<script
id="karla-bundle"
data-shop-slug="your-shop-slug"
data-starter-page="order-tracking"
data-debug="true"
></script>
Attribute Migration Reference
Legacy Attribute | W3C Compliant | Notes |
---|---|---|
shop-slug | data-shop-slug | Required |
merchant-slug | data-shop-slug | Alias supported |
starter-page | data-starter-page | Optional |
debug | data-debug | Set to "true" |
order-number | data-order-number | Not supported in legacy |
zip-code | data-zip-code | Not supported in legacy |
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 styling automatically */
#karla-frame {
/* Styles are applied by the SDK */
}
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
Iframe not displaying
- Verify your shop slug is correct
- Check browser console for errors
- Ensure the script has
id="karla-bundle"
- Confirm container element exists
Height not adjusting properly
- The SDK automatically manages heights
- Ensure no conflicting CSS on the iframe
- Check if JavaScript errors prevent height updates
- Enable debug mode to see height calculations
Order data not pre-filling
- Verify attribute names are correct (
data-order-number
, notorder-number
) - Check URL parameters as fallback
- Ensure values are properly encoded
- 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:
- Wait a few minutes before trying again
- Avoid making rapid repeated requests
- Check your implementation isn't triggering multiple loads
- Ensure you're not automatically refreshing the page
- 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:
- Verify the order number and ZIP code are correct
- Ensure the order exists in the system
- Check that order data has been synchronized
- Confirm the parameters are being passed correctly
- 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:
- Double-check the order number format and ZIP code
- Ensure the order exists and has been processed
- Verify the ZIP code matches the shipping address
- Wait a few minutes if the order was recently placed
- 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
-
Script Loading
// Check if SDK loaded
console.log(document.getElementById("karla-bundle")); -
Configuration
// View current configuration (in debug mode)
window.KARLA_CONFIG; -
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:
<iframe
sandbox="allow-same-origin allow-scripts allow-forms allow-modals allow-popups"
allow="clipboard-read clipboard-write fullscreen"
></iframe>
Browser Support
Browser | Minimum Version |
---|---|
Chrome | 90+ |
Firefox | 88+ |
Safari | 14+ |
Edge | 90+ |
Mobile Safari | iOS 14+ |
Chrome Android | 90+ |
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:
- Your shop slug
- Browser and version
- Console errors (if any)
- Network requests (HAR file if possible)
- 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