Link Decoration

When your business operates sites on different top-level domains (e.g. brand.com and brand-shop.co.uk), the Identity Hub redirect flow is vulnerable to Safari 17+ bounce tracking protection — browsers that detect a domain is only visited as part of redirect chains will delete its cookies after 7 days. Link Decoration provides an alternative cross-domain identity mechanism that is immune to this protection.

The Problem with Hub Redirects

The Identity Hub works by redirecting the visitor through id.company.com to transfer the anonymous ID. Safari 17+ and other privacy-focused browsers track these redirect-only domains and classify them as bounce trackers:

site-a.com → id.company.com (redirect) → site-b.com

Safari detects:
  - id.company.com is only ever visited as a redirect
  - Classifies it as a bounce tracker
  - Deletes its cookies after 7 days of no direct interaction

After 7 days without a direct visit to id.company.com, the hub loses its _dfid_hub cookie and can no longer transfer identities.

The Solution: Direct Link Decoration

Link Decoration bypasses the hub entirely. Instead of redirecting through a third domain, the identity travels directly in the link from one site to another via an encrypted _dfl parameter:

site-a.com → site-b.com?_dfl={encrypted_token}

No intermediate redirect. No bounce tracker classification.

How It Works

Outbound: Decorating Links

When Link Decoration is enabled, Datafly.js uses event delegation on document to intercept clicks on <a> elements whose href matches a configured target domain. On click, it appends an encoded _dfl parameter to the link’s href before the browser follows the navigation:

<!-- Original link -->
<a href="https://brand-shop.co.uk/products/headphones">Buy now</a>
 
<!-- On click, Datafly.js appends the decoration token -->
<!-- href becomes: https://brand-shop.co.uk/products/headphones?_dfl=eyJ... -->

Event delegation (a single click listener on document with useCapture: true) is used instead of attaching listeners to individual <a> elements. This means dynamically added links (e.g. from SPA rendering, lazy-loaded content, or CMS widgets) are automatically covered without needing a MutationObserver.

The _dfl parameter is a base64url-encoded JSON payload with short field names to minimise URL length:

{
  "a": "f47ac10b-58cc-4372-a567-0d02b2c3d479",
  "e": 1741877700,
  "o": "https://brand.com",
  "k": "dk_live_abc123..."
}

The token has a 5-minute TTL — longer than the hub token’s 60 seconds, since the link may sit on the page for a while before the user clicks it. The link is only decorated at click time, not when the page renders, so the 5-minute window starts from the moment of the click.

Inbound: Receiving the Identity

When a visitor arrives on the destination site with a _dfl parameter:

1. Datafly.js detects _dfl in the URL (checks window.location.search)

2. POSTs the token to the Ingestion Gateway for server-side validation:
   POST https://data.brand-shop.co.uk/v1/identity/decorate/validate
   {
     "token": "eyJ...",
     "pipeline_key": "dk_live_abc123..."
   }

3. Gateway decodes the token, validates:
   → Pipeline key matches a known org
   → TTL has not expired (5-minute window)
   → Origin is a configured cross-domain source

4. Returns the anonymous_id:
   { "anonymous_id": "f47ac10b-58cc-4372-a567-0d02b2c3d479" }

5. Datafly.js adopts the resolved ID as its own anonymous_id
   → Stores in cookie + localStorage

6. URL is cleaned via history.replaceState (removes _dfl parameter)
   → The token no longer appears in the address bar, bookmarks, or analytics

The visitor now has the same _dfid on both sites, and the _dfl parameter is no longer visible in the URL.

Programmatic API

For single-page applications where navigation happens via JavaScript (e.g. router.push(), window.location), Datafly.js provides a programmatic API:

// Decorate a URL before navigating
const url = datafly.decorateUrl('https://brand-shop.co.uk/checkout')
// Returns: "https://brand-shop.co.uk/checkout?_dfl=eyJ..."
 
window.location.href = url

Configuration

Link Decoration is configured as part of the organisation’s cross-domain identity settings. It works independently of the mode setting — you can use link decoration with either oidc or legacy mode for the hub flow:

{
  "cross_domain": {
    "enabled": true,
    "mode": "oidc",
    "hub_url": "https://id.company.com",
    "domains": ["brand.com", "brand-shop.co.uk", "brand-blog.com"],
    "link_decoration": {
      "enabled": true,
      "auto_decorate": true,
      "target_domains": ["brand-shop.co.uk", "brand-blog.com"]
    }
  }
}

When auto_decorate is false, only the programmatic API (datafly.decorateUrl()) is available — no automatic link interception occurs. This is useful for SPAs that handle all navigation programmatically.

Domain matching includes subdomains: a target of brand-shop.co.uk also matches www.brand-shop.co.uk and checkout.brand-shop.co.uk.

Comparison: Link Decoration vs Identity Hub Redirect

When to Use Each

These mechanisms are not mutually exclusive. Most deployments use Link Decoration alongside the Identity Hub:

• Link Decoration handles the common case of users clicking between your sites. Because there is no intermediate redirect, it is immune to Safari’s bounce tracking protection and provides the most seamless user experience.
• Identity Hub (OIDC flow) handles the first-visit case where the user arrives directly (e.g. via search engine, email link, or bookmark). It can resolve identity even without a prior click from a source site.
• Server-side identity graph provides deterministic linking when users authenticate on multiple sites via identify().

Security

The _dfl token is protected by multiple layers:

• Server-validated — The token is sent to /v1/identity/decorate/validate on the Ingestion Gateway for server-side validation. The client never decodes or trusts the token directly.
• Pipeline key bound — The token includes the pipeline key (k field), which the server uses to look up the org context and validate that the origin is a configured cross-domain source.
• Short-lived — 5-minute TTL. Tokens are rejected after expiry. The TTL is longer than the hub redirect token (60s) because users may not click immediately, but still short enough to limit replay risk.
• Origin-validated — The origin (o field) is included in the token payload and validated on the receiving side against the org’s configured domain list.
• URL-cleaned — The _dfl parameter is removed from the URL via history.replaceState() after processing, so it does not persist in bookmarks, browser history, or analytics tools.
• Click-time generation — Tokens are generated at the moment of click, not at page load. This minimises the window of validity.