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 and a container div:

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

Full Configuration

Configure all available options for complete control:

Full Configuration Example

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

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

Resolution Center

Resolution Center

<script
  data-starter-page="resolve"
  data-shop-slug="your-shop-slug"
  ...
></script>

Opens the resolution workflow for returns, exchanges, or other post-purchase requests.

General Finder

General Finder

<script data-starter-page="finder" data-shop-slug="your-shop-slug" ...></script>

Shows a form where customers can search for their orders using order number and ZIP code.

Tracking Updates

Tracking Updates

<script
  data-starter-page="tracking-updates"
  data-shop-slug="your-shop-slug"
  ...
></script>

Shows only the tracking updates widget.

Global

Global Scope

<script
  data-starter-page="global"
  data-shop-slug="your-shop-slug"
  defer
></script>

Enables global functionality, like attribution tracking across all pages. See Attribution Tracking for complete details.

Attribution Tracking

The Browser SDK includes a powerful attribution tracking module designed specifically for Shopify stores. This feature captures marketing attribution parameters from URLs and stores them in the Shopify cart, ensuring attribution data survives across browsing sessions, page redirects, and payment gateway flows.

Shopify Only

Attribution tracking only works on Shopify stores. For other platforms, use the Order Analytics API.

How Attribution Works

1. Customer clicks a marketing link with attribution parameters
2. Browser SDK captures the parameters (source, campaign, medium)
3. Data is stored in Shopify cart attributes (persists for 10 days)
4. On checkout completion, data transfers to order note_attributes
5. Backend systems read attribution from order webhooks for analytics

Key Features

• Cart-Session Attribution: First-click attribution per cart (10-day cart lifetime)
• Survives Redirects: Works through payment gateway redirects (PayPal, Apple Pay, etc.)
• Privacy-Friendly: Works with iOS 14+ tracking prevention (stored in cart, not cookies)
• Smart Deduplication: Won't overwrite existing attribution in same cart session
• Non-Blocking: Runs asynchronously, never delays page load
• Silent Failures: Errors logged in debug mode but hidden from customers

Installation

Add this script to ALL pages of your Shopify theme (typically in theme.liquid):

Global Attribution Setup

<!-- Add before </head> in theme.liquid -->
<script
  id="karla-bundle-global"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="your-shop-slug"
  data-starter-page="global"
  defer
></script>

important

The data-starter-page="global" attribute is required to enable attribution capture on all pages.

URL Parameters

The SDK recognizes these attribution parameters in URLs:

Parameter	Required	Description
karla_source	Yes	Attribution source
karla_campaign	No	Campaign identifier
karla_medium	No	Attribution medium (e.g., email)

Example:
https://shop.com/products/shoes?karla_source=email&karla_campaign=abandoned-cart&karla_medium=email

Example URLs

Email Campaign

https://shop.com/products/shoes?karla_source=email&karla_campaign=nov-abandoned-cart&karla_medium=email

Track emails from your email marketing platform.

Social Media

https://shop.com/?karla_source=instagram&karla_campaign=influencer-promo&karla_medium=social

Track social media campaigns and influencer promotions.

Product Recommendations

https://shop.com/products/widget?karla_source=karla&karla_campaign=product-recommendations

Track clicks from Karla's product recommendation widgets.

Cart Attributes Captured

The SDK stores these attributes in the Shopify cart, which automatically transfer to order note_attributes on checkout:

{
  "_karla_source": "instagram",
  "_karla_campaign": "influencer-promo",
  "_karla_medium": "social",
  "_karla_captured_at": "2025-11-26T14:30:15.234Z",
  "_karla_landing_url": "https://shop.com/products/shoes?karla_source=...",
  "_karla_landing_path": "/products/shoes",
  "_karla_referrer": "https://instagram.com",
  "_karla_version": "1"
}

Using Attribution with Tracking Pages

You can run both attribution capture AND tracking pages on the same site by using multiple script tags:

Combined Setup

<!-- Global attribution on all pages -->
<script
  id="karla-bundle-global"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="your-shop-slug"
  data-starter-page="global"
  defer
></script>

<!-- Tracking page on specific tracking page -->
<script
  id="karla-bundle"
  src="https://browser.gokarla.io/latest/bundle.min.js"
  data-shop-slug="your-shop-slug"
  data-starter-page="order-tracking"
></script>
<div id="karla-container"></div>

tip

Use different id attributes (e.g., karla-bundle-global) when running multiple instances on the same page.

Debug Mode

Enable debug logging to see attribution capture in the browser console:

Attribution with Debug Mode

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

Debug logs include:

• Shopify store detection
• Attribution parameter extraction
• Cart attribute updates
• Error messages and warnings

Attribution FAQs

What happens if a customer clicks multiple attribution links?

The SDK uses first-click attribution per cart session. Once attribution is captured, subsequent clicks won't overwrite it until:

• The cart expires
• An order is placed
• The cart is cleared

This ensures accurate attribution for the first marketing touchpoint.

How long is attribution data stored?

Attribution data persists in the cart's lifetime. When an order is placed, the data transfers to order note_attributes and becomes permanent.

Does this interfere with existing tracking pages?

No. Attribution mode (data-starter-page="global") runs independently from tracking page mode. You can safely use both on the same site.

Can I use this on non-Shopify stores?

No. The attribution module only works on Shopify stores (for now). For other platforms, use the Order Analytics API to submit attribution data when creating orders.

Does this work with Apple's privacy features?

Yes! Because attribution is stored in the cart (not cookies), it works even with iOS 14+ tracking prevention and Intelligent Tracking Prevention (ITP).

Integration Methods

DOM Order Requirement

The container element must exist in the DOM before the script loads. The SDK executes immediately upon loading and looks for the karla-container div. If it doesn't exist yet, the SDK will fail to initialize.

Method 1: Standard Integration (Recommended)

Let the SDK handle all iframe configuration:

Standard Integration

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

Why use karla-container?

This is the simplest and most future-proof approach. The SDK automatically handles all iframe configuration, security settings, and dynamic height management.

Method 2: Custom Iframe (More Control)

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

Custom Iframe Integration

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

When to use custom iframe

Use this approach when you need:

• Custom iframe attributes or styling
• Integration with specific frameworks
• Control over iframe lifecycle
• Compatibility with legacy implementations

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>

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

Debug Mode

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

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:

Before (Legacy)

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

After (W3C Compliant)

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

Attribute Reference

Legacy Attribute	W3C Compliant	Notes
shop-slug	data-shop-slug	Required
starter-page	data-starter-page	Set to "order-tracking"
debug	data-debug	Set to "false"
order-number	data-order-number	Optional
zip-code	data-zip-code	Optional

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 creation and styling automatically */

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 (id="karla-container" or id="karla-frame")

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

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

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

• Documentation: docs.gokarla.io
• Support: support@gokarla.io
• 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

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