> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/cross-domain-tracking-and-whitelisting.md).

# Cross-Domain Tracking & Whitelisting

{% hint style="info" %}
Cross-domain tracking allows you to track page views, form submissions, and click events across multiple domains while having all data appear in your main website's dashboard. This is especially useful for ecommerce sites with separate checkout domains or multi-domain setups.
{% endhint %}

Track user interactions across multiple domains and subdomains while maintaining a unified view in your primary Humblytics dashboard. Whether you're running an ecommerce site with a separate checkout domain or managing multiple related websites, cross-domain tracking ensures complete visibility into your user journeys.

## When do you actually need this?

Most sites don't need cross-domain tracking at all. You need it in three common situations:

1. **www and non-www versions of the same site.** If visitors can land on both `example.com` and `www.example.com`, make sure the domain in Humblytics matches the final destination after any redirect. You don't need the `domain` parameter for this; just match the exact domain in your site settings.
2. **Checkout on a separate domain.** Your store is on `example.com` but payment happens on `checkout.example.com` or a provider's domain. Use cross-domain events so conversions attribute back to your main site.
3. **A booking or form tool on a third-party domain.** For example a Calendly page or a hosted signup flow. Use cross-domain events (or a Reach External Destination goal in split tests) to count those conversions.

If none of these apply to you, install the script normally and skip this guide.

***

## How Cross-Domain Tracking Works

Cross-domain tracking enables you to:

* **Track checkout processes** on separate domains (e.g., `yourdomain.com` → `checkout.yourdomain.com`)
* **Monitor multi-step funnels** that span different domains
* **Attribute conversions** from external domains back to your main site
* **Maintain unified analytics** across your entire digital ecosystem

**Key Benefits:**

| Benefit               | Detail                                                                           |
| --------------------- | -------------------------------------------------------------------------------- |
| **Unified Dashboard** | All cross-domain events appear in your main site's analytics                     |
| **Complete Funnels**  | Track user journeys across domain boundaries                                     |
| **Privacy-first**     | The analytics script uses no cookies or local-storage identifiers, on any domain |

***

## Cross-Domain Event Tracking

You can track three types of events across domains using the `domain` parameter:

### Page Views

Track when users visit pages on external domains:

```javascript
window.Humblytics.trackPageView("/checkout", {
  domain: "yourdomain.com",
});
```

### Form Submissions

Track form completions on external domains:

```javascript
window.Humblytics.trackFormSubmission("checkout-form", {
  domain: "yourdomain.com",
});
```

### Click Events

Track button clicks and link interactions on external domains:

```javascript
window.Humblytics.trackClickEvent("purchase-button", "", {
  domain: "yourdomain.com",
});
```

`trackClickEvent` takes the click name, an optional label (for example the button text, or `""`), and then the options. If you pass the options as the second argument, the domain is ignored.

> **Important:** The `domain` parameter should specify the main website domain where you want the event data to appear in your dashboard. Events with a `domain` are only accepted if that external domain has been whitelisted on your main site (see Step 2 below); otherwise they are dropped.

***

## Setup Instructions

### Step 1: Install Humblytics on Both Domains

Both your main domain and the external domain need the Humblytics tracking script. Use your main site's script tag on both:

```html
<!-- Add to <head> of both domains -->
<script
  async
  src="https://app.humblytics.com/hmbl.min.js?id=YOUR_HUMBLYTICS_ID"
></script>
```

Your main domain must be a site in your Humblytics account. The external domain doesn't need to be.

### Step 2: Whitelist the External Domain (Required)

Humblytics only accepts cross-domain events from domains you've approved. Any event sent with a `domain` option from a domain that isn't whitelisted on your main site is dropped.

Ask support to whitelist the external domain on your main site: email **<support@humblytics.com>** with your main domain and the external domain (for example `checkout.yourdomain.com`). Subdomains of a whitelisted domain are covered automatically. Self-serve whitelisting in site settings is coming.

### Step 3: Implement Cross-Domain Tracking

On the external domain, use the tracking methods with the `domain` parameter:

**Example: Ecommerce Checkout Flow**

```javascript
// On checkout.yourdomain.com - track checkout page view
window.Humblytics.trackPageView("/checkout-start", {
  domain: "yourdomain.com",
});

// Track form submission on checkout completion
window.Humblytics.trackFormSubmission("checkout-complete", {
  domain: "yourdomain.com",
});

// Track purchase button clicks
window.Humblytics.trackClickEvent("purchase-cta", "", {
  domain: "yourdomain.com",
});
```

Only events that carry the `domain` option are attributed to your main site. Automatic page views and clicks on the external domain are recorded under the external domain only if it is also a site in your account; otherwise they are ignored.

***

## Common Use Cases

### Ecommerce with Separate Checkout

**Scenario:** Main site on `store.com`, checkout on `checkout.store.com`

