Experimentation

# The variation key becomes a Graph filter. For a visitor bucketed into "business":
query {
  _Content(
    where: { _metadata: { url: { default: { eq: "/en/" } } } }
    variation: { include: SOME, value: ["business"], includeOriginal: true }
  ) {
    items {
      _metadata { variation }   # "business", or null for the base page
    }
  }
}

// src/middleware.ts
import { createInstance, createStaticProjectConfigManager, OptimizelyDecideOption }
  from "@optimizely/optimizely-sdk/universal";

export const VARIATION_MARKER = "__v_";
const MAX_CMS_VARIATIONS = 3; // safety backstop; cms_route is the real control

// An experiment declares its target route via the cms_route variation variable.
// "" / undefined = all routes, "/*" = all, "/products/*" = prefix, "/x" = exact.
function routeMatches(pathname, cmsRoute) {
  if (!cmsRoute?.trim()) return true;
  const path = pathname.replace(/\/$/, "") || "/";
  return cmsRoute.split(",").some((raw) => {
    const entry = raw.trim();
    if (entry === "/*") return true;
    if (entry.endsWith("/*")) {
      const prefix = entry.slice(0, -2).replace(/\/$/, "") || "/";
      return path === prefix || path.startsWith(prefix + "/");
    }
    return path === (entry.replace(/\/$/, "") || "/");
  });
}

export async function middleware(request: NextRequest) {
  const response = NextResponse.next();

  // Set a stable visitor ID (not httpOnly - browser SDK reads it for bucketing events).
  const userId = request.cookies.get("optimizelyEndUserId")?.value ?? crypto.randomUUID();
  if (!request.cookies.get("optimizelyEndUserId")) {
    response.cookies.set("optimizelyEndUserId", userId, {
      maxAge: 60 * 60 * 24 * 365, sameSite: "lax", path: "/",
    });
  }

  // Skip API routes and already-rewritten paths.
  if (request.nextUrl.pathname.startsWith("/api/")) return response;
  if (request.nextUrl.pathname.includes(VARIATION_MARKER)) return response;

  // Fetch datafile with 60s edge cache (Vercel CDN caches this automatically).
  const datafile = await fetch(DATAFILE_URL, { next: { revalidate: 60 } }).then((r) => r.text());

  const client = createInstance({
    projectConfigManager: createStaticProjectConfigManager({ datafile }),
    requestHandler: noOpRequestHandler, // no HTTP needed - static config only
  });

  const ctx = client.createUserContext(userId, { device, hostname, logged_in, persona });
  const decisions = ctx.decideAll([OptimizelyDecideOption.DISABLE_DECISION_EVENT]);

  // Keep only CMS-content experiments (cms_flag) whose cms_route targets THIS path.
  // A visitor may match many experiments across the site; only the one authored on
  // the current page should be applied here - this is what keeps the cache clean.
  // Sorted by variationKey for a stable ISR cache key, then capped as a backstop.
  const activeDecisions = Object.values(decisions)
    .filter((d) => d.enabled && d.variationKey && d.variationKey !== "off")
    .filter((d) => d.variables?.cms_flag === true)
    .filter((d) => routeMatches(request.nextUrl.pathname, d.variables?.cms_route))
    .sort((a, b) => (a.variationKey as string).localeCompare(b.variationKey as string))
    .slice(0, MAX_CMS_VARIATIONS);

  if (activeDecisions.length === 0) return response;

  // Rewrite URL: /savings → /savings/__v_homepage--business
  // Each segment encodes flagKey--variationKey so the page knows which flag fired.
  // The user sees /savings in the browser - the rewrite is transparent.
  // Next.js catches each rewritten path as a separate ISR cache entry.
  const url = request.nextUrl.clone();
  const variationSuffix = activeDecisions
    .map((d) => `__v_${d.flagKey}--${d.variationKey}`)
    .join("/");
  url.pathname = url.pathname.replace(/\/$/, "") + `/${variationSuffix}`;
  return NextResponse.rewrite(url, { headers: response.headers });
}

// src/app/[[...slug]]/page.tsx
// Middleware rewrites: /savings → /savings/__v_homepage--business
//   VARIATION_MARKER = "__v_"   FLAG_VAR_SEP = "--"
// Both flagKey and variationKey are encoded in the URL segment so the page
// knows which flag to fire the bucketing event for - no extra SDK call needed.
import { VARIATION_MARKER, FLAG_VAR_SEP } from "@/middleware";

function extractVariations(slug) {
  const cleanSlug = slug?.filter((s) => !s.startsWith(VARIATION_MARKER));
  const flagVariations = slug
    ?.filter((s) => s.startsWith(VARIATION_MARKER))
    .map((s) => {
      const [flagKey, variationKey] = s.slice(VARIATION_MARKER.length).split(FLAG_VAR_SEP);
      return { flagKey, variationKey };
    }) ?? [];
  return {
    cleanSlug,
    activeVariations: flagVariations.map((fv) => fv.variationKey), // for Graph filter
    flagVariations,                                                  // for bucketing event
  };
}

