How to add feature flags and experiments to an Angular app

{
  "defaultTemplate": "kanban",
  "showTemplateGallery": true
}

export const environment = {
  production: true,
  amplitudeApiKey: 'your-project-api-key',
  amplitudeDeploymentKey: 'your-client-deployment-key',
};

export const environment = {
  production: false,
  amplitudeApiKey: 'your-project-api-key',
  amplitudeDeploymentKey: 'your-client-deployment-key',
};

// Resolves to true once initAll has finished in the browser, or false
// if analytics is off. Nothing awaits it on the server.
let markReady: (ok: boolean) => void = () => {};
export const amplitudeReady = new Promise<boolean>((resolve) => {
  markReady = resolve;
});

export function setAmplitudeReady(init: Promise<unknown> | null): void {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error: unknown) => {
      console.warn('[amplitude] initAll failed', error);
      markReady(false);
    },
  );
}

// Keep lines other Angular pages added here: pathOnly page views
// (/build/angular-web-analytics), masking (/build/angular-session-replay),
// and the webExperiment.plugin() block (/build/angular-web-experiment).
import * as amplitude from '@amplitude/unified';
import { environment } from '../environments/environment';
import { setAmplitudeReady } from './amplitude-ready';

export function initAmplitude(): void {
  if (!environment.amplitudeApiKey) {
    console.warn('amplitudeApiKey is not set; analytics is off.');
    setAmplitudeReady(null);
    return;
  }

  // Flags wait for this promise before they read from the SDK.
  setAmplitudeReady(
    amplitude.initAll(environment.amplitudeApiKey, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
      },
      sessionReplay: {
        // Every session while you build; about 1% in production.
        sampleRate: environment.production ? 0.01 : 1,
        debugMode: !environment.production,
        // From /build/angular-session-replay. Keep your masking rules when you paste this file.
        privacyConfig: {
          maskSelector: ['[data-amp-mask]'],
          blockSelector: ['[data-amp-block]'],
          unmaskSelector: ['[data-amp-unmask]'],
        },
      },
      experiment: {
        // The client deployment key from step 1.
        deploymentKey: environment.amplitudeDeploymentKey,
        // Default is 10 seconds. Fall back to the current UI sooner.
        fetchTimeoutMillis: 3000,
        // Only the component that shows a variant sends its exposure (step 5).
        automaticExposureTracking: false,
      },
    }),
  );
}

import {
  Injectable,
  PLATFORM_ID,
  Signal,
  afterNextRender,
  effect,
  inject,
  signal,
} from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import * as amplitude from '@amplitude/unified';
import { amplitudeReady } from './amplitude-ready';

export type FlagState = { value: string | null; payload: unknown };
type FetchUser = { user_properties?: Record<string, string> };

@Injectable({ providedIn: 'root' })
export class FlagsService {
  private readonly isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
  private readonly settled = signal(0);
  private generation = 0;

  // Goes up by one each time a fetch settles. 0 means the first fetch
  // hasn't settled yet.
  readonly version = this.settled.asReadonly();

  async refetch(user?: FetchUser): Promise<void> {
    if (!this.isBrowser) return;
    const generation = ++this.generation;
    try {
      // experiment() is undefined until initAll has finished.
      if (await amplitudeReady) {
        // On failure or timeout the SDK returns and retries in the background.
        await amplitude.experiment()?.fetch(user);
      }
    } finally {
      // Only the newest fetch updates components, so a slow anonymous
      // fetch can't overwrite the signed-in result.
      if (generation === this.generation) this.settled.update((v) => v + 1);
    }
  }
}

// Reads a browser-fetched flag in the component that shows it and sends
// an exposure once it renders. Call it from a field initializer.
export function injectFlag(flagKey: string): Signal<FlagState | undefined> {
  const flags = inject(FlagsService);
  const state = signal<FlagState | undefined>(undefined);

  // afterNextRender never runs on the server.
  const rendered = signal(false);
  afterNextRender(() => rendered.set(true));

  let lastExposure: string | undefined;

  effect(() => {
    if (!rendered() || flags.version() === 0) return;

    const experiment = amplitude.experiment();
    const variant = experiment?.variant(flagKey);
    const value = variant?.value ?? null;
    state.set({ value, payload: variant?.payload });

    // No variant means the user isn't in the rollout. An exposure without
    // a variant would remove them from the experiment, so send nothing.
    if (!value) return;

    // Skips a repeat exposure when a fetch settles without changing the
    // identity or the variant.
    const key = `${amplitude.getUserId() ?? ''}|${amplitude.getDeviceId() ?? ''}|${value}`;
    if (key === lastExposure) return;
    lastExposure = key;
    experiment?.exposure(flagKey);
  });

  return state.asReadonly();
}

import { Injectable, PLATFORM_ID, computed, effect, inject } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import * as amplitude from '@amplitude/unified';
import { AuthService } from './auth.service';
import { FlagsService } from './flags.service';

@Injectable({ providedIn: 'root' })
export class AmplitudeIdentityService {
  private readonly auth = inject(AuthService);
  private readonly flags = inject(FlagsService);
  private readonly isBrowser = isPlatformBrowser(inject(PLATFORM_ID));

  // Only the ID and plan matter. A new user object with the same
  // values doesn't trigger another Identify or fetch.
  private readonly identity = computed(
    () => {
      const user = this.auth.user();
      return user ? { id: user.id, plan: user.plan ?? 'unknown' } : null;
    },
    { equal: (a, b) => a?.id === b?.id && a?.plan === b?.plan },
  );

