Amplitude implementation
Setting up Amplitude
Install the SDK, configure it sanely, and verify page views are flowing. One hour, end to end.
This is the first module in the implementation sequence. Roughly an hour of work. You'll install the SDK, configure it, and verify data is flowing.
Once you finish this chapter, you'll have:
- Page view events firing automatically
- Device, OS, browser, location data captured on every event
- Traffic source attribution working
- Enough data to build basic traffic and session reports
This isn't much compared to what Amplitude can do, but it's a complete foundation. Each subsequent module builds on it.
Install the SDK
The Browser SDK runs in the user's browser and captures client-side events. Install it via npm:
npm install @amplitude/analytics-browserIf you're using a different package manager — pnpm, yarn, bun — substitute as appropriate. The package is the same.
Get your API key
In Amplitude, navigate to Settings → Organization settings → Projects. Click your project (typically named "default") and copy the API key.
Initialize the SDK
Create a client component that initializes Amplitude. The example uses Next.js App Router, but the pattern (initialize in the browser, before any tracking calls) works in any framework.
// src/components/amplitude-client.tsx
"use client";
import * as amplitude from "@amplitude/analytics-browser";
async function initAmplitude() {
await amplitude.init(process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY!, {
fetchRemoteConfig: false,
autocapture: {
elementInteractions: false,
formInteractions: false,
pageViews: {
trackHistoryChanges: "pathOnly",
},
},
}).promise;
}
if (typeof window !== "undefined") {
initAmplitude();
}
export const Amplitude = () => null;
export default amplitude;A few things to note:
- The init is "fire and forget" — it starts asynchronously so it doesn't block your app's loading.
- The
typeof window !== "undefined"check prevents initialization during server-side rendering. - The configuration is opinionated; the next section covers each choice.
Mount the component in your root layout so it loads on every page:
// src/app/layout.tsx
import { Amplitude } from "@/components/amplitude-client";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<Amplitude />
<body>{children}</body>
</html>
);
}The recommended configuration explained
The init call sets four config options. Here's what each does and why.
fetchRemoteConfig: false
Disables Amplitude's ability to override config from its UI. You want one source of truth for SDK configuration — your codebase. If config can come from multiple sources (code + remote), debugging mismatches becomes painful, and future developers may not realize remote config is in play.
Keep config explicit, version-controlled, and visible in your repo.
autocapture.elementInteractions: false
Disables Amplitude's automatic capture of every element interaction (clicks, hovers, etc.). These events generate huge volumes of noise and rely on CSS selectors that aren't always reliable — meaning the data is both overwhelming and untrustworthy.
You'll track the interactions that matter explicitly. The ones Amplitude would auto-capture and you'd actually want, you can add intentionally with clean event names.
autocapture.formInteractions: false
Same reasoning. Auto-captured form events fire whether or not the form actually succeeded — meaning you'd get "form submitted" events for validation failures, server errors, and successful submissions all looking identical. You can't distinguish them without parsing the data, which defeats the purpose.
Instead, track form-related events explicitly after server confirmation — see Tracking on successful states.
autocapture.pageViews.trackHistoryChanges: "pathOnly"
Page views are useful and you want them auto-captured. The pathOnly setting ensures page views fire when the path changes (e.g., navigating from /dashboard to /customers) but not when only the hash fragment changes (e.g., /dashboard#open-modal).
If your app uses hash-based routing for modals or drawers and you want page views for those state changes, remove the pageViews configuration block entirely (so the default behavior is used, which captures every URL change).
Other configuration worth knowing
A few options you'll likely leave at defaults but should understand.
Event batching. By default, the SDK sends events in batches: every 1 second or every 5 events, whichever comes first. This is almost always the right behavior. If you set flushIntervalMillis: 0 and flushQueueSize: 1, events send immediately — useful for testing, almost never appropriate in production. Browsers throttle high-frequency requests, and Safari's ITP may block them entirely.
Session timeout. Defaults to 30 minutes of inactivity. The session ends 30 minutes after the last event, not 30 minutes from session start. For most SaaS, the default is fine. If your product has long idle periods (e.g., dashboards left open), consider increasing.
Tracking options. You can disable automatic capture of specific metadata (IP, region, device info) via the trackingOptions property. Useful for privacy compliance or minimizing data collection. Default is to capture everything.
Server URL (reverse proxy). You can route events through your own domain to bypass ad blockers. This requires running infrastructure that forwards events to Amplitude. Not needed for initial setup.
Validate the setup
After deploying, navigate to Live Events in Amplitude. You should see page view events flowing in as users navigate your site (yourself included).
Verify:
- Page views fire on every navigation. Path changes should produce events; hash-only changes should not.
- Event properties include path, title, and referrer. Check a few events and inspect the properties.
- Device properties are populated. Device type, OS, browser, screen resolution.
- Location is captured. Country, region, city via IP geolocation.
If events don't appear after a few minutes:
- Verify your API key is correct (and that you're using the right environment's key)
- Confirm the
Amplitudecomponent is rendered in your root layout - Check that your browser isn't blocking the requests (disable ad blockers, check the Network tab for requests to
api2.amplitude.com)
What you have now
- A working Amplitude installation
- Automatic page view, session, and device tracking
- Geographic and referrer attribution
- A foundation to build the next three modules on
The next module — authentication — is where analytics gets meaningfully useful. Tracking page views is fine; tracking users across sessions is what unlocks retention and lifecycle analysis.