How to add guides and surveys to a React Router app (formerly Remix)

npm install @amplitude/unified

script-src 'self' https://*.amplitude.com
connect-src 'self' https://*.amplitude.com
img-src 'self' https://*.amplitude.com
media-src 'self' https://*.amplitude.com
style-src 'self' https://*.amplitude.com

// 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) {
  if (!init) {
    markReady(false);
    return;
  }
  init.then(
    () => markReady(true),
    (error) => {
      console.warn("[amplitude] initAll failed", error);
      markReady(false);
    },
  );
}

// The window.engagement methods this page calls, as the Guides and Surveys Web SDK docs define them.
type Engagement = {
  setRouter(fn: (url: string) => void): void;
  addCallback(name: string, fn: () => void): void;
  gs: {
    show(key: string, stepIndex?: number): void;
    closeAll(): void;
  };
  _debugStatus?: () => unknown;
};

export function getEngagement(): Engagement | undefined {
  // No window during the server render.
  if (typeof window === "undefined") return undefined;
  return (window as unknown as { engagement?: Engagement }).engagement;
}

// Keep lines other React Router pages added here: pageViews: { trackHistoryChanges:
// "pathOnly" } (/build/react-router-web-analytics); debugMode and privacyConfig
// (/build/react-router-session-replay); the amplitude-cookies import and handoff
// lines, the deviceId spread, and the experiment block
// (/build/react-router-feature-flags); the webExperiment.plugin() registration after
// initAll (/build/react-router-web-experiment).
// This page adds the setAmplitudeReady import, the setAmplitudeReady(...) wrapper around initAll, and setAmplitudeReady(null).
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";
import * as amplitude from "@amplitude/unified";
import { setAmplitudeReady } from "./lib/amplitude-ready";

const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY;

if (apiKey) {
  // initAll starts analytics, session replay, Feature Experiment, and
  // guides and surveys. Guides and surveys boot with the analytics user.
  setAmplitudeReady(
    amplitude.initAll(apiKey, {
      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: import.meta.env.DEV ? 1 : 0.01,
      },
    }),
  );
} else {
  console.warn("VITE_AMPLITUDE_API_KEY is not set; analytics is off.");
  setAmplitudeReady(null);
}

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <HydratedRouter />
    </StrictMode>
  );
});

import { useEffect } from "react";
import { useNavigate } from "react-router";
import { amplitudeReady } from "./amplitude-ready";
import { getEngagement } from "./engagement";

export function useEngagementBridge() {
  const navigate = useNavigate();

  useEffect(() => {
    // StrictMode runs setup, cleanup, then setup again in development.
    // Only the run that wasn't cleaned up registers.
    let cancelled = false;

    void amplitudeReady.then((ok) => {
      // Analytics is off, initAll failed, or this run was cleaned up.
      if (!ok || cancelled) return;

      const engagement = getEngagement();
      if (!engagement) {
        console.warn("window.engagement not found; guide links will reload the page.");
        return;
      }

      // Guide links set to "Use router" call this instead of reloading.
      engagement.setRouter((url) => {
        const target = new URL(url, window.location.origin);

        // Other sites load normally.
        if (target.origin !== window.location.origin) {
          window.location.assign(target.href);
          return;
        }

        void navigate(target.pathname + target.search + target.hash);
      });

      // Guide buttons with "Run callback" and the name open_new_project.
      engagement.addCallback("open_new_project", () => {
        void navigate("/projects/new");
      });
    });

    return () => {
      cancelled = true;
    };
  }, [navigate]);
}

// Keep lines other React Router pages added here: amplitude.experiment()?.clear()
// after reset() (/build/react-router-feature-flags).
import { Form } from "react-router";
import * as amplitude from "@amplitude/unified";
import { getEngagement } from "../lib/engagement";

export function SignOutButton() {
  return (
    <Form
      method="post"
      action="/logout"
      onSubmit={() => {
        // Order: closeAll, reset, clear.
        getEngagement()?.gs.closeAll(); // close anything still on screen
        amplitude.reset(); // clears the user ID and issues a new device ID
        amplitude.experiment()?.clear(); // from /build/react-router-feature-flags; harmless without flags
      }}
    >
      <button type="submit">Sign out</button>
    </Form>
  );
}

// Keep lines other React Router pages added here: data-exp attributes and
// suppressHydrationWarning (/build/react-router-web-experiment).
// Add data-guide to the elements a guide points at, for example:
<Link to="/projects/new" data-guide="new-project-button">New project</Link>

import { amplitudeReady } from "../lib/amplitude-ready";
import { getEngagement } from "../lib/engagement";