```javascript
// On checkout.store.com
window.Humblytics.trackPageView("/checkout", {
  domain: "store.com",
});

window.Humblytics.trackFormSubmission("purchase-form", {
  domain: "store.com",
});
```

### Multi-Domain Company Website

**Scenario:** Main site on `company.com`, blog on `blog.company.com`, support on `help.company.com`

```javascript
// On blog.company.com
window.Humblytics.trackPageView("/blog-post", {
  domain: "company.com",
});

// On help.company.com
window.Humblytics.trackFormSubmission("support-ticket", {
  domain: "company.com",
});
```

### Third-Party Integration Tracking

**Scenario:** Main site on `business.com`, booking system on `bookings.thirdparty.com`

```javascript
// On bookings.thirdparty.com
window.Humblytics.trackFormSubmission("appointment-booking", {
  domain: "business.com",
});
```

***

## Foxy Checkout Example

You don't need cross-domain events to attribute Foxy purchases. The tracking script on your main site passes the visit ID into the Foxy cart automatically, and the [Foxy connector](https://docs.humblytics.com/how-to-track-purchase-events/foxy.md) matches each transaction to that visit.

If you also want the Foxy checkout and receipt pages to show up as page views on your main site, add this to Foxy's custom footer. This is optional, and requires `yourstore.foxycart.com` (or your custom checkout domain) to be whitelisted on your main site as described above:

```html
<!-- In Foxy custom footer (optional page-view tracking) -->
<script
  async
  src="https://app.humblytics.com/hmbl.min.js?id=YOUR_HUMBLYTICS_ID"
></script>

{% if context == 'checkout' %}
<script>
  window.HumblyticsOnReady(function (humblytics) {
    humblytics.trackPageView("/foxy-checkout", {
      domain: "your-main-domain.com",
    });
  });
</script>
{% endif %} {% if context == 'receipt' and first_receipt_display %}
<script>
  window.HumblyticsOnReady(function (humblytics) {
    humblytics.trackPageView("/foxy-receipt", {
      domain: "your-main-domain.com",
    });
  });
</script>
{% endif %}
```

***

## Best Practices

### Consistent Naming

Use clear, consistent naming for cross-domain events:

* **Page paths:** Use descriptive paths like `/checkout-start`, `/payment-complete`
* **Event labels:** Use descriptive names like `checkout-form`, `newsletter-signup`
* **Domain references:** Always use your primary domain in the `domain` parameter

### Event Organization

Structure your cross-domain events logically:

```javascript
// Good: Descriptive and organized
window.Humblytics.trackPageView("/ecommerce/checkout", { domain: "main.com" });
window.Humblytics.trackFormSubmission("ecommerce-purchase", {
  domain: "main.com",
});

// Avoid: Generic or unclear naming
window.Humblytics.trackPageView("/page1", { domain: "main.com" });
window.Humblytics.trackFormSubmission("form", { domain: "main.com" });
```

### Testing Your Implementation

1. **Install tracking** on both domains
2. **Trigger test events** on the external domain
3. **Verify in dashboard** that events appear under your main domain
4. **Check attribution** by following the complete user journey

***

## Viewing Cross-Domain Data

All cross-domain events appear in your main dashboard exactly like native events:

* **Page Views:** Observe → Analytics → Pages
* **Form Submissions:** Observe → Analytics → Clicks & forms (Forms section)
* **Click Events:** Observe → Analytics → Clicks & forms
* **Funnels:** Include cross-domain steps in funnel analysis
* **Split Tests:** Use cross-domain events as conversion goals

***

## Using Cross-Domain Events in Split Tests

Beyond just tracking cross-domain interactions, you can use these events as **conversion goals in split tests**. This enables sophisticated A/B testing scenarios where the conversion happens on external domains.

### When to Use Cross-Domain Event Goals

**Instead of simple destination page tracking**, use cross-domain events when:

* **Complex conversion flows:** The conversion involves multiple steps or specific interactions on external sites
* **Precise tracking:** You need to track the actual conversion action, not just page arrival
* **External checkout processes:** Track completed purchases on separate checkout domains
* **Third-party integrations:** Monitor conversions through external booking systems, forms, or apps

### Setup Process

**Step 1: Implement Cross-Domain Event Tracking**

Set up the appropriate tracking on your external domain:

```javascript
// Example: Track checkout completion on external domain
window.Humblytics.trackFormSubmission("checkout-complete", {
  domain: "yourmainsite.com",
});

// Example: Track specific page interactions
window.Humblytics.trackClickEvent("external-signup-button", "", {
  domain: "yourmainsite.com",
});

// Example: Track custom page view events
window.Humblytics.trackPageView("/external-conversion-step", {
  domain: "yourmainsite.com",
});
```

**Step 2: Create Split Test with Event Goal**

1. Navigate to **Split Testing** → **Start New Experiment**
2. Choose the appropriate **event goal type**:
   * **Form Submission Event** for `trackFormSubmission()` calls
   * **Click Event** for `trackClickEvent()` calls
   * **Page View Event** for `trackPageView()` calls
