Required dependencies

npm install @amplitude/analytics-browser tslib
# For Node.js usage:
npm install @amplitude/analytics-node tslib
# For React Native:
npm install @amplitude/analytics-react-native tslib
# Peer dependencies for browser (React playground):
npm install react react-dom

No native build steps are required for browser or Node.js. For React Native, run npx pod-install after install on iOS and ensure Android linking is complete via npx expo prebuild if using Expo.

Project setup

1. Copy the source/ directory into your project root (e.g., ./source/).
2. Add path aliases in tsconfig.json if you want to import from source directly:

   {
     "compilerOptions": {
       "paths": {
         "@amplitude/analytics-browser": ["./source/analytics-browser/src/index.ts"],
         "@amplitude/analytics-core": ["./source/analytics-core/src/index.ts"],
         "@amplitude/analytics-client-common": ["./source/analytics-client-common/src/index.ts"]
       }
     }
   }
   

3. Set your Amplitude API key. Use an environment variable:

   AMPLITUDE_API_KEY=your_api_key_here
   

4. For browser builds using Rollup or Webpack, ensure tslib is available (it is listed as a direct dependency in each package).
5. For the Node SDK, ensure node >= 14 is used. The browser SDK targets ES5/ESM via separate tsconfig files (tsconfig.es5.json, tsconfig.esm.json).

Public API

init

init(apiKey: string, userId?: string, options?: BrowserOptions): AmplitudeReturn<void>

Initializes the Amplitude SDK with your API key. Must be called before any other method. Pass userId to associate events with a known user from the start. options accepts config for server zone, cookie storage, transport, and more.

track

track(
  eventInput: string | BaseEvent,
  eventProperties?: Record<string, any>,
  eventOptions?: EventOptions
): AmplitudeReturn<Result>

Sends an analytics event. Pass a string event name or a full BaseEvent object. eventProperties is a flat key/value map attached to the event. Returns a promise-like AmplitudeReturn that resolves when the event is flushed.

identify

identify(identify: Identify, eventOptions?: EventOptions): AmplitudeReturn<Result>

Sends an identify call to set or update user properties. Build the Identify object using its chainable methods (set, setOnce, add, append, etc.) before passing it. Used whenever user profile data changes.

Revenue

class Revenue {
  setProductId(productId: string): Revenue
  setPrice(price: number): Revenue
  setQuantity(quantity: number): Revenue
  setRevenue(revenue: number): Revenue
  setEventProperties(properties: Record<string, any>): Revenue
}

Builder class for revenue events. Construct with new Revenue(), chain setters, then pass to revenue(). Used to log in-app purchases or subscription events accurately.

createInstance

createInstance(): AmplitudeBrowser

Creates an isolated AmplitudeBrowser instance with its own config and event queue. Use when running multiple Amplitude projects in the same browser context (e.g., multi-tenant apps).

parseLegacyCookies

parseLegacyCookies(
  apiKey: string,
  cookieStorage: Storage<UserSession>,
  deleteLegacyCookies?: boolean
): Promise<UserSession>

Reads and parses Amplitude v1 legacy cookies, returning a UserSession object. Use during SDK migration from v1 to v2 to preserve existing device/user/session IDs.

Working examples

Scenario - Basic browser event tracking

Initialize the SDK and track a custom event with properties in a TypeScript browser application.

import { init, track, flush } from './source/analytics-browser/src/index';

const API_KEY = process.env.AMPLITUDE_API_KEY ?? '';

// Initialize once at app startup
init(API_KEY, undefined, {
  defaultTracking: true,
});

// Track a custom event
track('Button Clicked', {
  button_name: 'sign_up',
  page: '/home',
});

// Flush pending events before page unload
window.addEventListener('beforeunload', () => {
  flush();
});

Scenario - User identification and properties

Identify a logged-in user and set user properties after authentication.

import { init, identify, setUserId } from './source/analytics-browser/src/index';
import { Identify } from './source/analytics-core/src/index';

init(process.env.AMPLITUDE_API_KEY ?? '');

function onUserLogin(userId: string, plan: string, age: number) {
  setUserId(userId);

  const identifyEvent = new Identify();
  identifyEvent.set('plan', plan);
  identifyEvent.set('age', age);
  identifyEvent.setOnce('initial_plan', plan);
  identifyEvent.add('login_count', 1);

  identify(identifyEvent);
}

onUserLogin('user-123', 'pro', 28);

Scenario - Revenue logging

Log a purchase event using the Revenue builder.

import { init, revenue } from './source/analytics-browser/src/index';
import { Revenue } from './source/analytics-core/src/index';

init(process.env.AMPLITUDE_API_KEY ?? '');

