Getting Set Up With Interleaving

import { GrowthBook } from "@growthbook/growthbook";
import { interleavePlugin, interleave } from "@growthbook/growthbook/plugins";

const gb = new GrowthBook({
  apiHost: "https://cdn.growthbook.io",
  clientKey: "sdk-abc123",
  attributes: { id: user.id },
  plugins: [
    interleavePlugin({
      // Called once per interleaved impression (see Step 2)
      onExposure: (exposure) => {
        // analytics.track is just an example. You can use any event tracking system you want.
        analytics.track("Interleave Exposure", { userId: user.id, ...exposure });
      },
    }),
  ],
});
await gb.init();

// The config shape can be anything you define.
// It can then be overridden in GrowthBook as JSON and passed through.
// This is just an example:
type RankerConfig = { algorithmVersion: "v1" | "v2"; weight?: number };

const { result, trackingProps } = await interleave<Product, RankerConfig>(gb, {
  // The experiment's key in GrowthBook
  key: "search-ranking",
  // Return the ranked list for one ranker's config. Called once per ranker.
  // Can be sync or async.
  getList: (config) => rankingService.rank(query, config),
  // Used when the experiment is not in the SDK payload
  fallbackConfig: { algorithmVersion: "v1" },
  // One id per query or impression. Defaults to a UUID.
  rankingId: searchRequestId,
  // Defaults to the item itself for strings and numbers, otherwise item.id
  getItemId: (product) => product.sku,
});

render(result);

{
  timestamp: 1730200000000,       // ms since epoch
  experimentId: "search-ranking", // the experiment's tracking key
  rankingId: "9f1c...",           // this impression
  hashAttribute: "id",
  hashValue: "user_123",          // the identifier the analysis joins on
  items: [
    { itemId: "sku_1", variation: "popular",     position: 0, competitive: false },
    { itemId: "sku_2", variation: "buyers-pick", position: 1, competitive: true },
    { itemId: "sku_3", variation: "popular",     position: 2, competitive: true },
    // ...
  ]
}

// Example only. Your component and analytics call will differ.
function ResultList({ user, result, trackingProps }) {
  return result.map((item) => (
    <FeaturedProduct
      key={item.sku}
      item={item}
      onClick={() =>
        analytics.track("Click Result", {
          userId: user.id,
          item_id: item.sku, // must match what getItemId() returned in Step 1
          ...trackingProps, // experiment_id and ranking_id when interleaved
        })
      }
    />
  ));
}

SELECT
  user_id,
  event_timestamp AS timestamp,
  experiment_id   AS experiment_id,
  ranking_id      AS ranking_id,
  items           AS items
FROM interleave_exposures

SELECT
  user_id,
  timestamp,
  item_id,
  ranking_id,
  value
FROM product_clicked

{ "algorithmVersion": "v2", "weight": 0.3 }

{
  "name": "Search ranking: buyer's pick",
  "key": "search-ranking",
  "hashAttribute": "id",
  "variations": {
    "control":   { "key": "popular",     "name": "Popular",     "config": "{\"algorithm\":\"popular\"}" },
    "treatment": { "key": "buyers-pick", "name": "Buyer's pick", "config": "{\"algorithm\":\"buyers-pick\",\"weight\":0.3}" }
  },
  "datasourceId": "ds_abc123",
  "interleavingExposureQueryId": "<exposure query id>",
  "userIdType": "user_id",
  "metrics": [
    { "id": "fact__clicks", "analyses": [{ "type": "paired" }, { "type": "preference", "attribution": "exposureCount" }] },
    {
      "id": "fact__orders",
      "analyses": [{ "type": "preference", "attribution": "exposureCount" }]
    }
  ],
  "environmentSettings": { "production": { "enabled": true } }
}

import type {
  GrowthBook,
  GrowthBookClient,
  UserScopedGrowthBook,
} from "@growthbook/growthbook";

// ---------------------------------------------------------------------------
// Plugin registration
// ---------------------------------------------------------------------------

/**
 * Register once on the GrowthBook instance via `plugins: [interleavePlugin({...})]`.
 * On a multi-user `GrowthBookClient`, register on the client; it is re-applied
 * to every user-scoped instance the client creates.
 */
export function interleavePlugin(
  options?: InterleavePluginOptions,
): (gb: GrowthBook | GrowthBookClient | UserScopedGrowthBook) => void;

export type InterleavePluginOptions = {
  /**
   * Called once per interleaved impression, i.e. once per `interleave()` call
   * that actually drafted two lists. Not called on any fallback path.
   *
   * - Fire-and-forget: a sync throw or a rejected promise is caught and
   *   logged; it never blocks or fails `interleave()`.
   * - No deduplication. Reusing a `rankingId` fires it again; duplicate
   *   impressions are deduplicated during analysis.
   * - Send the payload to your warehouse as-is, with `items` kept as a JSON
   *   array in one column.
   */
  onExposure?: (exposure: InterleaveExposure) => void | Promise<void>;
};

