Hydrate affiliate details in a cached theme

Affiliate hydration lets one cacheable storefront page work for both attributed and anonymous visitors. Your Liquid template emits a stable placeholder. The FairShare SDK replaces that placeholder in the browser after it resolves the visitor’s affiliate. Use the placeholder that matches where the value appears:

Context	Use
Visible text	A `<fluid-affiliate-*>` element
A complete HTML attribute	A `data-fluid-affiliate-*` marker
A username inside a URL	The `{{ username }}` Liquid value

Render affiliate text

Fluid provides five affiliate elements:

Element	Value
`<fluid-affiliate-name>`	Display name
`<fluid-affiliate-email>`	Email address
`<fluid-affiliate-initials>`	Initials
`<fluid-affiliate-avatar>`	Avatar URL as text
`<fluid-affiliate-my-site-url>`	Personal site URL as text

Put fallback text inside an element. Fluid keeps that text when the field is empty during the initial affiliate resolution.

<p>
  Shop with <fluid-affiliate-name>our team</fluid-affiliate-name>
</p>

These elements render in the light DOM, so your theme styles apply normally.

Hydrate HTML attributes

Use a data marker when the affiliate value needs to become an HTML attribute:

<img
  data-fluid-affiliate-src="avatar"
  data-fluid-affiliate-alt="name"
  alt="Your shopping guide"
/>

<a data-fluid-affiliate-href="my_site_url">
  Visit your guide's site
</a>

The supported markers are:

Marker	Result
`data-fluid-affiliate="<field>"`	Sets `textContent`
`data-fluid-affiliate-src="<field>"`	Sets `src`
`data-fluid-affiliate-href="<field>"`	Sets `href`
`data-fluid-affiliate-alt="<field>"`	Sets `alt`

<field> can be name, email, initials, avatar, my_site_url, or username. For my_site_url, you can set data-fluid-affiliate-base-url on the same element to use a different origin:

<a
  data-fluid-affiliate-href="my_site_url"
  data-fluid-affiliate-base-url="https://shop.example.com"
>
  Visit your guide's site
</a>

Use a data marker for eagerly loaded attributes such as image src. A browser can request a literal placeholder before hydration if you put one directly in src.

Put an affiliate username in a URL

Use {{ username }} when the affiliate username is one part of a link or form URL:

<a href="/{{ username }}/shop">Shop</a>
<form action="/{{ username }}/join" method="get">
  <button type="submit">Join</button>
</form>

Fluid renders a stable sentinel into the cacheable page. The SDK replaces every sentinel with the resolved username. Anonymous visitors fall back to home. Use the sentinel in attributes that the browser follows after user interaction, such as href and action. For an eagerly fetched image source, use data-fluid-affiliate-src; the hydration API does not provide generic srcset or poster markers.

Show content conditionally

Liquid conditions run before the browser resolves the affiliate. Use hydration visibility markers for affiliate-dependent content:

<aside
  data-fluid-affiliate-show-if="affiliate"
  style="display: none"
>
  Shopping with
  <fluid-affiliate-name>your guide</fluid-affiliate-name>
</aside>

<aside data-fluid-affiliate-hide-if="affiliate">
  Shop with the Fluid community
</aside>

Use affiliate to test whether any affiliate resolved. You can also test a specific field such as avatar or email. data-fluid-affiliate-show-if requires every comma-separated token to have a value. data-fluid-affiliate-hide-if hides the element when any listed token has a value. If both markers are present, the hide condition wins. Pre-hide show-if content with style="display: none" to prevent a flash before hydration. If an SPA changes affiliates without replacing the element, do not rely on hide-if alone to reveal content that it previously hid. Re-render that conditional region when the attribution changes.

React to hydrated content

Hydration happens after the initial HTML is parsed. If your script measures or copies hydrated content, observe the element instead of reading it immediately:

<div
  id="affiliate-banner"
  data-fluid-affiliate-show-if="affiliate"
  style="display: none"
>
  <fluid-affiliate-name></fluid-affiliate-name>
</div>

<script>
  const banner = document.getElementById("affiliate-banner");

  const syncBannerHeight = () => {
    const visible = window.getComputedStyle(banner).display !== "none";
    document.documentElement.style.setProperty(
      "--affiliate-banner-height",
      visible ? `${banner.offsetHeight}px` : "0px",
    );
  };

  new MutationObserver(syncBannerHeight).observe(banner, {
    attributes: true,
    attributeFilter: ["style"],
    childList: true,
    subtree: true,
    characterData: true,
  });

  syncBannerHeight();
</script>

There is no public rescanForSentinels() method. Hydration reapplies when FairShare publishes an affiliate settings change and scans the current document again. In an SPA, render the destination content before that settings update. Prefer the custom elements for text that must continue reacting after the affiliate changes.

Test your theme

Test both attributed and anonymous paths:

Open a supported storefront path with an affiliate username.
Confirm text, images, links, and conditional regions resolve.
Open the equivalent path with home.
Confirm fallback content remains usable and no affiliate-only region flashes.
Test a second affiliate to catch values that were copied only once.
Check keyboard focus, image alternative text, and screen-reader output after hydration.

See supported storefront paths for route patterns and FairShare components for the SDK component inventory.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Hydrate affiliate details in a cached theme

Render affiliate text

Hydrate HTML attributes

Put an affiliate username in a URL

Show content conditionally

React to hydrated content

Test your theme

​Render affiliate text

​Hydrate HTML attributes

​Put an affiliate username in a URL

​Show content conditionally

​React to hydrated content

​Test your theme

Render affiliate text

Hydrate HTML attributes

Put an affiliate username in a URL

Show content conditionally

React to hydrated content

Test your theme