3. **Enter the exact event name** from your tracking code (e.g., "checkout-complete", "external-signup-button")

**Step 3: Configure Variants and Launch**

Set up your page variants as normal and launch the test. The cross-domain events will be attributed to the correct split test variant based on the user's session.

### Real-World Examples

**Ecommerce Checkout Optimization**

```javascript
// Split test: Optimize product pages for checkout completion
// Goal: Track actual purchases, not just checkout page visits

// On external checkout domain
window.Humblytics.trackFormSubmission("purchase-complete", {
  domain: "store.com",
});

// Split test goal: Form Submission Event = "purchase-complete"
```

**Lead Generation with External Forms**

```javascript
// Split test: Optimize landing pages for form completions
// Goal: Track successful form submissions on third-party platform

// On external form platform
window.Humblytics.trackFormSubmission("lead-qualified", {
  domain: "business.com",
});

// Split test goal: Form Submission Event = "lead-qualified"
```

**SaaS Trial Activation**

```javascript
// Split test: Optimize signup flow for trial activation
// Goal: Track when users complete onboarding on external app

// On external app domain
window.Humblytics.trackPageView("/onboarding-complete", {
  domain: "marketing-site.com",
});

// Split test goal: Page View Event = "/onboarding-complete"
```

### Advanced Attribution

Cross-domain event goals maintain proper attribution throughout complex user journeys:

1. **User visits** your split test page variant
2. **User navigates** to external domain (checkout, booking, etc.)
3. **Cross-domain event** fires on external domain
4. **Attribution preserved** back to original split test variant
5. **Conversion counted** for the correct test group

This enables testing of complete conversion funnels that span multiple domains while maintaining accurate statistical analysis.

### Best Practices for Split Test Goals

**Event Naming:**

* Use descriptive, unique event names
* Maintain consistency across domains
* Document your event naming convention

**Timing:**

* Ensure events fire after the Humblytics script loads
* Place tracking calls at the actual conversion moment
* Test event firing across different user scenarios

**Validation:**

* Test the complete flow from split test variant to cross-domain conversion
* Verify events appear in your dashboard with correct attribution
* Monitor for any attribution delays or issues

***

{% hint style="info" %}
**Related: URL fragments.** If a checkout or multi-step form changes only the part of the URL after `#` (`#step-1`, `#step-2`), turn on **Site settings → General → Track URL fragments** so each step is recorded as its own page view. This setting is independent of cross-domain tracking.
{% endhint %}

## Troubleshooting

### Events Not Appearing

**Check the following:**

1. Humblytics script is installed on the external domain
2. The `domain` parameter matches your main domain exactly
3. The external domain has been whitelisted on your main site (required)
4. The main domain is a site in your Humblytics account
5. Events are being triggered after the Humblytics script loads (wrap calls in `window.HumblyticsOnReady`)
6. For `trackClickEvent`, the options are the **third** argument, after the label

### Incorrect Attribution

**Verify:**

1. The `domain` parameter value is correct
2. Timing of event tracking (wait for script to load)
3. Network connectivity from external domain to Humblytics

### Seeing Your Own Domain as a Referrer (www vs non-www)

If your site has both a root domain and a www domain (for example `example.com` redirecting to `www.example.com`), older versions of Humblytics could log that redirect as an external referral, making your own domain appear as a top traffic source.

**A platform-wide fix shipped on June 19, 2026.** Sessions recorded after that date no longer log the redirect as a referral.

Two things to know:

1. **Historical data is not retroactively cleaned.** Sessions recorded before the fix will still show the self-referral in longer date ranges. That's expected; the numbers going forward are clean.
2. **Match the final domain.** In your Humblytics site settings, use the domain visitors actually end up on after the redirect (usually the www version).

If you still see new self-referral sessions after June 19, 2026, email **<support@humblytics.com>** with your domain setup.

***

## Advanced Implementation

### Dynamic Domain Detection

For complex setups, you can dynamically set the domain parameter:

```javascript
// Automatically detect main domain
const mainDomain = window.location.hostname.includes("checkout")
  ? "yourdomain.com"
  : window.location.hostname;

window.Humblytics.trackPageView("/current-page", {
  domain: mainDomain,
});
```

### Conditional Cross-Domain Tracking

Only track cross-domain when necessary:

```javascript
function trackEvent(eventType, eventName, options = {}) {
  const isExternalDomain = window.location.hostname !== "yourdomain.com";

  if (isExternalDomain) {
    options.domain = "yourdomain.com";
  }

  if (eventType === "pageView") {
    window.Humblytics.trackPageView(eventName, options);
  } else if (eventType === "formSubmission") {
    window.Humblytics.trackFormSubmission(eventName, options);
  }
}
```

***

**Questions or need help with complex cross-domain setups?** Email **<support@humblytics.com>** for guidance on advanced implementations and custom attribution models.