  constructor() {
    // Angular runs effects during server rendering too.
    if (!this.isBrowser) return;

    effect(() => {
      const identity = this.identity();

      if (!identity) {
        // Anonymous or signed out: keep the device ID and fetch for it.
        // Reset only from your sign-out method.
        void this.flags.refetch();
        return;
      }

      // Amplitude drops IDs shorter than 5 characters. Use the same
      // string your backend sends as user_id.
      amplitude.setUserId(`user-${identity.id}`);

      const identify = new amplitude.Identify();
      identify.set('plan', identity.plan);
      amplitude.identify(identify);

      // Pass plan with the request, so targeting sees it on this evaluation.
      void this.flags.refetch({ user_properties: { plan: identity.plan } });
    });
  }
}

// Keep lines other Angular pages added here: the getEngagement import and
// getEngagement()?.gs.closeAll() before reset() (/build/angular-guides-surveys).
import { Injectable, inject, signal } from '@angular/core';
import * as amplitude from '@amplitude/unified';
import { FlagsService } from './flags.service';

export interface User {
  id: string;
  plan?: string;
}

// Stand-in for your auth. Replace the bodies with your own logic.
@Injectable({ providedIn: 'root' })
export class AuthService {
  private readonly flags = inject(FlagsService);
  readonly user = signal<User | null>(null);

  signIn(user: User): void {
    // ... your sign-in logic
    this.user.set(user);
  }

  async signOut(): Promise<void> {
    // ... your sign-out logic
    this.user.set(null);
    // Clears the user ID and issues a new device ID for the next person.
    amplitude.reset();
    // Drops the previous user's variants.
    amplitude.experiment()?.clear();
    // Fetches for the new device, even if the identity effect already ran.
    void this.flags.refetch();
  }
}

export const TEMPLATES: string[] = ['blank', 'kanban', 'roadmap'];

export type NewProjectConfig = { defaultTemplate: string; showGallery: boolean };

type NewProjectPayload = { defaultTemplate?: unknown; showTemplateGallery?: unknown };

// Only the "on" variant carries the new settings. Validate the payload
// and keep the current defaults for anything missing or unexpected.
export function newProjectConfig(
  variant: { value: string | null; payload?: unknown } | undefined,
): NewProjectConfig {
  const payload = (variant?.value === 'on' ? variant.payload : undefined) as
    | NewProjectPayload
    | undefined;
  const candidate = payload?.defaultTemplate;
  return {
    defaultTemplate:
      typeof candidate === 'string' && TEMPLATES.includes(candidate) ? candidate : 'blank',
    showGallery: payload?.showTemplateGallery === true,
  };
}

export function sameConfig(a?: NewProjectConfig, b?: NewProjectConfig): boolean {
  return a?.defaultTemplate === b?.defaultTemplate && a?.showGallery === b?.showGallery;
}

import { Component, input, linkedSignal } from '@angular/core';
import * as amplitude from '@amplitude/unified';
import { TEMPLATES, type NewProjectConfig } from './new-project-config';

@Component({
  selector: 'app-new-project-form',
  template: `
    @if (config().showGallery) {
      <fieldset>
        <legend>Start from a template</legend>
        @for (t of templates; track t) {
          <label>
            <input
              type="radio"
              name="template"
              [value]="t"
              [checked]="template() === t"
              (change)="template.set(t)"
            />
            {{ t }}
          </label>
        }
      </fieldset>
    } @else {
      <select #picker (change)="template.set(picker.value)">
        @for (t of templates; track t) {
          <option [value]="t" [selected]="template() === t">{{ t }}</option>
        }
      </select>
    }
    <button type="button" (click)="create()">Create project</button>
  `,
})
export class NewProjectForm {
  readonly config = input.required<NewProjectConfig>();
  protected readonly templates = TEMPLATES;

  // Starts at the variant's default and resets if the config changes.
  protected readonly template = linkedSignal(() => this.config().defaultTemplate);

  protected create(): void {
    // ... your create logic

    amplitude.track('Project Created', { template: this.template() });
  }
}

import { Component, computed } from '@angular/core';
import { injectFlag } from '../flags.service';
import { newProjectConfig, sameConfig } from './new-project-config';
import { NewProjectForm } from './new-project-form';

@Component({
  selector: 'app-new-project',
  imports: [NewProjectForm],
  template: `
    @if (config(); as cfg) {
      <app-new-project-form [config]="cfg" />
    } @else {
      <div aria-busy="true" style="min-height: 320px"></div>
    }
  `,
})
export class NewProject {
  private readonly flag = injectFlag('new-project-flow');

  // undefined until the first fetch settles. A later fetch with the same
  // settings keeps the user's template choice.
  protected readonly config = computed(
    () => {
      const flag = this.flag();
      return flag ? newProjectConfig(flag) : undefined;
    },
    { equal: sameConfig },
  );
}

npm install @amplitude/experiment-node-server

import { Experiment } from '@amplitude/experiment-node-server';

type LocalClient = ReturnType<typeof Experiment.initializeLocal>;
export type ServerVariants = ReturnType<LocalClient['evaluateV2']>;
export type ExperimentUser = {
  user_id?: string;
  device_id?: string;
  user_properties?: Record<string, string>;
};

let client: LocalClient | undefined;
let ready: Promise<void> | undefined;

// Creates the client once per process and starts downloading flag rules.
export function startFlags(): Promise<void> {
  if (!ready) {
    const key = process.env['AMPLITUDE_SERVER_DEPLOYMENT_KEY'];
    if (!key) return Promise.reject(new Error('AMPLITUDE_SERVER_DEPLOYMENT_KEY is not set'));

    const localClient = Experiment.initializeLocal(key);
    client = localClient;
    // start() downloads the flag rules, then polls for updates. If it
    // fails, the next request starts over.
    ready = localClient.start().catch((error: unknown) => {
      localClient.stop();
      client = undefined;
      ready = undefined;
      throw error;
    });
  }
  return ready;
}

