Cross-Domain Identity

When your business operates multiple domains (e.g., www.example.com and shop.example.com, or brand-a.com and brand-b.com), each domain has its own first-party anonymous identifier by default. The cross-domain identity feature links these separate identities into a single user profile through Signal’s Identity Hub.

The problem

Browsers enforce strict cookie isolation between domains. A cookie set on example.com cannot be read by other-brand.com. This means:

• A user who visits brand-a.com and then brand-b.com appears as two separate anonymous users
• Conversion attribution breaks when the ad click lands on one domain and the purchase happens on another
• User journeys spanning multiple domains cannot be stitched together

The solution

Datafly’s Identity Hub acts as a shared intermediary at a neutral subdomain (e.g., id.company.com). When cross-domain is enabled, Datafly.js redirects first-time visitors through the hub, which resolves their identity across domains using an encrypted token.

Site A (brand-a.com)          Identity Hub              Site B (brand-b.com)
┌─────────────────┐         (id.company.com)           ┌─────────────────┐
│                 │                                     │                 │
│  User visits    │──── redirect ────>┌──────────┐     │                 │
│  brand-a.com    │                   │  Hub     │     │                 │
│                 │                   │  looks up│     │                 │
│  anon_id: AAA   │                   │  or      │     │                 │
│                 │<── redirect ──────│  creates │     │                 │
│  anon_id: AAA   │   + encrypted     │  canonical    │                 │
│  (confirmed)    │     token         │  identity│     │                 │
│                 │                   └──────────┘     │                 │
└─────────────────┘                                     │                 │
                                                        │  User visits    │
                                                        │  brand-b.com    │
                                                        │                 │
                                                        │  anon_id: BBB   │
                                                        │──── redirect ──>│
                                                        │                 │
                                                        │  Hub returns    │
                                                        │  anon_id: AAA   │
                                                        │  (same user!)   │
                                                        └─────────────────┘

How it works

Step by step

1. User visits Site A. Datafly.js generates an anonymous ID for the visitor and checks whether cross-domain resolution has already been performed for this browser.
2. First visit: redirect to the Identity Hub. Datafly.js redirects to the customer’s Identity Hub endpoint with the current anonymous ID and a return URL.
3. Hub resolves the canonical identity. The hub looks up the anonymous ID against its identity store. If the visitor has never been seen before, the current ID becomes their canonical identity. If a different domain in the same group has already registered the same visitor, the hub returns the existing canonical ID.
4. Hub redirects back to Site A with a short-lived, signed identity token in the URL.
5. Datafly.js processes the token. It validates the token, applies the canonical identity to the local visitor, and removes the token parameter from the URL so it doesn’t appear in analytics or bookmarks.
6. Resolution is cached so the hub redirect won’t happen again for this browser.

When the same user later visits Site B, the same flow occurs. The hub recognises the user (via its own first-party cookie on the hub subdomain) and returns the same canonical ID, linking both domains.

Token security

The identity token returned from the Hub is short-lived and signed. It contains only the canonical identity and an expiration timestamp — no PII, no session secrets. Tokens expire within seconds to prevent replay, and the token parameter is removed from the URL after processing. Signal validates the token server-side on the first event from the new domain.

Configuration

Source configuration

Enable cross-domain identity in your source configuration:

{
  "cross_domain": {
    "enabled": true,
    "hub_url": "https://id.company.com/resolve",
    "linked_domains": ["brand-a.com", "brand-b.com", "shop.brand-a.com"]
  }
}

Datafly.js init

When using the npm package, pass the cross-domain configuration to init():

import datafly from '@datafly/collector';
 
datafly.init({
  pipelineKey: 'dk_live_abc123',
  endpoint: 'https://data.brand-a.com',
  crossDomain: {
    hubUrl: 'https://id.company.com/resolve',
    linkedDomains: ['brand-a.com', 'brand-b.com'],
  },
});

When using the script tag method, cross-domain configuration is loaded from the source configuration on the server. No additional client-side configuration is needed.

Identity Hub setup

The Identity Hub requires:

1. A shared subdomain — e.g., id.company.com — that is accessible from all linked domains
2. DNS configuration — a DNS record for the hub subdomain (your account team will provide the exact target during onboarding)
3. SSL certificate — valid TLS certificate for the hub subdomain (provisioned automatically)

The hub sets its own first-party cookie on id.company.com to recognise returning users across domains.

Configuration reference

Redirect behaviour

The redirect to the Identity Hub happens only once per browser. After the first resolution:

• A _df_xd_resolved flag is set in localStorage
• A _df_xd_anon_id value stores the resolved canonical ID
• Subsequent page loads skip the redirect entirely

Failure handling

Datafly.js is designed to degrade gracefully if cross-domain resolution fails:

In all failure cases, tracking continues normally with a domain-specific anonymous ID. No events are lost.

When to use cross-domain identity

Cross-domain identity is appropriate when:

• You operate multiple top-level domains that share users (e.g., brand-a.com and brand-b.com)
• You have separate domains for marketing and e-commerce (e.g., example.com and shop.example.com)
• Ad clicks land on one domain and conversions happen on another

Cross-domain identity is not needed when:

• All your sites are on subdomains of the same root domain (cookies can be shared via domain=.example.com)
• You only operate a single domain
• Users authenticate on each domain (use identify() to link identities via userId instead)