Chris Tam · Last updated 12 November 2026
Amplitude feature flags let you control which version of a feature people see in an app built with Devin Desktop. Experimentation helps you compare what they do after seeing each version.
In this tutorial, you'll use Devin Local to build a demo that displays sample usage figures and simulates a report export. You'll add compact and expanded layouts, assign them with a flag, and track exposure after the assigned layout appears.
A browser demo that switches between compact and expanded usage reports using a feature flag. It keeps a compact fallback when no usable assignment arrives and tracks simulated exports separately from exposure.
Prerequisites
- Devin Desktop installed and signed in, with your local project folder open in its IDE. Use Devin Local for the implementation and review its proposed changes.
- Node.js 22.12 or later and Corepack with pnpm 10.33.2. The example pins Vite 8.3.4 and
@amplitude/unified1.1.43; it doesn't require another Build tutorial. - A development Amplitude project and its public client API key from Settings > Projects > your project > General. Confirm its US or EU data center. For flags, also obtain a client deployment key from the same project in Amplitude Experiment.
Sign up for Amplitude if you need an account, and compare plans for your project's allowances. Use synthetic data throughout this walkthrough.
1. Open the project and connect context
I use a small Vite app to make the generated changes easy to inspect. For a new example, create an empty repository. If you're extending an existing app, open its repository and preserve its setup instead.
mkdir amplitude-report-feature-flags
cd amplitude-report-feature-flags
git initOptionally connect Amplitude MCP for Devin Desktop so Devin Local can inspect your existing event names. Merge this server entry into the project's .devin/mcp_config.json, preserving other servers. Use https://mcp.eu.amplitude.com/mcp for an EU project.
{
"mcpServers": {
"amplitude": {
"url": "https://mcp.amplitude.com/mcp"
}
}
}In the Agents window, open Customize > MCPs, select This computer under Install MCPs for, and enable the server. Complete its Amplitude OAuth sign-in when prompted. Ask Devin Local which Amplitude projects you can access to confirm the connection. Devin Desktop's MCP reference covers project configuration and OAuth. An MCP connection uses your account permissions; keep the browser API key in .env.local.
Keep Gitignore access off under Devin Settings > Devin Local > Configuration. Enter credentials into the ignored .env.local yourself; give the agent variable names rather than values. Ignoring a file helps keep it out of agent context, but is not a security boundary for terminal commands you approve. Preserve existing MCP servers, AGENTS.md and nested rules.
2. Give the agent a precise implementation prompt
With the folder open, select Plan below Devin Local's input and paste the prompt. Plan mode explores the repository and writes a plan before implementation. Review its file list and checks, then click Implement to switch to Code. Review command and MCP tool requests as they appear.
Work in this repository and first inspect its app entry point, existing Amplitude initialization, consent flow, authentication, package manager, existing AGENTS.md and .devin/rules instructions. Use current Amplitude docs and report the source URLs. Before changing code, describe the files you will touch and any conflicting existing setup.
Read the complete reference app at https://github.com/amplitude/ampli-examples/tree/0f6b33751a384faf49539b7078aa3b84cb45908f/browser/coding-tools/feature-flags. Implement that standalone Vite report example, or merge the same behavior into the existing browser app. If you cannot read the reference, ask me to paste its files before implementing it. For the isolated development demo only: Use @amplitude/unified 1.1.43 with one initAll call and top-level serverZone. Read both a project API key and a client deployment key from Vite configuration; reject a blank deployment before initializing. Request sampleRate 0 and skip engagement. Set synthetic user build-web-flags-demo before fetch. Configure automaticExposureTracking false, retryFetchOnFailure false and throwOnError true so a failed fetch enters the fallback handler instead of reusing a cached assignment. Fetch report-layout once, accept only control and expanded, and display Compact fallback for empty, unknown or failed results. Control renders Compact; expanded shows daily totals. Call exposure(report-layout) once after the assigned DOM has had a paint opportunity. Do not expose the fallback. Keep conversions disabled while assignment is pending. Track Report Exported with report_period and layout_source only on export.
In an existing app, use its existing analytics client, confirmed user identity, consent lifecycle, and enabled products. Do not copy the demo synthetic IDs or its sample/skip choices into that client. If the existing installation is not Unified, propose a documented compatible integration before changing initialization; never add a parallel client. Preserve routes, authentication, replay privacy, consent and other product setup. Do not replace whole shared files or reset identity while authentication is anonymous or loading. Read only public client configuration through VITE_ variables; never use server or admin credentials. Keep .env.local ignored. Preserve the lockfile and frozen-install workflow. Report what was built, what was tested locally, and which service-side outcomes remain unverified. Stop the affected claim if current docs disagree; record both sources rather than guessing.MCP. Ask the connected agent to inspect the project's existing event names before adding Report Exported. If your taxonomy already defines this action, use its established name consistently in the app and product configuration.
3. Review the proposed changes
Review Devin Local's inline diff zones and accept or reject each hunk. Then inspect the repository diff before keeping the implementation. I check the initialization and privacy paths before the visible UI, because a working button doesn't prove the integration is configured correctly.
git diff -- package.json pnpm-workspace.yaml index.html main.js .gitignore .devin/mcp_config.json .devin/rules
git status --shortOpen every new file listed by git status too; git diff omits untracked files.
Confirm the agent uses initAll, sets serverZone at the top level, initializes once per page load, and preserves the existing client if the app already has one. Check that .env.local is ignored. Vite embeds VITE_ values in the browser bundle; these values may contain client ingestion or client deployment keys, never server, admin, or secret credentials.
The complete example uses a fixed synthetic identity. In an existing app, connect your confirmed application identity and consent lifecycle. Don't overwrite your login handler, navigation, or another product's instrumentation with this demo.
4. Check the complete reference implementation
These are complete files for the new standalone example. Compare them with the agent's result. In an existing app, merge the relevant imports, handlers, configuration, and DOM targets without replacing unrelated files.
The Unified SDK installation guide supplies the SDK setup. This reproducible example pins @amplitude/unified 1.1.43. The current API reference may document a newer release. In the pinned package, initialization returns a plain promise, so I await initAll directly.
The pinned Unified release includes a beta Experiment plugin. Review that dependency before adopting this exact version in production. Its underlying Experiment client supports throwOnError; the public configuration table does not list that option. The sample uses it so a rejected fetch keeps the fallback without exposing a cached assignment.
{
"name": "amplitude-build-feature-flags",
"private": true,
"version": "1.0.0",
"type": "module",
"packageManager": "pnpm@10.33.2+sha512.a90faf6feeab71ad6c6e57f94e0fe1a12f5dcc22cd754db40ae9593eb6a3e0b6b12e3540218bb37ae083404b1f2ce6db2a4121e979829b4aff94b99f49da1cf8",
"engines": {
"node": ">=22.12.0",
"pnpm": ">=10.21.0"
},
"scripts": {
"dev": "vite --host 127.0.0.1",
"build": "vite build",
"preview": "vite preview --host 127.0.0.1"
},
"dependencies": {
"@amplitude/unified": "1.1.43"
},
"devDependencies": {
"vite": "8.3.4"
}
}minimumReleaseAge: 10080
trustPolicy: no-downgradenode_modules/
dist/
.env.local
.env.qaVITE_AMPLITUDE_API_KEY=
VITE_AMPLITUDE_SERVER_ZONE=US
VITE_AMPLITUDE_DEPLOYMENT_KEY=<!doctype html>
<html lang="en">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Usage report demo</title></head>
<body>
<main>
<h1>Usage report</h1>
<p>84 actions in the past 7 days.</p>
<button id="start">Start demo</button>
<button id="export-report">Export report</button>
<p>Local exports: <span id="exports">0</span></p>
<p>Layout: <span id="layout">Compact</span></p>
<p id="detail" hidden>Daily totals: 12 actions per day.</p>
<p id="status" role="status">Demo stopped. Use synthetic data only.</p>
</main>
<script type="module" src="/main.js"></script>
</body>
</html>import * as amplitude from "@amplitude/unified";
const deploymentKey = (import.meta.env.VITE_AMPLITUDE_DEPLOYMENT_KEY || "").trim();
let layoutSource = "fallback";
const apiKey = (import.meta.env.VITE_AMPLITUDE_API_KEY || "").trim();
const zone = (import.meta.env.VITE_AMPLITUDE_SERVER_ZONE || "US").trim();
const status = document.querySelector("#status");
const startButton = document.querySelector("#start");
const exportButton = document.querySelector("#export-report");
let started = false;
let starting;
let exports = 0;
exportButton.addEventListener("click", () => {
exports += 1;
document.querySelector("#exports").textContent = String(exports);
if (started) amplitude.track("Report Exported", { report_period: "7d", layout_source: layoutSource });
});
startButton.addEventListener("click", () => {
if (starting) return;
if (!apiKey || !["US", "EU"].includes(zone) || !deploymentKey) {
status.textContent = "Add the development configuration and restart Vite. Local export still works.";
return;
}
startButton.disabled = true;
starting = start().catch(() => {
status.textContent = "Setup failed. Check configuration and connectivity, then reload.";
});
});
async function start() {
await amplitude.initAll(apiKey, {
serverZone: zone,
analytics: { autocapture: false },
sessionReplay: { sampleRate: 0 },
experiment: { deploymentKey, automaticExposureTracking: false, retryFetchOnFailure: false, throwOnError: true, fetchTimeoutMillis: 5000 },
engagement: { skip: true },
});
amplitude.setUserId("build-web-flags-demo");
started = true;
const client = amplitude.experiment();
if (!client) throw new Error("Experiment client unavailable");
// Do not log conversions under a fallback while assignment is still pending.
exportButton.disabled = true;
try {
await client.fetch();
const value = client.variant("report-layout").value;
if (value === "control" || value === "expanded") {
layoutSource = "assigned";
document.querySelector("#layout").textContent = value === "expanded" ? "Expanded" : "Compact";
document.querySelector("#detail").hidden = value !== "expanded";
await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
client.exposure("report-layout");
status.textContent = `Assigned ${value}; device ${amplitude.getDeviceId()}.`;
} else {
status.textContent = "No usable assignment. Compact fallback; no assigned exposure.";
}
} catch {
status.textContent = "Fetch failed. Compact fallback; no assigned exposure.";
} finally {
exportButton.disabled = false;
}
}Install from the checked-in manifest. Commit the generated lockfile, and use a frozen install in repeatable builds.
corepack enable
corepack prepare pnpm@10.33.2 --activate
pnpm install
cp .env.example .env.localFill in .env.local with the development configuration. The client key is public and limited to ingestion, but keeping it in local configuration avoids tying shared source to one project. See Vite's environment-variable reference for rebuild and browser-exposure behavior.
5. Configure the development project
Create a feature flag in the development project with key report-layout. Use remote evaluation, add the values control and expanded, and attach the client deployment whose key you configured. Keep the general rollout at zero while testing; put only your intended synthetic testers in test targeting and save the configuration.
Flag key: report-layout
Values: control, expanded
Synthetic user: build-web-flags-demo
control display: Compact
expanded display: Expanded, with daily totals
Fallback display: Compact, layout_source=fallback
Conversion: Report ExportedTest the two values separately in your development targeting. A fetch returning HTTP 200 can still contain no assignment for this flag. The app exposes only a recognized assigned value, and it records layout_source so fallback exports can be distinguished from assigned exports.
For an experiment, create an experiment or convert the flag, configure [Experiment] Exposure as its exposure event, and save Report Exported as the primary conversion metric. Review the hypothesis and targeting before selecting Start Experiment. A flag assignment alone doesn't mean an experiment has started or produced a statistically reliable result.
The sample requests a zero replay sample rate. Check the development project's replay capture settings too. Preserve any existing replay consent and privacy configuration when merging.
6. Run the report
Start Vite and open the local URL it prints. Export once before starting the SDK to confirm the report remains usable when analytics is unconfigured. Then tap Start demo once and perform the product check below.
pnpm devAfter the development check, stop the server and verify the production build. Restart Vite after changing environment configuration.
pnpm install --frozen-lockfile
pnpm buildFor UI debugging, ask Devin Local to open a Preview, then use Send element on the report control to include its rendered element in your next prompt. Open the same local URL in your system browser for Network and Instrumentation Explorer checks. Preview rendering alone does not verify Amplitude delivery.
Verify it worked
- Leave either client key blank. Export locally and tap Start demo. Confirm the configuration warning, Compact fallback, and no SDK initialization. A missing deployment key must not silently select another deployment.
- With valid development keys, target
build-web-flags-demotocontrol. Start once and confirm the report shows Compact with an Assigned status. Export once. - In a separate page load, target the same synthetic tester to
expanded. Confirm the extra daily totals appear before the assigned exposure and export. Keep the general audience unchanged. - Test an empty or unavailable assignment. Confirm Compact fallback, no assigned exposure, and
layout_source: fallbackon any export tracked after initialization. - In User Lookup, check the processed
[Experiment] ExposureandReport Exportedevents for the same user, device, and test time. The integrated SDK sends the exposure; don't add a second custom exposure event. - Open the experiment and confirm its saved exposure definition, primary conversion metric, deployment, and started state. Verify that processed test activity belongs to that setup. Do not infer a winner from a passing integration test.
Troubleshooting
Start demo asks for configuration. Fill in .env.local and restart Vite. The guard deliberately leaves the SDK stopped when the required client configuration is missing or the region isn't US or EU.
The report stays Compact. Check whether the status says Assigned control or fallback. Verify the exact flag key, values, deployment association, tester inclusion, saved state, and region.
A missing deployment still returns flags in another app. This example rejects an empty client deployment key. Without that guard, the Unified integration can fall back to the project API key's deployment.
An exposure arrives before the assigned report appears. Keep automatic exposure disabled and the explicit exposure call after rendering. Remove automatic reads or duplicate exposure calls added by the agent.
The fetch fails. Keep the usable Compact fallback. Check connectivity and targeting, then reload for a new attempt. The pinned SDK uses throwOnError: true to reject failed fetches instead of continuing with cached assignments. The demo disables background fetch retries and doesn't retry initialization within the same page load.
The agent added a second SDK or broke an existing route. Review the repository's original entry point and merge into its existing client. Keep one Amplitude initialization for this app; don't combine this example with a second script loader or independently initialized browser package.
FAQ
Does this measure Devin usage or the app I build?
This measures the application you build or maintain with Devin Local. Devin Desktop helps edit and review its code; the Amplitude SDK runs in your app.
Which Amplitude key goes in the browser app?
The browser app uses a public project API key and a client deployment key. An MCP connection authenticates separately. Keep server deployment keys, admin tokens, and secret keys out of browser configuration and committed source.
Can I use this in an existing React or Next.js app?
Yes. Have the agent merge the behavior into the existing browser entry point and client. Preserve authentication, consent, and routing. The standalone reference uses Vite; a server-rendered app needs its framework's browser-only lifecycle rather than a direct copy of the Vite entry file.
Does a successful build prove the product works?
No. A build checks that the browser app can be bundled. The Verify section separately checks the rendered experience, processed activity, and the product result. Record which checks you performed before broadening the audience.
Will the agent make the same changes every time?
Treat its output as a change to review. Keep the explicit prompt, pinned reference, and repository rules, then compare its diff with the required behavior. An agent can propose a different implementation without establishing that its SDK calls or product settings are correct.
Full code reference
Step 4 contains every application and configuration file. Download the complete example with its lockfile and setup README. Keep .env.local ignored and commit the package lock when you customize the example.
Keep the rules in your repository
Save this Devin Desktop project rule as .devin/rules/amplitude-feature-flags.md. Preserve existing rules. trigger: always_on includes its body in each chat; review any later edit to the rule along with the app code.
---
description: Amplitude report instrumentation
trigger: always_on
---
## Amplitude report instrumentation
Inspect existing Amplitude initialization, consent, authentication and project rules first.
Use the existing client and current official SDK documentation. Initialize once.
In a Unified integration, keep serverZone at the options' top level.
Preserve enabled products, identity, routes, private-data controls and the lockfile.
Synthetic users, sampling and skip options in a standalone demo are not host-app defaults.
Do not add a parallel client when merging into an existing integration.
Keep private and server credentials out of browser configuration and source.
Keep report-layout assignment and the rendered report in sync.
Fetch after the confirmed identity is set, then handle empty, unknown and failed results.
Use one exposure method for this path; expose only the recognized assigned layout after render.
Keep fallback exports distinguishable and conversions disabled while assignment is pending.
Do not start an experiment or change audience targeting as part of a code edit.
Record what was built, locally tested and observed in the live service separately.
If sources conflict, record both and pause the affected claim before implementation.What this unlocks
Product analytics shows Report Exported for the same identity used by this example. The feature flags and experiments integration pairs [Experiment] Exposure with Report Exported so you can compare exports after each assigned layout. Keep the event name and report-period property consistent as you extend the app.
Next steps
Reference docs
Amplitude is the leading all-in-one analytics platform for building better products. Product and engineering teams use Amplitude to connect product analytics and web analytics with session replay, heatmaps, experimentation, feature flags, and guides and surveys in one unified workflow, with AI agents working across all of it. Learn how Amplitude is building self-improving products with Wave, helping teams turn product data into PRs.