// Evaluates the given flags for one user in memory. Returns {} on any
// failure, so pages render their defaults instead of erroring.
export async function evaluateFlags(
  user: ExperimentUser,
  flagKeys: string[],
): Promise<ServerVariants> {
  if (!user.user_id && !user.device_id) return {};

  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    // A cold start or outage renders defaults instead of holding the page.
    await Promise.race([
      startFlags(),
      new Promise<never>((_, reject) => {
        timer = setTimeout(() => reject(new Error('flag rules not loaded within 1 s')), 1000);
      }),
    ]);
    return client ? client.evaluateV2(user, flagKeys) : {};
  } catch (error) {
    console.error('[flags] evaluation failed; rendering defaults.', error);
    return {};
  } finally {
    clearTimeout(timer);
  }
}

export AMPLITUDE_SERVER_DEPLOYMENT_KEY=your-server-deployment-key

// Set by the server when it evaluates flags for a visitor who has no
// AMP_ cookie yet. Not the SDK's own cookie.
export const DEVICE_ID_HANDOFF_COOKIE = 'amp_server_device_id';

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function isDeviceId(value: string | undefined): value is string {
  return value !== undefined && UUID.test(value);
}

import { randomUUID } from 'node:crypto';
import type { Request, Response } from 'express';
import { AmplitudeCookie } from '@amplitude/experiment-node-server';
import { environment } from '../environments/environment';
import { DEVICE_ID_HANDOFF_COOKIE, isDeviceId } from '../app/amplitude-cookies';
import type { ServerFlags } from '../app/server-flags';
import { evaluateFlags } from './experiment';

// Server-rendered flags only. Their variants are readable in the page source.
const FLAG_KEYS = ['new-project-flow-ssr'];

// Pages evaluated per visitor and sent as private. Each one also needs
// RenderMode.Server in src/app/app.routes.server.ts.
const FLAG_PATHS = new Set(['/projects/new']);

export function wantsServerFlags(req: Request): boolean {
  // originalUrl, not req.path: a handler mounted on '/**' sees req.path as '/'.
  const path = new URL(req.originalUrl, 'http://localhost').pathname;
  return Boolean(req.headers.accept?.includes('text/html')) && FLAG_PATHS.has(path);
}

// Your auth: replace with however your server reads the signed-in user.
type ServerUser = { id: string; plan?: string };

function readCookie(req: Request, name: string): string | undefined {
  const prefix = `${name}=`;
  const match = req.headers.cookie?.split(/;\s*/).find((c) => c.startsWith(prefix));
  if (!match) return undefined;
  try {
    return decodeURIComponent(match.slice(prefix.length));
  } catch {
    return undefined;
  }
}

function readDeviceId(req: Request): string | undefined {
  if (!environment.amplitudeApiKey) return undefined;
  // cookieName throws on a malformed key: render defaults, not an error.
  try {
    // `true` selects the Browser SDK 2 cookie format, which unified uses.
    const cookie = readCookie(req, AmplitudeCookie.cookieName(environment.amplitudeApiKey, true));
    return cookie ? (AmplitudeCookie.parse(cookie, true).device_id ?? undefined) : undefined;
  } catch {
    return undefined;
  }
}

export async function loadFlags(req: Request, res: Response): Promise<ServerFlags> {
  // One visitor's device ID and variants: no cache may store this page.
  res.setHeader('cache-control', 'private, no-store');

  // 1. The browser SDK's own cookie.
  // 2. An ID this server minted earlier that the browser hasn't adopted yet.
  // 3. A new ID, handed to the browser in 6d.
  let deviceId = readDeviceId(req);
  if (!deviceId) {
    const handoff = readCookie(req, DEVICE_ID_HANDOFF_COOKIE);
    if (isDeviceId(handoff)) deviceId = handoff;
  }
  if (!deviceId) {
    deviceId = randomUUID();
    res.cookie(DEVICE_ID_HANDOFF_COOKIE, deviceId, {
      path: '/',
      httpOnly: false, // src/app/amplitude.ts reads it
      sameSite: 'lax',
      maxAge: 60 * 60 * 1000, // one hour; Express takes milliseconds
    });
  }

  // Set by your auth middleware, if any. Same "user-" prefix as the browser.
  const user = (req as Request & { user?: ServerUser }).user;
  const userId = user ? `user-${user.id}` : undefined;

  const variants = await evaluateFlags(
    {
      device_id: deviceId,
      user_id: userId,
      // Local evaluation only sees the properties you pass in.
      ...(user ? { user_properties: { plan: user.plan ?? 'unknown' } } : {}),
    },
    FLAG_KEYS,
  );

  // Plain objects only, and nothing for users outside the rollout.
  const flags: ServerFlags['flags'] = {};
  for (const [flagKey, variant] of Object.entries(variants)) {
    if (variant?.value && variant.value !== 'off') {
      flags[flagKey] = { value: variant.value, payload: variant.payload };
    }
  }

  return { deviceId, userId, flags };
}

// Keep lines other Angular pages added here: the header middleware
// (/build/angular-web-experiment) and the withCampaign import and /old-landing
// redirect (/build/angular-web-analytics), both above the Angular handler.
import {
  AngularNodeAppEngine,
  createNodeRequestHandler,
  isMainModule,
  writeResponseToNodeResponse,
} from '@angular/ssr/node';
import express from 'express';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { startFlags } from './server/experiment'; // Added
import { loadFlags, wantsServerFlags } from './server/flags'; // Added

const serverDistFolder = dirname(fileURLToPath(import.meta.url));
const browserDistFolder = resolve(serverDistFolder, '../browser');

const app = express();
const angularApp = new AngularNodeAppEngine();

app.use(
  express.static(browserDistFolder, {
    maxAge: '1y',
    index: false,
    redirect: false,
  }),
);

app.use(async (req, res, next) => {
  try {
    // Added: flagged pages only, each evaluated for this visitor. Angular
    // reads the second handle() argument through the REQUEST_CONTEXT token.
    const amplitudeFlags = wantsServerFlags(req) ? await loadFlags(req, res) : null;
    const response = await angularApp.handle(req, { amplitudeFlags });
    if (response) {
      await writeResponseToNodeResponse(response, res);
    } else {
      next();
    }
  } catch (error) {
    next(error);
  }
});