function logPurchase(productId: string, price: number, quantity: number) {
  const revenueEvent = new Revenue()
    .setProductId(productId)
    .setPrice(price)
    .setQuantity(quantity)
    .setRevenue(price * quantity)
    .setEventProperties({ category: 'subscription' });

  revenue(revenueEvent);
}

logPurchase('pro-monthly', 9.99, 1);

Scenario - Multiple isolated instances

Use createInstance when you need two independent Amplitude projects in the same page.

import { createInstance } from './source/analytics-browser/src/index';

const analyticsA = createInstance();
const analyticsB = createInstance();

analyticsA.init('API_KEY_PROJECT_A');
analyticsB.init('API_KEY_PROJECT_B');

analyticsA.track('Page Viewed', { project: 'A' });
analyticsB.track('Page Viewed', { project: 'B' });

File walkthrough

• analytics-browser/src/index.ts - Public entry point; re-exports all browser SDK methods from the default client singleton and named exports.
• analytics-browser/src/browser-client.ts - AmplitudeBrowser class implementation with full lifecycle management.
• analytics-browser/src/browser-client-factory.ts - Instantiates the default singleton client and exports createInstance.
• analytics-browser/src/config.ts - Browser-specific config defaults and merging logic.
• analytics-browser/src/cookie-migration/index.ts - Parses Amplitude v1 legacy cookies for SDK migration.
• analytics-browser/src/attribution/ - UTM, referrer, and campaign attribution parsing and tracking.
• analytics-browser/src/plugins/ - Built-in browser plugins (destination, identity sender, etc.).
• analytics-browser/src/storage/ - Cookie and localStorage adapters.
• analytics-browser/src/transports/ - HTTP fetch transport implementation.
• analytics-browser/src/video-capture/ - Video interaction capture utilities.
• analytics-browser/src/utils/ - Snippet helpers, misc utilities.
• analytics-browser/generated/ - Pre-built snippet files for CDN/GTM deployment.
• analytics-client-common/src/index.ts - Shared utilities: campaign parsing, cookie naming, session detection, storage helpers, analytics connector.
• analytics-core/src/index.ts - Core primitives: AmplitudeCore, Identify, Revenue, Config, Logger, MemoryStorage, CookieStorage, transport base classes, remote config client.
• analytics-node/ - Node.js SDK; mirrors browser SDK but uses Node-compatible transports and storage.
• analytics-react-native/ - React Native SDK with AsyncStorage backend.
• analytics-types/ - Shared TypeScript interfaces and type aliases consumed across all packages.

Common pitfalls and fixes

• init not called before track: All track/identify calls before init are queued via runQueuedFunctions; always await init in tests to avoid flaky results.
• Duplicate events in React StrictMode: StrictMode double-invokes effects; guard init with a ref or move it outside the component tree.
• Legacy v1 cookies not migrated: Call parseLegacyCookies during init options callback and pass the returned session fields into BrowserOptions to preserve device/session IDs.
• ESM/CJS interop in bundlers: The package ships both ES5 and ESM builds (tsconfig.es5.json, tsconfig.esm.json); point your bundler exports field to the ESM build for tree-shaking.
• tslib missing at runtime: tslib is a direct dependency; ensure it is not hoisted out of the package in monorepo setups (add to root dependencies or configure nohoist).
• Node.js fetch not available below v18: The FetchTransport uses native fetch; on Node < 18 install and polyfill node-fetch or upgrade Node.

Vibe-coding prompt template

I have dropped the Amplitude TypeScript SDK source into `./source/` in my project.
Please read `./source/USAGE.md` for the full API reference and setup instructions.

The upstream package is `@amplitude/analytics-browser` (browser SDK) and
`@amplitude/analytics-core` (core primitives).

My project is a [TypeScript / React / Node.js / Express] application.
Please integrate Amplitude analytics step-by-step:

1. Install required dependencies listed in USAGE.md.
2. Wire tsconfig paths so imports resolve to `./source/analytics-browser/src/index.ts`.
3. Add an `amplitudeService.ts` that calls `init`, exports `track`, `identify`,
   and `revenue` wrappers using the real exports from `./source/analytics-browser/src/index.ts`.
4. In my main entry file, initialize Amplitude with `process.env.AMPLITUDE_API_KEY`.
5. Track a "Page Viewed" event on each route change.
6. On user login, call `setUserId` and send an `Identify` event with `plan` and `email` properties.
7. Add a `logPurchase` helper using the `Revenue` class from `./source/analytics-core/src/index.ts`.

Use only the exports documented in USAGE.md. Do not invent any API methods.

License and credit

The Amplitude TypeScript SDK is open source. See source/LICENSE if present in the repository, or refer to the GitHub repository for the current license (MIT as of the latest release). Upstream package: @amplitude/analytics-browser.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。