async function CmsPage({ params }) {
  const { slug } = await params;
  const { cleanSlug, activeVariations, flagVariations } = extractVariations(slug);

  // Pass variation keys to Graph - same filter as always, now sourced from URL not cookies
  const variationOption = activeVariations.length > 0
    ? { variation: { include: "SOME" as const, value: activeVariations, includeOriginal: true } }
    : undefined;

  const client = getClient();
  const items = await client.getContentByPath(`/${cleanSlug.join("/")}/`, variationOption);
  const page = items.find((i) => activeVariations.includes(i._metadata?.variation)) ?? items[0];

  // Look up flagKey by the variationKey Graph actually served
  const servedVariation = page._metadata?.variation ?? null;
  const servedFlagKey = flagVariations.find((fv) => fv.variationKey === servedVariation)?.flagKey ?? null;

  return (
    <>
      <OptimizelyComponent content={page} />
      {servedFlagKey && <FxBucketingEvent flagKey={servedFlagKey} />}
    </>
  );
}

# Theoretical GraphQL generated by getContentByPath("/en/", variationFilter)
# when the user is bucketed into the "personal" variation:

query {
  _Content(
    where: {
      _metadata: { url: { default: { eq: "/en/" } } }
    }
    variation: {
      include: SOME
      value: ["personal"]
      includeOriginal: true   # always include the base - safe fallback for non-experiment users
    }
    limit: 10
  ) {
    items {
      _metadata {
        key
        version
        variation       # "personal" | null (base version)
        url { default }
      }
      ... on HomePage {
        composition { ... }
      }
    }
  }
}

# Graph returns TWO items:
#   items[0] → base homepage          (variation: null)
#   items[1] → "personal" variation   (variation: "personal")
#
# The code picks items[1] because it matches activeVariations.
# If no matching CMS variation exists, includeOriginal: true ensures
# items[0] (the base) is returned - experiment is safe to deploy before
# editors create any CMS variations.

// src/components/FxBucketingEvent.tsx
// flagKey is passed in from the page - it was encoded in the URL by middleware:
//   /savings → /savings/__v_homepage--business
// extractVariations() in page.tsx parses it back out.
// No decideAll() here - the flagKey is already known from the route.

"use client";
export function FxBucketingEvent({ flagKey }: { flagKey: string }) {
  useEffect(() => {
    const userId = getCookie("optimizelyEndUserId");
    if (!userId) return;
    void getOptimizelyBrowserClient().then((client) => {
      if (!client) return;
      const ua = navigator.userAgent;
      const device = /mobile|android|iphone|ipad/i.test(ua) ? "mobile" : "desktop";
      const persona = getCookie("demo_persona");
      // Attributes MUST mirror src/middleware.ts (which produced the served
      // variation) - including logged_in - or the impression can land on a
      // different variation than the one that was rendered.
      const ctx = client.createUserContext(userId, {
        device,
        hostname: window.location.hostname,
        logged_in: !!getCookie("demo_bucketing_id"),
        ...(persona ? { persona } : {}),
      });
      ctx?.decide(flagKey, []); // fire bucketing event for this flag only
    });
  }, [flagKey]);
  return null;
}

// src/app/[[...slug]]/page.tsx
// flagKey comes from the URL segment, not from a client-side SDK call.
// flagVariations = [{ flagKey: "homepage", variationKey: "business" }]
const { cleanSlug, activeVariations, flagVariations } = extractVariations(slug);
const servedVariation = page._metadata?.variation ?? null;
const servedFlagKey = flagVariations.find((fv) => fv.variationKey === servedVariation)?.flagKey ?? null;

return (
  <>
    <OptimizelyComponent content={page} />
    {servedFlagKey && <FxBucketingEvent flagKey={servedFlagKey} />}
  </>
);

// Server component - client and userId are resolved upstream
// (same pattern as middleware: createInstance with a 60s-cached datafile).

const userCtx = client.createUserContext(userId, attributes);

// Evaluate without firing an impression:
const decision = userCtx.decide(
  "hero_copy",
  [OptimizelyDecideOption.DISABLE_DECISION_EVENT],
);
if (!decision.enabled) return null;

// Variation will be rendered - fire the impression:
void userCtx.decide("hero_copy");

// Variables come back typed - cast to the type you expect:
const headline = decision.variables.headline as string;
const subheadline = decision.variables.subheadline as string;
return <Hero headline={headline} subheadline={subheadline} variation={decision.variationKey} />;

// Normal decision - bucketed by the visitor's anonymous userId
const userCtx = client.createUserContext(userId, attributes);
const decision = userCtx.decide("hero_copy", [DISABLE_DECISION_EVENT]);

// Account-level decision - when logged in, bucket by account ID instead.
// All seats on the same account see the same variation.
// userId is still used for analytics; only bucketing is overridden.
const accountCtx = accountId
  ? client.createUserContext(userId, {
      ...attributes,
      $opt_bucketing_id: accountId,
    })
  : null;
const accountDecision = accountCtx?.decide("hero_copy", [DISABLE_DECISION_EVENT]);