if (isMainModule(import.meta.url)) {
  // Added: start downloading flag rules now; early requests wait up to 1 s.
  startFlags().catch((error: unknown) => {
    console.warn('[flags] could not load flag rules; pages render defaults.', error);
  });

  const port = process.env['PORT'] || 4000;
  app.listen(port, () => {
    console.log(`Node Express server listening on http://localhost:${port}`);
  });
}

export const reqHandler = createNodeRequestHandler(app);

// Keep lines other Angular pages added here: the plans, offer/:code and
// account routes (/build/angular-web-analytics) and projects/:projectId
// (/build/angular-heatmaps). Merge into your existing array.
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  // Rendered per request, so the server can evaluate flags for each visitor.
  { path: 'projects/new', renderMode: RenderMode.Server },
  { path: '**', renderMode: RenderMode.Prerender },
];

// Keep lines other Angular pages added here: pathOnly page views
// (/build/angular-web-analytics), masking (/build/angular-session-replay),
// and the webExperiment.plugin() block (/build/angular-web-experiment).
import * as amplitude from '@amplitude/unified';
import { environment } from '../environments/environment';
import { setAmplitudeReady } from './amplitude-ready';
import { DEVICE_ID_HANDOFF_COOKIE, isDeviceId } from './amplitude-cookies';

function readCookie(name: string): string | undefined {
  const prefix = `${name}=`;
  const match = document.cookie.split('; ').find((c) => c.startsWith(prefix));
  // A malformed cookie must not stop the app from starting.
  try {
    return match ? decodeURIComponent(match.slice(prefix.length)) : undefined;
  } catch {
    return undefined;
  }
}

export function initAmplitude(): void {
  if (!environment.amplitudeApiKey) {
    console.warn('amplitudeApiKey is not set; analytics is off.');
    setAmplitudeReady(null);
    return;
  }

  // Browser SDK 2 names its cookie AMP_ plus the first 10 characters of
  // the key. If it exists, the SDK already has a device ID: keep it.
  const hasAmpCookie =
    readCookie(`AMP_${environment.amplitudeApiKey.slice(0, 10)}`) !== undefined;
  const serverDeviceId = readCookie(DEVICE_ID_HANDOFF_COOKIE);
  const adoptServerDeviceId = !hasAmpCookie && isDeviceId(serverDeviceId);

  setAmplitudeReady(
    amplitude.initAll(environment.amplitudeApiKey, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
        // First visit only: the device ID the server bucketed this visitor with.
        ...(adoptServerDeviceId ? { deviceId: serverDeviceId } : {}),
      },
      sessionReplay: {
        sampleRate: environment.production ? 0.01 : 1,
        debugMode: !environment.production,
        // From /build/angular-session-replay. Keep your masking rules when you paste this file.
        privacyConfig: {
          maskSelector: ['[data-amp-mask]'],
          blockSelector: ['[data-amp-block]'],
          unmaskSelector: ['[data-amp-unmask]'],
        },
      },
      experiment: {
        deploymentKey: environment.amplitudeDeploymentKey,
        fetchTimeoutMillis: 3000,
        automaticExposureTracking: false,
      },
    }),
  );
}

import {
  Injectable,
  REQUEST_CONTEXT,
  TransferState,
  afterNextRender,
  inject,
  makeStateKey,
} from '@angular/core';
import * as amplitude from '@amplitude/unified';
import { amplitudeReady } from './amplitude-ready';

export type FlagVariant = { value: string; payload?: unknown };
export type ServerFlags = {
  deviceId: string;
  userId?: string;
  flags: Record<string, FlagVariant>;
};

const SERVER_FLAGS = makeStateKey<ServerFlags | null>('amplitude-server-flags');

@Injectable({ providedIn: 'root' })
export class ServerFlagsService {
  // What the server evaluated for this page load, or null without SSR.
  readonly state: ServerFlags | null;

  constructor() {
    const transferState = inject(TransferState);
    // Server: the object src/server.ts passed to handle(). Browser: none.
    const context = inject(REQUEST_CONTEXT, { optional: true }) as {
      amplitudeFlags?: ServerFlags | null;
    } | null;
    if (context?.amplitudeFlags) {
      transferState.set(SERVER_FLAGS, context.amplitudeFlags);
    }
    this.state = transferState.get(SERVER_FLAGS, null);
  }
}

// One exposure per flag per page load; client-side navigations don't resend it.
const sentServerExposures = new Set<string>();

// Reads a server-evaluated flag during render and sends one exposure after
// it renders, if the browser's identity still matches the server's.
export function injectServerFlag(flagKey: string): FlagVariant | undefined {
  const state = inject(ServerFlagsService).state;
  const variant = state?.flags[flagKey];

  // afterNextRender never runs on the server.
  afterNextRender(() => {
    const value = variant?.value;
    // No variant means the user isn't in the rollout: send nothing.
    if (!state || !value) return;

    // getDeviceId() is undefined until initAll settles.
    void amplitudeReady.then((ok) => {
      if (!ok) return;
      const browserDeviceId = amplitude.getDeviceId();
      const browserUserId = amplitude.getUserId();
      // After a sign-out or a different sign-in in this tab, the variant on
      // screen isn't this visitor's any more: send nothing.
      const sameDevice = browserDeviceId === state.deviceId;
      const sameUser = !state.userId || !browserUserId || browserUserId === state.userId;
      if (!sameDevice || !sameUser) return;

      if (sentServerExposures.has(flagKey)) return;
      sentServerExposures.add(flagKey);
      amplitude.track({
        event_type: '$exposure',
        event_properties: { flag_key: flagKey, variant: value },
        // The user the server evaluated, if the browser hasn't set one yet.
        ...(state.userId && !browserUserId ? { user_id: state.userId } : {}),
      });
    });
  });

  return variant;
}