export function FeedbackButton() {
  return (
    <button
      type="button"
      onClick={() => {
        // Waits for initAll, so an early click opens the survey once it's ready.
        void amplitudeReady.then((ok) => {
          if (ok) getEngagement()?.gs.show("product-feedback");
        });
      }}
    >
      Give feedback
    </button>
  );
}

// Keep lines other React Router pages added here: the root loader and its getUser
// import (/build/react-router-product-analytics); the refetchBrowserFlags import and
// calls (/build/react-router-feature-flags); the experiment <script> in Layout's head
// (/build/react-router-web-experiment).

// Add these imports:
import { useEngagementBridge } from "./lib/engagement-bridge";
import { FeedbackButton } from "./components/FeedbackButton";

// Replace the App export:

export default function App({ loaderData }: Route.ComponentProps) {
  // Guide links and Run callback buttons, registered once in the browser.
  useEngagementBridge();

  const id = loaderData.user?.id;
  const plan = loaderData.user?.plan ?? "unknown";

  // The root loader reruns after every action. Only act when the
  // identity actually changes.
  const lastIdentity = useRef<string | undefined>(undefined);

  useEffect(() => {
    const identity = id ? `user-${id}|${plan}` : "anonymous";
    if (identity === lastIdentity.current) return;
    lastIdentity.current = identity;

    // Signed out or not signed in yet: keep the same device ID.
    // Reset only from your sign-out handler.
    if (!id) return;

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

    const identify = new amplitude.Identify();
    identify.set("plan", plan);
    amplitude.identify(identify);
  }, [id, plan]);

  return (
    <>
      <header>
        <FeedbackButton />
      </header>
      <Outlet />
    </>
  );
}

// -- app/lib/amplitude-ready.ts --
let markReady: (ok: boolean) => void = () => {};
export const amplitudeReady = new Promise<boolean>((resolve) => {
  markReady = resolve;
});

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

// -- app/lib/engagement.ts --
type Engagement = {
  setRouter(fn: (url: string) => void): void;
  addCallback(name: string, fn: () => void): void;
  gs: {
    show(key: string, stepIndex?: number): void;
    closeAll(): void;
  };
  _debugStatus?: () => unknown;
};

export function getEngagement(): Engagement | undefined {
  if (typeof window === "undefined") return undefined;
  return (window as unknown as { engagement?: Engagement }).engagement;
}

// -- app/entry.client.tsx --
// Keep lines other React Router pages added here: pageViews: { trackHistoryChanges:
// "pathOnly" } (/build/react-router-web-analytics); debugMode and privacyConfig
// (/build/react-router-session-replay); the amplitude-cookies import and handoff
// lines, the deviceId spread, and the experiment block
// (/build/react-router-feature-flags); the webExperiment.plugin() registration after
// initAll (/build/react-router-web-experiment).
// This page adds the setAmplitudeReady import, the setAmplitudeReady(...) wrapper around initAll, and setAmplitudeReady(null).
import { startTransition, StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";
import * as amplitude from "@amplitude/unified";
import { setAmplitudeReady } from "./lib/amplitude-ready";

const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY;

if (apiKey) {
  // initAll starts analytics, session replay, Feature Experiment, and
  // guides and surveys. Guides and surveys boot with the analytics user.
  setAmplitudeReady(
    amplitude.initAll(apiKey, {
      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: import.meta.env.DEV ? 1 : 0.01,
      },
    }),
  );
} else {
  console.warn("VITE_AMPLITUDE_API_KEY is not set; analytics is off.");
  setAmplitudeReady(null);
}

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <HydratedRouter />
    </StrictMode>
  );
});

// -- app/lib/engagement-bridge.ts --
import { useEffect } from "react";
import { useNavigate } from "react-router";
import { amplitudeReady } from "./amplitude-ready";
import { getEngagement } from "./engagement";

export function useEngagementBridge() {
  const navigate = useNavigate();

  useEffect(() => {
    let cancelled = false;

    void amplitudeReady.then((ok) => {
      if (!ok || cancelled) return;

      const engagement = getEngagement();
      if (!engagement) {
        console.warn("window.engagement not found; guide links will reload the page.");
        return;
      }

      engagement.setRouter((url) => {
        const target = new URL(url, window.location.origin);
        if (target.origin !== window.location.origin) {
          window.location.assign(target.href);
          return;
        }
        void navigate(target.pathname + target.search + target.hash);
      });

      engagement.addCallback("open_new_project", () => {
        void navigate("/projects/new");
      });
    });

    return () => {
      cancelled = true;
    };
  }, [navigate]);
}

// -- app/components/SignOutButton.tsx --
// Keep lines other React Router pages added here: amplitude.experiment()?.clear()
// after reset() (/build/react-router-feature-flags).
import { Form } from "react-router";
import * as amplitude from "@amplitude/unified";
import { getEngagement } from "../lib/engagement";

