feat: randomize mobile feed ad positions via adJitter

Add optional `adJitter` to `FeedAdTemplate` so ad positions can vary
deterministically per feed while keeping average cadence unchanged.
Jitter only activates when the `feed_ad_template` GrowthBook flag sets
`adJitter` under the `default` key, so only the mobile/1-column list
layout is affected.

- Extend FeedAdTemplate with optional adJitter
- Pure getAdSlotIndex helper with seeded FNV-1a hash keyed off feedQueryKey
- Clamp jitter to floor((adRepeat - 1) / 2) so consecutive ads never
  overlap or reorder
- Unit tests for parity, window bounds, determinism, and clamp

Made-with: Cursor

Author: nimrodkra

packages/shared/src/hooks/useFeed.spec.ts

@@ -0,0 +1,106 @@
+import { getAdSlotIndex } from './useFeed';
+
+describe('getAdSlotIndex', () => {
+  const seed = '["feed","my-feed"]';
+
+  it('matches modulo math when adJitter is 0', () => {
+    const adStart = 2;
+    const adRepeat = 5;
+    const positions: number[] = [];
+    for (let index = 0; index < 40; index += 1) {
+      const n = getAdSlotIndex({ index, adStart, adRepeat, seed });
+      if (n !== undefined) {
+        positions.push(index);
+      }
+    }
+    expect(positions).toEqual([2, 7, 12, 17, 22, 27, 32, 37]);
+  });
+
+  it('returns undefined for indices before the first possible ad slot', () => {
+    const adStart = 2;
+    const adRepeat = 5;
+    const adJitter = 2;
+    expect(
+      getAdSlotIndex({ index: -1, adStart, adRepeat, adJitter, seed }),
+    ).toBeUndefined();
+  });
+
+  it('keeps jittered positions inside the expected window per slot', () => {
+    const adStart = 2;
+    const adRepeat = 5;
+    const adJitter = 2;
+    const windows = new Map<number, number[]>();
+    for (let index = 0; index < 60; index += 1) {
+      const n = getAdSlotIndex({
+        index,
+        adStart,
+        adRepeat,
+        adJitter,
+        seed,
+      });
+      if (n !== undefined) {
+        const list = windows.get(n) ?? [];
+        list.push(index);
+        windows.set(n, list);
+      }
+    }
+    Array.from(windows.entries()).forEach(([n, hits]) => {
+      expect(hits).toHaveLength(1);
+      const center = adStart + n * adRepeat;
+      expect(hits[0]).toBeGreaterThanOrEqual(center - adJitter);
+      expect(hits[0]).toBeLessThanOrEqual(center + adJitter);
+    });
+    expect(windows.size).toBeGreaterThanOrEqual(10);
+  });
+
+  it('is deterministic for the same seed and slot index', () => {
+    const args = {
+      adStart: 2,
+      adRepeat: 5,
+      adJitter: 2,
+      seed,
+    };
+    const runA: Array<number | undefined> = [];
+    const runB: Array<number | undefined> = [];
+    for (let index = 0; index < 40; index += 1) {
+      runA.push(getAdSlotIndex({ index, ...args }));
+      runB.push(getAdSlotIndex({ index, ...args }));
+    }
+    expect(runA).toEqual(runB);
+  });
+
+  it('produces different positions for different seeds', () => {
+    const args = { adStart: 2, adRepeat: 5, adJitter: 2 };
+    const collect = (s: string): number[] => {
+      const hits: number[] = [];
+      for (let index = 0; index < 60; index += 1) {
+        if (getAdSlotIndex({ index, ...args, seed: s }) !== undefined) {
+          hits.push(index);
+        }
+      }
+      return hits;
+    };
+    const seedA = '["feed","user-a"]';
+    const seedB = '["feed","user-b"]';
+    expect(collect(seedA)).not.toEqual(collect(seedB));
+  });
+
+  it('clamps jitter so consecutive ads never overlap or reorder', () => {
+    const adStart = 2;
+    const adRepeat = 5;
+    const adJitter = 100;
+    const hits: number[] = [];
+    for (let index = 0; index < 200; index += 1) {
+      if (
+        getAdSlotIndex({ index, adStart, adRepeat, adJitter, seed }) !==
+        undefined
+      ) {
+        hits.push(index);
+      }
+    }
+    expect(hits.length).toBeGreaterThan(5);
+    for (let i = 1; i < hits.length; i += 1) {
+      expect(hits[i]).toBeGreaterThan(hits[i - 1]);
+    }
+  });
+});

packages/shared/src/hooks/useFeed.ts

@@ -150,6 +150,50 @@ export interface UseFeedOptionalParams<T> {
   onEmptyFeed?: () => void;
 }
 
+/* eslint-disable no-bitwise -- intentional bitwise ops for FNV-1a hash */
+const hashSeed = (key: string, n: number): number => {
+  let h = 2166136261 >>> 0;
+  const s = `${key}:${n}`;
+  for (let i = 0; i < s.length; i += 1) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h;
+};
+/* eslint-enable no-bitwise */
+
+export const getAdSlotIndex = ({
+  index,
+  adStart,
+  adRepeat,
+  adJitter = 0,
+  seed,
+}: {
+  index: number;
+  adStart: number;
+  adRepeat: number;
+  adJitter?: number;
+  seed: string;
+}): number | undefined => {
+  if (adRepeat <= 0) {
+    return undefined;
+  }
+  const safeJitter = Math.max(
+    0,
+    Math.min(adJitter, Math.floor((adRepeat - 1) / 2)),
+  );
+  if (index < adStart - safeJitter) {
+    return undefined;
+  }
+  const n = Math.max(0, Math.round((index - adStart) / adRepeat));
+  const offset =
+    safeJitter === 0
+      ? 0
+      : (hashSeed(seed, n) % (safeJitter * 2 + 1)) - safeJitter;
+  const pos = adStart + n * adRepeat + offset;
+  return pos === index ? n : undefined;
+};
+
 export default function useFeed<T>(
   feedQueryKey: QueryKey,
   pageSize: number,
@@ -318,21 +362,20 @@ export default function useFeed<T>(
         adTemplate?.adStart ??
         featureFeedAdTemplate.defaultValue.default.adStart;
       const adRepeat = adTemplate?.adRepeat ?? pageSize + 1;
+      const adJitter = adTemplate?.adJitter ?? 0;
+
+      const adPage = getAdSlotIndex({
+        index,
+        adStart,
+        adRepeat,
+        adJitter,
+        seed: JSON.stringify(feedQueryKey),
+      });
 
-      const adIndex = index - adStart; // 0-based index from adStart
-
-      // if adIndex is negative, it means we are not supposed to show ads yet based on adStart
-      if (adIndex < 0) {
-        return undefined;
-      }
-      const adMatch = adIndex % adRepeat === 0; // should ad be shown at this index based on adRepeat
-
-      if (!adMatch) {
+      if (adPage === undefined) {
         return undefined;
       }
 
-      const adPage = adIndex / adRepeat; // page number for ad
-
       if (isLoading) {
         return createPlaceholderItem(adPage);
       }
@@ -365,8 +408,10 @@ export default function useFeed<T>(
       isLoading,
       adTemplate?.adStart,
       adTemplate?.adRepeat,
+      adTemplate?.adJitter,
       adsUpdatedAt,
       pageSize,
+      feedQueryKey,
     ],
   );
 

packages/shared/src/lib/feed.ts

@@ -274,6 +274,7 @@ export const getFeedName = (
 export type FeedAdTemplate = {
   adStart: number;
   adRepeat?: number;
+  adJitter?: number;
 };
 
 export function usePostLogEvent() {