// Keep lines other Angular pages added here: nav links (/build/angular-session-replay,
// /build/angular-heatmaps), and EngagementBridgeService and <app-feedback-button />
// (/build/angular-guides-surveys).
import { ServerFlagsService } from './server-flags';

  constructor() {
    inject(AmplitudeIdentityService);
    // Copies the server's flags into TransferState on every server render
    // that evaluated them, and reads them back in the browser.
    inject(ServerFlagsService);
  }

import { Component } from '@angular/core';
import { injectServerFlag } from '../server-flags';
import { newProjectConfig } from './new-project-config';
import { NewProjectForm } from './new-project-form';

@Component({
  selector: 'app-new-project',
  imports: [NewProjectForm],
  template: `<app-new-project-form [config]="config" />`,
})
export class NewProject {
  // Evaluated on the server, so the first HTML already has the variant.
  protected readonly config = newProjectConfig(injectServerFlag('new-project-flow-ssr'));
}

// -- src/environments/environment.ts --
export const environment = {
  production: true,
  amplitudeApiKey: 'your-project-api-key',
  amplitudeDeploymentKey: 'your-client-deployment-key',
};

// -- src/environments/environment.development.ts --
export const environment = {
  production: false,
  amplitudeApiKey: 'your-project-api-key',
  amplitudeDeploymentKey: 'your-client-deployment-key',
};

// -- src/app/amplitude-ready.ts --
// Resolves to true once initAll has finished in the browser, or false
// if analytics is off. Nothing awaits it on the server.
let markReady: (ok: boolean) => void = () => {};
export const amplitudeReady = new Promise<boolean>((resolve) => {
  markReady = resolve;
});

export function setAmplitudeReady(init: Promise<unknown> | null): void {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error: unknown) => {
      console.warn('[amplitude] initAll failed', error);
      markReady(false);
    },
  );
}

// -- src/app/amplitude.ts --
// Keep lines other Angular pages added here: pathOnly page views
// (/build/angular-web-analytics), masking (/build/angular-session-replay),
// and the webExperiment.plugin() block (/build/angular-web-experiment).
import * as amplitude from '@amplitude/unified';
import { environment } from '../environments/environment';
import { setAmplitudeReady } from './amplitude-ready';

export function initAmplitude(): void {
  if (!environment.amplitudeApiKey) {
    console.warn('amplitudeApiKey is not set; analytics is off.');
    setAmplitudeReady(null);
    return;
  }

  setAmplitudeReady(
    amplitude.initAll(environment.amplitudeApiKey, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
      },
      sessionReplay: {
        sampleRate: environment.production ? 0.01 : 1,
        debugMode: !environment.production,
        // From /build/angular-session-replay. Keep your masking rules when you paste this file.
        privacyConfig: {
          maskSelector: ['[data-amp-mask]'],
          blockSelector: ['[data-amp-block]'],
          unmaskSelector: ['[data-amp-unmask]'],
        },
      },
      experiment: {
        deploymentKey: environment.amplitudeDeploymentKey,
        fetchTimeoutMillis: 3000,
        automaticExposureTracking: false,
      },
    }),
  );
}

// -- src/app/flags.service.ts --
import {
  Injectable,
  PLATFORM_ID,
  Signal,
  afterNextRender,
  effect,
  inject,
  signal,
} from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import * as amplitude from '@amplitude/unified';
import { amplitudeReady } from './amplitude-ready';

export type FlagState = { value: string | null; payload: unknown };
type FetchUser = { user_properties?: Record<string, string> };

@Injectable({ providedIn: 'root' })
export class FlagsService {
  private readonly isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
  private readonly settled = signal(0);
  private generation = 0;

  readonly version = this.settled.asReadonly();

  async refetch(user?: FetchUser): Promise<void> {
    if (!this.isBrowser) return;
    const generation = ++this.generation;
    try {
      if (await amplitudeReady) {
        await amplitude.experiment()?.fetch(user);
      }
    } finally {
      if (generation === this.generation) this.settled.update((v) => v + 1);
    }
  }
}

export function injectFlag(flagKey: string): Signal<FlagState | undefined> {
  const flags = inject(FlagsService);
  const state = signal<FlagState | undefined>(undefined);

  const rendered = signal(false);
  afterNextRender(() => rendered.set(true));

  let lastExposure: string | undefined;

  effect(() => {
    if (!rendered() || flags.version() === 0) return;

    const experiment = amplitude.experiment();
    const variant = experiment?.variant(flagKey);
    const value = variant?.value ?? null;
    state.set({ value, payload: variant?.payload });

    if (!value) return;

    const key = `${amplitude.getUserId() ?? ''}|${amplitude.getDeviceId() ?? ''}|${value}`;
    if (key === lastExposure) return;
    lastExposure = key;
    experiment?.exposure(flagKey);
  });

  return state.asReadonly();
}

// -- src/app/amplitude-identity.service.ts --
import { Injectable, PLATFORM_ID, computed, effect, inject } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import * as amplitude from '@amplitude/unified';
import { AuthService } from './auth.service';
import { FlagsService } from './flags.service';

@Injectable({ providedIn: 'root' })
export class AmplitudeIdentityService {
  private readonly auth = inject(AuthService);
  private readonly flags = inject(FlagsService);
  private readonly isBrowser = isPlatformBrowser(inject(PLATFORM_ID));

  private readonly identity = computed(
    () => {
      const user = this.auth.user();
      return user ? { id: user.id, plan: user.plan ?? 'unknown' } : null;
    },
    { equal: (a, b) => a?.id === b?.id && a?.plan === b?.plan },
  );

