--- title: "Amplitude onboarding and initial setup, done right" canonical_url: https://ampl.webclat.com/guides/amplitude-onboarding-and-initial-setup description: "The setup sequence that avoids the most common new-instance mistakes: project structure, environments, tracking plan first, identity strategy, and the order to do it all in." source: Webclat | Amplitude Solutions (official Amplitude partner, independent consultancy) --- # Amplitude onboarding and initial setup, done right **In short:** A new Amplitude instance goes wrong most often not from a bad SDK integration but from skipped sequencing - instrumenting before the tracking plan exists, mixing staging and production events in one project, or deciding on identity strategy after code is already shipped. Getting onboarding right means fixing that order: plan, then structure, then instrument, then govern - never the reverse. ## What it is Amplitude onboarding covers everything before the first meaningful chart gets built: organization and project structure (how many projects, and why), environment separation (staging vs. production), the initial tracking plan, identity strategy (how anonymous and identified users merge), and the first round of SDK or data-pipeline instrumentation. It is easy to treat onboarding as purely technical ("install the SDK, call init"), but the decisions that are hardest to reverse later - project structure and identity strategy specifically - are organizational and analytical decisions, not SDK configuration, and they need to be made deliberately before instrumentation starts. ## When you need it - You're standing up a brand-new Amplitude instance for a product that has no existing event data - the highest-leverage moment to get structure right, because every later cohort, chart, and integration inherits whatever project and identity decisions get made here. - You inherited an existing Amplitude instance with unclear or undocumented setup decisions and need to establish (or reconstruct) what the project structure and identity strategy actually are before trusting any analysis built on top of them. - You're adding a new product surface (a new app, a new platform) to an org that already runs Amplitude elsewhere, and need to decide whether it belongs in an existing project or a new one. ## Implementation, done properly 1. Decide project structure before writing any tracking code: one project per distinct product experience with genuinely different user bases and event vocabularies is the common pattern, while a single product's web and mobile clients usually belong in the same project so cross-platform funnels and cohorts work without joining data across projects by hand. 2. Separate environments from day one - a staging or development project (or a clearly-flagged environment property) distinct from production, so test traffic, QA runs, and internal team usage never pollute the numbers a stakeholder will eventually present from. 3. Write the tracking plan before instrumenting anything: name the core actions that answer the product's actual open questions, assign an owner to each, and only then start writing SDK calls against that plan - instrumenting first and naming things as you go is exactly how inconsistent, duplicate-heavy event catalogs get built. 4. Decide identity strategy explicitly: when does an anonymous device get merged into an identified user (at signup? at login on a second device?), what goes in user properties versus event properties, and what the logout behavior is - these decisions are expensive to change retroactively because changing them can fragment or double-count historical user counts. 5. Instrument core events first (activation, the primary value action, retention-relevant repeat actions) and expand from there, rather than trying to track everything the product does in the first sprint - a smaller, well-governed event set that's actually queried beats a large one built on guesswork about what might matter later. 6. Set up baseline governance before opening the instance to the wider team: a naming convention enforced (or at least documented) from the start, and a clear owner for the tracking plan itself, so the second and third people who add events follow the same rules the first did. ## How to verify it worked 1. In Amplitude's Events explorer, confirm the first batch of instrumented events are arriving with the property types and values the tracking plan specifies - not just that events of the right name are showing up. 2. Create a test user, walk them through the product's real signup and core-action flow, and confirm in User Look-Up that their event history reads as one coherent session under one user, not fragmented across multiple anonymous device profiles - this is the fastest way to catch an identity-strategy problem before it's baked into weeks of production data. 3. Confirm staging and production event streams are actually separated - check that internal team and QA activity from the days after launch is not appearing in whatever project or environment a stakeholder will eventually pull real numbers from. 4. Have someone outside the setup process (a PM, a second engineer) pull one basic chart - a funnel or a simple event count - using only the tracking plan documentation, with no help from whoever built the instrumentation. If they can't find the events they need or don't trust the naming, the documentation and governance step needs another pass before wider rollout. ## FAQ ### How long should initial Amplitude onboarding realistically take? For one product surface with a clear core action, a properly sequenced setup - tracking plan, structure decisions, initial instrumentation, and QA - typically runs a few weeks rather than days; rushing straight to instrumentation to hit a shorter timeline is usually what produces the identity and taxonomy problems that cost far more time to fix later. ### Should we import historical event data from our previous analytics tool during onboarding? Only after the tracking plan and identity strategy are settled - importing historical data before those decisions are made means re-mapping the import once the schema changes, twice the work for one migration. If a migration is in scope, treat it as its own project phase after new instrumentation is live and validated, not a parallel-track shortcut. Related: [Free tracking plan template](https://ampl.webclat.com/resources/tracking-plan-template), [The 30-item implementation checklist](https://ampl.webclat.com/resources/implementation-checklist), [Use case: a tracking plan that survives your next redesign](https://ampl.webclat.com/use-cases/tracking-plan-that-survives-your-next-redesign)