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/lib/optimizely/requestVariations.ts - a per-request store
const store = cache(() => ({ flagVariations: [] as FlagVariation[] }));
export function setRequestFlagVariations(v: FlagVariation[]) { store().flagVariations = v; }
export function edgeVariationFor(flagKey: string) {
  return store().flagVariations.find((fv) => fv.flagKey === flagKey)?.variationKey ?? null;
}

// src/app/[[...slug]]/page.tsx - the catch-all records the middleware's __v_ segments
const { flagVariations } = extractVariations(slug);
setRequestFlagVariations(flagVariations);

// VariationContainerBlock - a server component
const edgeKey = edgeVariationFor(flagKey);
if (edgeKey !== null) {
  // Middleware decided this flag: render that variation only, no flicker
  const shown = variations.find((v) => v.variationKey === edgeKey) ?? variations[0];
  return <>{render(shown)}<FxBucketingEvent flagKey={flagKey} /></>;
}
// No segment: server-render every variation, let the browser pick one
return (
  <VariationContainerClient
    flagKey={flagKey}
    variants={variations.map((v) => ({ key: v.variationKey, node: render(v) }))}
  />
);

// VariationContainerClient - "use client"
const decision = useFxDecision(flagKey);   // null until the datafile loads
const shown = variants.find((v) => v.key === decision?.variationKey) ?? variants[0];

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

export const VARIATION_MARKER = "__v_";   // arbitrary - pick anything URL-safe
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 decision 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: /pricing → /pricing/__v_checkout_layout--single_step
  // 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 });
}

// The catch-all content route
// Middleware rewrites: /pricing → /pricing/__v_checkout_layout--single_step
// Both flagKey and variationKey are encoded in the URL segment so the page
// knows which flag to fire the decision event for - no extra SDK call needed.
// Keep parsing in one module, shared with middleware:
// a malformed segment parses to null instead of an undefined variation key.
import { isVariationSegment, parseVariationSegment } from "@/lib/optimizely/variationPath";

function extractVariations(slug) {
  const cleanSlug = slug?.filter((s) => !isVariationSegment(s));
  const flagVariations = slug
    ?.map(parseVariationSegment)
    .filter((fv) => fv !== null) ?? [];
  return {
    cleanSlug,
    activeVariations: flagVariations.map((fv) => fv.variationKey), // for Graph filter
    flagVariations,                                                  // for decision 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.
  // stored: false opts out of Graph stored queries, which would otherwise freeze the
  // variation value from the first request and serve it to every visitor.
  const variationOption = activeVariations.length > 0
    ? {
        variation: { include: "SOME" as const, value: activeVariations, includeOriginal: true },
        stored: false,
      }
    : 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 && <DecisionEvent 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.

// The component that fires the decision event, client-side
// flagKey is passed in from the page - it was encoded in the URL by middleware:
//   /pricing → /pricing/__v_checkout_layout--single_step
// The content route parses it back out.
// No decideAll() here - the flagKey is already known from the route.

"use client";
export function DecisionEvent({ 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("persona");
      // Attributes MUST mirror what middleware used (it produced the served
      // variation) - including logged_in - or the decision event 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("bucketing_id"),
        ...(persona ? { persona } : {}),
      });
      ctx?.decide(flagKey, []); // fire decision event for this flag only
    });
  }, [flagKey]);
  return null;
}

// The catch-all content route
// 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 && <DecisionEvent 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 a decision event:
const decision = userCtx.decide(
  "checkout_layout",
  [OptimizelyDecideOption.DISABLE_DECISION_EVENT],
);
if (!decision.enabled) return null;

// Variation will be rendered - fire the decision event:
void userCtx.decide("checkout_layout");

// 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("checkout_layout", [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("checkout_layout", [DISABLE_DECISION_EVENT]);