  constructor() {
    if (!this.isBrowser) return;

    effect(() => {
      const identity = this.identity();

      if (!identity) {
        void this.flags.refetch();
        return;
      }

      // Amplitude drops IDs shorter than 5 characters.
      amplitude.setUserId(`user-${identity.id}`);
      const identify = new amplitude.Identify();
      identify.set('plan', identity.plan);
      amplitude.identify(identify);

      void this.flags.refetch({ user_properties: { plan: identity.plan } });
    });
  }
}

// -- src/app/auth.service.ts --
// Keep lines other Angular pages added here: the getEngagement import and
// getEngagement()?.gs.closeAll() before reset() (/build/angular-guides-surveys).
import { Injectable, inject, signal } from '@angular/core';
import * as amplitude from '@amplitude/unified';
import { FlagsService } from './flags.service';

export interface User {
  id: string;
  plan?: string;
}

@Injectable({ providedIn: 'root' })
export class AuthService {
  private readonly flags = inject(FlagsService);
  readonly user = signal<User | null>(null);

  signIn(user: User): void {
    // ... your sign-in logic
    this.user.set(user);
  }

  async signOut(): Promise<void> {
    // ... your sign-out logic
    this.user.set(null);
    amplitude.reset();
    amplitude.experiment()?.clear();
    void this.flags.refetch();
  }
}

// -- src/app/projects/new-project-config.ts --
export const TEMPLATES: string[] = ['blank', 'kanban', 'roadmap'];

export type NewProjectConfig = { defaultTemplate: string; showGallery: boolean };

type NewProjectPayload = { defaultTemplate?: unknown; showTemplateGallery?: unknown };

export function newProjectConfig(
  variant: { value: string | null; payload?: unknown } | undefined,
): NewProjectConfig {
  const payload = (variant?.value === 'on' ? variant.payload : undefined) as
    | NewProjectPayload
    | undefined;
  const candidate = payload?.defaultTemplate;
  return {
    defaultTemplate:
      typeof candidate === 'string' && TEMPLATES.includes(candidate) ? candidate : 'blank',
    showGallery: payload?.showTemplateGallery === true,
  };
}

export function sameConfig(a?: NewProjectConfig, b?: NewProjectConfig): boolean {
  return a?.defaultTemplate === b?.defaultTemplate && a?.showGallery === b?.showGallery;
}

// -- src/app/projects/new-project-form.ts --
import { Component, input, linkedSignal } from '@angular/core';
import * as amplitude from '@amplitude/unified';
import { TEMPLATES, type NewProjectConfig } from './new-project-config';

@Component({
  selector: 'app-new-project-form',
  template: `
    @if (config().showGallery) {
      <fieldset>
        <legend>Start from a template</legend>
        @for (t of templates; track t) {
          <label>
            <input
              type="radio"
              name="template"
              [value]="t"
              [checked]="template() === t"
              (change)="template.set(t)"
            />
            {{ t }}
          </label>
        }
      </fieldset>
    } @else {
      <select #picker (change)="template.set(picker.value)">
        @for (t of templates; track t) {
          <option [value]="t" [selected]="template() === t">{{ t }}</option>
        }
      </select>
    }
    <button type="button" (click)="create()">Create project</button>
  `,
})
export class NewProjectForm {
  readonly config = input.required<NewProjectConfig>();
  protected readonly templates = TEMPLATES;

  protected readonly template = linkedSignal(() => this.config().defaultTemplate);

  protected create(): void {
    // ... your create logic

    amplitude.track('Project Created', { template: this.template() });
  }
}

// -- src/app/projects/new-project.ts --
import { Component, computed } from '@angular/core';
import { injectFlag } from '../flags.service';
import { newProjectConfig, sameConfig } from './new-project-config';
import { NewProjectForm } from './new-project-form';

@Component({
  selector: 'app-new-project',
  imports: [NewProjectForm],
  template: `
    @if (config(); as cfg) {
      <app-new-project-form [config]="cfg" />
    } @else {
      <div aria-busy="true" style="min-height: 320px"></div>
    }
  `,
})
export class NewProject {
  private readonly flag = injectFlag('new-project-flow');

  protected readonly config = computed(
    () => {
      const flag = this.flag();
      return flag ? newProjectConfig(flag) : undefined;
    },
    { equal: sameConfig },
  );
}

// -- src/app/amplitude-cookies.ts --
export const DEVICE_ID_HANDOFF_COOKIE = 'amp_server_device_id';

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export function isDeviceId(value: string | undefined): value is string {
  return value !== undefined && UUID.test(value);
}

// -- src/app/amplitude.ts --
// Keep lines other Angular pages added here: pathOnly page views
// (/build/angular-web-analytics), masking (/build/angular-session-replay),
// and the webExperiment.plugin() block (/build/angular-web-experiment).
import * as amplitude from '@amplitude/unified';
import { environment } from '../environments/environment';
import { setAmplitudeReady } from './amplitude-ready';
import { DEVICE_ID_HANDOFF_COOKIE, isDeviceId } from './amplitude-cookies';

function readCookie(name: string): string | undefined {
  const prefix = `${name}=`;
  const match = document.cookie.split('; ').find((c) => c.startsWith(prefix));
  try {
    return match ? decodeURIComponent(match.slice(prefix.length)) : undefined;
  } catch {
    return undefined;
  }
}

export function initAmplitude(): void {
  if (!environment.amplitudeApiKey) {
    console.warn('amplitudeApiKey is not set; analytics is off.');
    setAmplitudeReady(null);
    return;
  }

  const hasAmpCookie =
    readCookie(`AMP_${environment.amplitudeApiKey.slice(0, 10)}`) !== undefined;
  const serverDeviceId = readCookie(DEVICE_ID_HANDOFF_COOKIE);
  const adoptServerDeviceId = !hasAmpCookie && isDeviceId(serverDeviceId);

  setAmplitudeReady(
    amplitude.initAll(environment.amplitudeApiKey, {
      analytics: {
        autocapture: {
          attribution: true,
          pageViews: true,
          sessions: true,
          formInteractions: true,
          fileDownloads: true,
          elementInteractions: true,
        },
        ...(adoptServerDeviceId ? { deviceId: serverDeviceId } : {}),
      },
      sessionReplay: {
        sampleRate: environment.production ? 0.01 : 1,
        debugMode: !environment.production,
        // From /build/angular-session-replay. Keep your masking rules when you paste this file.
        privacyConfig: {
          maskSelector: ['[data-amp-mask]'],
          blockSelector: ['[data-amp-block]'],
          unmaskSelector: ['[data-amp-unmask]'],
        },
      },
      experiment: {
        deploymentKey: environment.amplitudeDeploymentKey,
        fetchTimeoutMillis: 3000,
        automaticExposureTracking: false,
      },
    }),
  );
}