export type InterleaveExposure = {
  /** Milliseconds since epoch. Cast to a timestamp in the exposure query. */
  timestamp: number;

  /** The experiment's tracking key, not its `key`. Should land in `experiment_id` column of exposure query. */
  experimentId: string;

  /** The impression id. Should land in `ranking_id` column of exposure query. */
  rankingId: string;

  /** Attribute name the user was diverted on, e.g. "id". Informational. */
  hashAttribute: string;

  /**
   * The hash attribute's value, stringified.
   * Informational but can be used as the identifier column in your Exposure Query as ideally
   * the identifier column is identical to this value.
   */
  hashValue: string;

  /**
   * One entry per rendered item, in rendered order. Store as a JSON array;
   * GrowthBook unnests it in SQL.
   */
  items: InterleavedItem[];
};

export type InterleavedItem = {
  /** From `getItemId`. Joins to `item_id` on engagement events. */
  itemId: string;

  /**
   * Key of the ranker credited with the item. Arbitrary for a tie (both
   * rankers wanted it); the supplying ranker for a leftover or a fill.
   */
  variation: string;

  /** 0-based slot in `result`. Recorded, not used by either analysis today. */
  position: number;

  /**
   * True only for the two items placed in a contested round. False for ties,
   * leftovers after one ranker runs out, and `maxItems` fills. Only
   * competitive items count toward results.
   */
  competitive: boolean;
};

// ---------------------------------------------------------------------------
// The call
// ---------------------------------------------------------------------------

/**
 * Replaces the call that fetches a ranked list.
 *
 * `T` is your item type. `C` is your ranker config shape. TypeScript cannot
 * infer one without the other, so pass both type arguments or neither.
 *
 * Determinism: given the same SDK payload and the same `rankingId`, the
 * returned order is identical. User diversion hashes (seed, hashAttribute
 * value); each draft round hashes (seed, rankingId, round index).
 *
 * Throws only if the FIRST ranker's `getList` throws. Every other failure
 * degrades to serving a single ranker's list (see `InterleaveResult`).
 */
export function interleave<T, C extends object = InterleaveConfig>(
  gb: GrowthBook | UserScopedGrowthBook,
  options: InterleaveOptions<T, C>,
): Promise<InterleaveResult<T>>;

/** A ranker's config. Authored in GrowthBook as JSON, handed to `getList` unchanged. */
export type InterleaveConfig = Record<string, unknown>;

export type InterleaveOptions<T, C extends object = InterleaveConfig> = {
  /**
   * The interleaving experiment's key in GrowthBook. Same character set as a
   * feature key: letters, numbers, `_ - . : |`. Immutable once created.
   */
  key: string;

  /**
   * Return the ranked list for one ranker's config. Called once per ranker,
   * concurrently, when the user is interleaved; once with a single config
   * otherwise. May be sync or async.
   *
   * Every returned item must have a non-empty id (see `getItemId`). If any
   * item has none, the SDK logs an error and serves the first ranker's list.
   *
   * Apply business rules (diversity caps, pinned items, filters) INSIDE this
   * function, before the merge. Never re-sort or re-filter `result`.
   */
  getList: (config: C) => T[] | Promise<T[]>;

  /**
   * Used when the experiment is not in the SDK payload at all: never started,
   * not enabled in this environment, SDK too old, or a ranker config that
   * failed validation server-side. This is the one case with no client-side
   * signal beyond `inExperiment === false`.
   */
  fallbackConfig: C;

  /**
   * One id per impression (one search, one page load). Seeds the draft, so
   * reusing it replays the same list; pass it down from server to client to
   * keep SSR and hydration consistent. Pagination continues the same id;
   * a filter change is a new id. Defaults to a UUID.
   */
  rankingId?: string;

  /**
   * Set false to skip interleaving for this call and serve the first ranker,
   * e.g. when the user picked an explicit sort. Default true.
   */
  enabled?: boolean;

  /**
   * Stable id for an item. Must match the `item_id` on engagement events.
   * Defaults to the item itself for strings and numbers, otherwise `item.id`.
   */
  getItemId?: (item: T) => string;

  /**
   * Caps the returned list on every exit path, interleaved or not. If a cap
   * leaves a single slot, it is filled with a non-competitive item.
   */
  maxItems?: number;
};

export type InterleaveResult<T> = {
  /** The list to render. Drafted when interleaved, else one ranker's list. */
  result: T[];

  /** True only when two lists were drafted and an exposure was fired. */
  inExperiment: boolean;

  /**
   * When not interleaved, the key of the ranker whose config was used:
   *   - targeting miss / outside coverage / hash attribute missing -> first ranker
   *   - `enabled: false` or experiments disabled on the instance   -> first ranker
   *   - second ranker threw                                        -> first ranker
   *   - item without an id                                         -> first ranker
   *   - experiment missing from payload (`fallbackConfig` used)    -> undefined
   * Undefined when interleaved.
   */
  variation?: string;

  /** The impression id used, whether supplied or generated. */
  rankingId: string;

  /**
   * Spread into every engagement event for this impression alongside
   * `item_id`. Empty object when not interleaved, so it is always safe to
   * spread.
   */
  trackingProps: InterleaveTrackingProps;
};

export type InterleaveTrackingProps = {
  /** The experiment's tracking key. Matches `experiment_id` in exposures. */
  experiment_id?: string;
  /** Required on events for paired analysis. */
  ranking_id?: string;
};