export function SignOutButton() {
  return (
    <Form
      method="post"
      action="/logout"
      onSubmit={() => {
        // Order: closeAll, reset, clear.
        getEngagement()?.gs.closeAll(); // close anything still on screen
        amplitude.reset(); // clears the user ID and issues a new device ID
        amplitude.experiment()?.clear(); // from /build/react-router-feature-flags; harmless without flags
      }}
    >
      <button type="submit">Sign out</button>
    </Form>
  );
}

// -- app/routes/home.tsx (add to your existing home route; keep its meta export) --
// Keep lines other React Router pages added here: data-exp attributes and
// suppressHydrationWarning (/build/react-router-web-experiment).
// Add data-guide to the elements a guide points at, for example:
<Link to="/projects/new" data-guide="new-project-button">New project</Link>

// -- app/components/FeedbackButton.tsx --
import { amplitudeReady } from "../lib/amplitude-ready";
import { getEngagement } from "../lib/engagement";

export function FeedbackButton() {
  return (
    <button
      type="button"
      onClick={() => {
        // Waits for initAll, so an early click opens the survey once it's ready.
        void amplitudeReady.then((ok) => {
          if (ok) getEngagement()?.gs.show("product-feedback");
        });
      }}
    >
      Give feedback
    </button>
  );
}

// -- app/root.tsx (App export; keep the template's imports, links, Layout and ErrorBoundary, and the root loader) --
// Keep lines other React Router pages added here: the root loader and its getUser
// import (/build/react-router-product-analytics); the refetchBrowserFlags import and
// calls (/build/react-router-feature-flags); the experiment <script> in Layout's head
// (/build/react-router-web-experiment).

// Add these imports:
import { useEngagementBridge } from "./lib/engagement-bridge";
import { FeedbackButton } from "./components/FeedbackButton";

// Replace the App export:

export default function App({ loaderData }: Route.ComponentProps) {
  useEngagementBridge();

  const id = loaderData.user?.id;
  const plan = loaderData.user?.plan ?? "unknown";
  const lastIdentity = useRef<string | undefined>(undefined);

  useEffect(() => {
    const identity = id ? `user-${id}|${plan}` : "anonymous";
    if (identity === lastIdentity.current) return;
    lastIdentity.current = identity;
    if (!id) return;
    amplitude.setUserId(`user-${id}`);
    const identify = new amplitude.Identify();
    identify.set("plan", plan);
    amplitude.identify(identify);
  }, [id, plan]);

  return (
    <>
      <header>
        <FeedbackButton />
      </header>
      <Outlet />
    </>
  );
}

// Unchanged from earlier pages; keep your versions: .env, app/auth.server.ts, app/routes.ts, app/routes/new-project.tsx, the root loader in app/root.tsx.

Complete https://amplitude.com/build/react-router-product-analytics first, or
confirm this React Router framework mode app already has its setup;
create its app/auth.server.ts stub and app/routes/new-project.tsx route
at projects/new if they're missing. Then add Amplitude guides and
surveys by following https://amplitude.com/build/react-router-guides-surveys
exactly. Merge into existing shared files and never delete lines another
Amplitude Build page added; each file's first comment on that page names
them. Use @amplitude/unified's initAll, called once in
app/entry.client.tsx before hydrateRoot; never call engagement.init() or
engagement.boot(), and never initialize in a useEffect. Wrap initAll in
setAmplitudeReady from app/lib/amplitude-ready.ts and call
setAmplitudeReady(null) when VITE_AMPLITUDE_API_KEY is empty; change
nothing else in that file. Don't pass engagement: { skip: true }. Add
app/lib/engagement.ts with a typed getEngagement() that returns undefined
on the server, and app/lib/engagement-bridge.ts with a
useEngagementBridge hook that waits for amplitudeReady, ignores
StrictMode's cleaned-up run, and registers setRouter (same-origin URLs
through navigate(), others through window.location.assign) and an
open_new_project callback. In app/root.tsx, add the two imports and call
the hook at the top of the root App component; keep the getUser import,
the loader, Layout and any refetchBrowserFlags calls. Keep the identity
effect's early return when the user is null. In the sign-out form's
onSubmit, call getEngagement()?.gs.closeAll(), then amplitude.reset(),
then amplitude.experiment()?.clear(). Add data-guide="new-project-button"
to the New project link in app/routes/home.tsx without replacing the
file, and render a FeedbackButton in the root App that waits for
amplitudeReady and calls gs.show('product-feedback'). If the app sends a
CSP or COOP header, add https://*.amplitude.com to script-src,
connect-src, img-src, media-src, and style-src, and set COOP to
same-origin-allow-popups; if it already uses a nonce, pass it as
engagement: { nonce } in initAll. Don't hardcode the key and don't
invent survey or callback names. Report every file you changed.