// -- src/app/server-flags.ts --
import {
  Injectable,
  REQUEST_CONTEXT,
  TransferState,
  afterNextRender,
  inject,
  makeStateKey,
} from '@angular/core';
import * as amplitude from '@amplitude/unified';
import { amplitudeReady } from './amplitude-ready';

export type FlagVariant = { value: string; payload?: unknown };
export type ServerFlags = {
  deviceId: string;
  userId?: string;
  flags: Record<string, FlagVariant>;
};

const SERVER_FLAGS = makeStateKey<ServerFlags | null>('amplitude-server-flags');

@Injectable({ providedIn: 'root' })
export class ServerFlagsService {
  readonly state: ServerFlags | null;

  constructor() {
    const transferState = inject(TransferState);
    const context = inject(REQUEST_CONTEXT, { optional: true }) as {
      amplitudeFlags?: ServerFlags | null;
    } | null;
    if (context?.amplitudeFlags) {
      transferState.set(SERVER_FLAGS, context.amplitudeFlags);
    }
    this.state = transferState.get(SERVER_FLAGS, null);
  }
}

// One exposure per flag per page load; client-side navigations don't resend it.
const sentServerExposures = new Set<string>();

export function injectServerFlag(flagKey: string): FlagVariant | undefined {
  const state = inject(ServerFlagsService).state;
  const variant = state?.flags[flagKey];

  afterNextRender(() => {
    const value = variant?.value;
    if (!state || !value) return;

    void amplitudeReady.then((ok) => {
      if (!ok) return;
      const browserDeviceId = amplitude.getDeviceId();
      const browserUserId = amplitude.getUserId();
      const sameDevice = browserDeviceId === state.deviceId;
      const sameUser = !state.userId || !browserUserId || browserUserId === state.userId;
      if (!sameDevice || !sameUser) return;

      if (sentServerExposures.has(flagKey)) return;
      sentServerExposures.add(flagKey);
      amplitude.track({
        event_type: '$exposure',
        event_properties: { flag_key: flagKey, variant: value },
        ...(state.userId && !browserUserId ? { user_id: state.userId } : {}),
      });
    });
  });

  return variant;
}

// -- src/app/app.ts (add two lines to your root component) --
// Angular 19: src/app/app.component.ts, class AppComponent.
// Keep lines other Angular pages added here: nav links (/build/angular-session-replay,
// /build/angular-heatmaps), and EngagementBridgeService and <app-feedback-button />
// (/build/angular-guides-surveys).
import { ServerFlagsService } from './server-flags';

  constructor() {
    inject(AmplitudeIdentityService);
    inject(ServerFlagsService);
  }

// -- src/app/projects/new-project.ts --
import { Component } from '@angular/core';
import { injectServerFlag } from '../server-flags';
import { newProjectConfig } from './new-project-config';
import { NewProjectForm } from './new-project-form';

@Component({
  selector: 'app-new-project',
  imports: [NewProjectForm],
  template: `<app-new-project-form [config]="config" />`,
})
export class NewProject {
  protected readonly config = newProjectConfig(injectServerFlag('new-project-flow-ssr'));
}

// -- src/server/experiment.ts --
import { Experiment } from '@amplitude/experiment-node-server';

type LocalClient = ReturnType<typeof Experiment.initializeLocal>;
export type ServerVariants = ReturnType<LocalClient['evaluateV2']>;
export type ExperimentUser = {
  user_id?: string;
  device_id?: string;
  user_properties?: Record<string, string>;
};

let client: LocalClient | undefined;
let ready: Promise<void> | undefined;

export function startFlags(): Promise<void> {
  if (!ready) {
    const key = process.env['AMPLITUDE_SERVER_DEPLOYMENT_KEY'];
    if (!key) return Promise.reject(new Error('AMPLITUDE_SERVER_DEPLOYMENT_KEY is not set'));

    const localClient = Experiment.initializeLocal(key);
    client = localClient;
    ready = localClient.start().catch((error: unknown) => {
      localClient.stop();
      client = undefined;
      ready = undefined;
      throw error;
    });
  }
  return ready;
}

export async function evaluateFlags(
  user: ExperimentUser,
  flagKeys: string[],
): Promise<ServerVariants> {
  if (!user.user_id && !user.device_id) return {};

  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    await Promise.race([
      startFlags(),
      new Promise<never>((_, reject) => {
        timer = setTimeout(() => reject(new Error('flag rules not loaded within 1 s')), 1000);
      }),
    ]);
    return client ? client.evaluateV2(user, flagKeys) : {};
  } catch (error) {
    console.error('[flags] evaluation failed; rendering defaults.', error);
    return {};
  } finally {
    clearTimeout(timer);
  }
}

// -- src/server/flags.ts --
import { randomUUID } from 'node:crypto';
import type { Request, Response } from 'express';
import { AmplitudeCookie } from '@amplitude/experiment-node-server';
import { environment } from '../environments/environment';
import { DEVICE_ID_HANDOFF_COOKIE, isDeviceId } from '../app/amplitude-cookies';
import type { ServerFlags } from '../app/server-flags';
import { evaluateFlags } from './experiment';

const FLAG_KEYS = ['new-project-flow-ssr'];

const FLAG_PATHS = new Set(['/projects/new']);

export function wantsServerFlags(req: Request): boolean {
  // originalUrl, not req.path: a handler mounted on '/**' sees req.path as '/'.
  const path = new URL(req.originalUrl, 'http://localhost').pathname;
  return Boolean(req.headers.accept?.includes('text/html')) && FLAG_PATHS.has(path);
}

type ServerUser = { id: string; plan?: string };

function readCookie(req: Request, name: string): string | undefined {
  const prefix = `${name}=`;
  const match = req.headers.cookie?.split(/;\s*/).find((c) => c.startsWith(prefix));
  if (!match) return undefined;
  try {
    return decodeURIComponent(match.slice(prefix.length));
  } catch {
    return undefined;
  }
}

function readDeviceId(req: Request): string | undefined {
  if (!environment.amplitudeApiKey) return undefined;
  try {
    const cookie = readCookie(req, AmplitudeCookie.cookieName(environment.amplitudeApiKey, true));
    return cookie ? (AmplitudeCookie.parse(cookie, true).device_id ?? undefined) : undefined;
  } catch {
    return undefined;
  }
}

export async function loadFlags(req: Request, res: Response): Promise<ServerFlags> {
  res.setHeader('cache-control', 'private, no-store');

  let deviceId = readDeviceId(req);
  if (!deviceId) {
    const handoff = readCookie(req, DEVICE_ID_HANDOFF_COOKIE);
    if (isDeviceId(handoff)) deviceId = handoff;
  }
  if (!deviceId) {
    deviceId = randomUUID();
    res.cookie(DEVICE_ID_HANDOFF_COOKIE, deviceId, {
      path: '/',
      httpOnly: false,
      sameSite: 'lax',
      maxAge: 60 * 60 * 1000,
    });
  }

  const user = (req as Request & { user?: ServerUser }).user;
  const userId = user ? `user-${user.id}` : undefined;

  const variants = await evaluateFlags(
    {
      device_id: deviceId,
      user_id: userId,
      ...(user ? { user_properties: { plan: user.plan ?? 'unknown' } } : {}),
    },
    FLAG_KEYS,
  );

  const flags: ServerFlags['flags'] = {};
  for (const [flagKey, variant] of Object.entries(variants)) {
    if (variant?.value && variant.value !== 'off') {
      flags[flagKey] = { value: variant.value, payload: variant.payload };
    }
  }

  return { deviceId, userId, flags };
}

// -- src/server.ts (Angular 20; on Angular 19 make only the // Added changes) --
// Keep lines other Angular pages added here: the header middleware
// (/build/angular-web-experiment) and the withCampaign import and /old-landing
// redirect (/build/angular-web-analytics), both above the Angular handler.
import {
  AngularNodeAppEngine,
  createNodeRequestHandler,
  isMainModule,
  writeResponseToNodeResponse,
} from '@angular/ssr/node';
import express from 'express';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { startFlags } from './server/experiment'; // Added
import { loadFlags, wantsServerFlags } from './server/flags'; // Added

const serverDistFolder = dirname(fileURLToPath(import.meta.url));
const browserDistFolder = resolve(serverDistFolder, '../browser');

const app = express();
const angularApp = new AngularNodeAppEngine();

app.use(
  express.static(browserDistFolder, {
    maxAge: '1y',
    index: false,
    redirect: false,
  }),
);

app.use(async (req, res, next) => {
  try {
    // Added
    const amplitudeFlags = wantsServerFlags(req) ? await loadFlags(req, res) : null;
    const response = await angularApp.handle(req, { amplitudeFlags });
    if (response) {
      await writeResponseToNodeResponse(response, res);
    } else {
      next();
    }
  } catch (error) {
    next(error);
  }
});

if (isMainModule(import.meta.url)) {
  // Added
  startFlags().catch((error: unknown) => {
    console.warn('[flags] could not load flag rules; pages render defaults.', error);
  });

  const port = process.env['PORT'] || 4000;
  app.listen(port, () => {
    console.log(`Node Express server listening on http://localhost:${port}`);
  });
}

export const reqHandler = createNodeRequestHandler(app);

// -- src/app/app.routes.server.ts --
// Keep lines other Angular pages added here: the plans, offer/:code and
// account routes (/build/angular-web-analytics) and projects/:projectId
// (/build/angular-heatmaps). Merge into your existing array.
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  { path: 'projects/new', renderMode: RenderMode.Server },
  { path: '**', renderMode: RenderMode.Prerender },
];

First complete https://amplitude.com/build/angular-product-analytics (or
confirm the app already has its setup). Then follow
https://amplitude.com/build/angular-feature-flags exactly. Use the root
component file the app already has (app.ts or app.component.ts).
Merge into existing shared files (environment files, amplitude.ts,
auth.service.ts, app.ts, server.ts, app.routes.server.ts) and never
delete lines another Amplitude Build page added; each file's first
comment names them. Don't add a second initAll.
- Add amplitudeDeploymentKey (a client- key, never a server- key) to both
  environment files and leave the sample value for me.
- Pass initAll(...) to setAmplitudeReady, add the experiment block with
  automaticExposureTracking: false, and read every flag you show through
  injectFlag, in the component that shows it.
- In the sign-out method: reset(), then experiment()?.clear(), then
  FlagsService.refetch(). Never reset when the user is null.
- If the app uses @angular/ssr: if src/server.ts uses CommonEngine, skip
  step 6 and tell me. Otherwise do step 6: read the server key from
  process.env.AMPLITUDE_SERVER_DEPLOYMENT_KEY, edit the generated
  src/server.ts in place (only the three // Added changes), render
  projects/new with RenderMode.Server, and add only the two
  ServerFlagsService lines to the root component.
- Never send exposures from the server, don't hardcode keys, and don't
  invent flag keys. Report every file you changed.