@amplitude/wizard 1.0.0 → 1.2.0

package/dist/src/ui/tui/store.js

@@ -119,12 +119,24 @@ export class WizardStore {
     }
     setCredentials(credentials) {
         this.$session.setKey('credentials', credentials);
-        if (credentials?.projectId) {
-            analytics.setDistinctId(String(credentials.projectId));
+        const session = this.$session.get();
+        if (session.userEmail) {
+            analytics.setDistinctId(session.userEmail);
+            analytics.identifyUser({
+                email: session.userEmail,
+                org_id: session.selectedOrgId ?? undefined,
+                org_name: session.selectedOrgName ?? undefined,
+                workspace_id: session.selectedWorkspaceId ?? undefined,
+                workspace_name: session.selectedWorkspaceName ?? undefined,
+                project_id: session.selectedProjectId ?? credentials?.projectId,
+                project_name: session.selectedProjectName,
+                region: session.region,
+                integration: session.integration,
+            });
         }
         analytics.wizardCapture('Auth Complete', {
             project_id: credentials?.projectId,
-            region: this.session.region,
+            region: session.region,
         });
         this.emitChange();
     }
@@ -139,6 +151,9 @@ export class WizardStore {
     setFrameworkConfig(integration, config) {
         this.$session.setKey('integration', integration);
         this.$session.setKey('frameworkConfig', config);
+        if (integration) {
+            analytics.identifyUser({ integration });
+        }
         this.emitChange();
     }
     setDetectionComplete() {
@@ -294,6 +309,32 @@ export class WizardStore {
         this.$session.setKey('credentials', { ...creds, accessToken });
         this.$version.set(this.$version.get() + 1);
     }
+    /** Update both access and id tokens (e.g. after a silent OAuth refresh). */
+    updateTokens(accessToken, idToken) {
+        const creds = this.$session.get().credentials;
+        if (!creds)
+            return;
+        this.$session.setKey('credentials', { ...creds, accessToken, idToken });
+        this.$version.set(this.$version.get() + 1);
+    }
+    /**
+     * Restore org/workspace/project session IDs that weren't populated at startup
+     * (e.g. because the fire-and-forget fetchAmplitudeUser failed due to expired token).
+     * Only updates fields that are provided.
+     */
+    restoreSessionIds(fields) {
+        if (fields.orgId !== undefined)
+            this.$session.setKey('selectedOrgId', fields.orgId);
+        if (fields.orgName !== undefined)
+            this.$session.setKey('selectedOrgName', fields.orgName);
+        if (fields.workspaceId !== undefined)
+            this.$session.setKey('selectedWorkspaceId', fields.workspaceId);
+        if (fields.workspaceName !== undefined)
+            this.$session.setKey('selectedWorkspaceName', fields.workspaceName);
+        if (fields.projectId !== undefined)
+            this.$session.setKey('selectedProjectId', fields.projectId);
+        this.emitChange();
+    }
     /** Request the TabContainer to switch to a tab by id. Clears after consumption. */
     setRequestedTab(id) {
         this.$requestedTab.set(id);
@@ -330,21 +371,8 @@ export class WizardStore {
         analytics.wizardCapture('Data Ingestion Confirmed', sessionPropertiesCompact(this.session));
         this.emitChange();
     }
-    setChecklistChartComplete() {
-        this.$session.setKey('checklistChartComplete', true);
-        this.emitChange();
-    }
-    setChecklistDashboardComplete() {
-        this.$session.setKey('checklistDashboardComplete', true);
-        this.emitChange();
-    }
-    setChecklistComplete() {
-        this.$session.setKey('checklistComplete', true);
-        analytics.wizardCapture('Checklist Completed', {
-            chart_complete: this.session.checklistChartComplete,
-            dashboard_complete: this.session.checklistDashboardComplete,
-            ...sessionPropertiesCompact(this.session),
-        });
+    setChecklistDashboardUrl(url) {
+        this.$session.setKey('checklistDashboardUrl', url);
         this.emitChange();
     }
     setActivationOptionsComplete() {
@@ -376,6 +404,12 @@ export class WizardStore {
         this.$session.setKey('selectedOrgName', org.name);
         this.$session.setKey('selectedWorkspaceId', workspace.id);
         this.$session.setKey('selectedWorkspaceName', workspace.name);
+        // Extract the analytics project ID from the lowest-rank environment.
+        const projectId = workspace.environments
+            ?.slice()
+            .sort((a, b) => a.rank - b.rank)
+            .find((e) => e.app?.id)?.app?.id ?? null;
+        this.$session.setKey('selectedProjectId', projectId);
         // Write ampli.json to the project directory.
         // Use session.region (user-confirmed) over pendingAuthCloudRegion (auto-detected)
         // so that /region changes are respected.

package/dist/src/ui/tui/utils/diagnostics.js

@@ -51,9 +51,7 @@ export function createDiagnosticSnapshot(store, version) {
             mcp_complete: session.mcpComplete,
             slack_complete: session.slackComplete,
             data_ingestion_confirmed: session.dataIngestionConfirmed,
-            checklist_complete: session.checklistComplete,
-            checklist_chart_complete: session.checklistChartComplete,
-            checklist_dashboard_complete: session.checklistDashboardComplete,
+            checklist_dashboard_url: session.checklistDashboardUrl !== null,
             discovered_features: session.discoveredFeatures,
             additional_feature_queue: session.additionalFeatureQueue,
             amplitude_pre_detected: session.amplitudePreDetected,

package/dist/src/ui/wizard-ui.d.ts

@@ -107,4 +107,12 @@ export interface WizardUI {
         name: string;
         description: string;
     }>): void;
+    /** Emitted by agent mode when MCP polling detects events flowing into the project. */
+    setEventIngestionDetected(eventNames: string[]): void;
+    /**
+     * Called when the agent writes .amplitude-dashboard.json with the URL of
+     * the dashboard it created during the conclude phase. Surfaces the link in
+     * ChecklistScreen so users can open the dashboard immediately.
+     */
+    setDashboardUrl(url: string): void;
 }

package/dist/src/utils/analytics.d.ts

@@ -26,6 +26,21 @@ export declare class Analytics {
     private initPromise;
     constructor();
     setDistinctId(distinctId: string): void;
+    /**
+     * Send an identify call to associate user properties with the current user.
+     * Call after setDistinctId() has been called with a valid email.
+     */
+    identifyUser(properties: {
+        email?: string;
+        org_id?: string;
+        org_name?: string;
+        workspace_id?: string;
+        workspace_name?: string;
+        project_id?: string | number | null;
+        project_name?: string | null;
+        region?: string | null;
+        integration?: string | null;
+    }): void;
     setTag(key: string, value: string | boolean | number | null | undefined): void;
     captureException(error: Error, properties?: Record<string, unknown>): void;
     capture(eventName: string, properties?: Record<string, unknown>): void;

package/dist/src/utils/analytics.js

@@ -69,6 +69,43 @@ class Analytics {
     setDistinctId(distinctId) {
         this.distinctId = distinctId;
     }
+    /**
+     * Send an identify call to associate user properties with the current user.
+     * Call after setDistinctId() has been called with a valid email.
+     */
+    identifyUser(properties) {
+        const apiKey = resolveTelemetryApiKey();
+        if (!apiKey || !this.distinctId) {
+            (0, debug_1.debug)('identifyUser skipped (no API key or distinctId):', properties);
+            return;
+        }
+        this.ensureInitStarted();
+        const identifyObj = new analytics_node_1.Identify();
+        if (properties.email) {
+            identifyObj.setOnce('email', properties.email);
+        }
+        if (properties.org_id)
+            identifyObj.set('org_id', properties.org_id);
+        if (properties.org_name)
+            identifyObj.set('org_name', properties.org_name);
+        if (properties.workspace_id)
+            identifyObj.set('workspace_id', properties.workspace_id);
+        if (properties.workspace_name)
+            identifyObj.set('workspace_name', properties.workspace_name);
+        if (properties.project_id != null)
+            identifyObj.set('project_id', String(properties.project_id));
+        if (properties.project_name)
+            identifyObj.set('project_name', properties.project_name);
+        if (properties.region)
+            identifyObj.set('region', properties.region);
+        if (properties.integration)
+            identifyObj.set('integration', properties.integration);
+        this.client.identify(identifyObj, {
+            device_id: this.anonymousId,
+            user_id: this.distinctId,
+        });
+        (0, debug_1.debug)('identifyUser:', properties);
+    }
     setTag(key, value) {
         this.tags[key] = value;
     }

package/dist/src/utils/setup-utils.js

@@ -414,7 +414,12 @@ async function askForWizardLogin(opts = {}) {
             });
         }
         (0, ui_1.getUI)().log.success(`Logged in as ${chalk_1.default.bold(userInfo.email)}${selectedOrg ? ` (${selectedOrg.name})` : ''}`);
-        analytics_1.analytics.setDistinctId(userInfo.id);
+        analytics_1.analytics.setDistinctId(userInfo.email);
+        analytics_1.analytics.identifyUser({
+            email: userInfo.email,
+            org_id: selectedOrg?.id,
+            org_name: selectedOrg?.name,
+        });
         analytics_1.analytics.setTag('opened-wizard-link', true);
     }
     let selectedWorkspace;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amplitude/wizard",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "homepage": "https://github.com/amplitude/wizard",
   "repository": "https://github.com/amplitude/wizard",
   "description": "The Amplitude wizard helps you to configure your project",
@@ -139,6 +139,6 @@
     "test:bdd:watch": "cucumber-js --retry 0 2>&1 | npx nodemon --watch features --exec cucumber-js",
     "test:proxy": "vitest run --config vitest.config.proxy.ts",
     "test:proxy:smoke": "vitest run --config vitest.config.proxy.ts -t 'proxy:smoke'",
-    "skills:refresh": "bash scripts/refresh-instrumentation-skills.sh"
+    "skills:refresh": "bash scripts/refresh-skills.sh"
   }
 }

package/skills/integration/integration-android/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integration-android
-description: Amplitude integration for Android applications
+description: Amplitude integration for Android applications using the Kotlin SDK
 metadata:
   author: Amplitude
   version: dev
@@ -22,7 +22,7 @@ Follow these steps in order to complete the integration:
 ## Reference files
 
 - `references/EXAMPLE.md` - Android example project code
-- `references/analytics.md` - Amplitude documentation for Analytics
+- `references/android.md` - Amplitude documentation for Android
 - `references/amplitude-quickstart.md` - Amplitude documentation for Amplitude Quickstart
 - `references/basic-integration-1.0-begin.md` - Amplitude setup - begin
 - `references/basic-integration-1.1-edit.md` - Amplitude setup - edit
@@ -36,14 +36,11 @@ The example project shows the target implementation pattern. Consult the documen
 - **Environment variables**: Always use environment variables for Amplitude keys. Never hardcode them.
 - **Minimal changes**: Add Amplitude code alongside existing integrations. Don't replace or restructure existing code.
 - **Match the example**: Your implementation should follow the example project's patterns as closely as possible.
-
-## Framework guidelines
-
-- Adapt dependency configuration to the appropriate build.gradle(.kts) file according to the project gradle version
-- Call Amplitude(Configuration(apiKey = ..., context = applicationContext)).also { amplitude = it } only once in the Application class's onCreate() method, so it is initialized as early as possible and only once.
-- Initialize Amplitude in the Application class's onCreate() method
-- Ensure every activity has a android:label to accurately track screen views.
+- **Unified SDK**: For new browser/frontend projects, use `@amplitude/unified` as the default SDK — it bundles Analytics, Session Replay, Experiment, and Guides & Surveys in a single package. Initialize with `initAll()`. Only use `@amplitude/analytics-browser` if the project already has it installed.
+- **Event naming**: Event names MUST use Title Case with spaces following the [Noun] + [Past-Tense Verb] pattern (e.g., "Button Clicked", "Sign Up Completed", "Cart Viewed"). Do NOT use snake_case, camelCase, or SCREAMING_SNAKE. Property names should use snake_case (e.g., button_text, page_url).
+- **No PII in events**: Never send PII (emails, full names, phone numbers, physical addresses, IP addresses) in `track()` event properties. PII belongs in `identify()` user properties only.
+- **Autocapture**: Enable autocapture in the init config to automatically capture sessions, page views, form interactions, and file downloads. Use the `autocapture` config option (not the deprecated `defaultTracking`).
 
 ## Identifying users
 
-Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. Call `amplitude.setUserId(userId)` to associate events with a known user, and use `amplitude.identify()` with an `Identify` object to set user properties. If both frontend and backend code exist, pass a consistent user/device ID via custom request headers to maintain event correlation.
+Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. Call `amplitude.setUserId(userId)` to associate events with a known user, and use `amplitude.identify()` with an `Identify` object to set user properties. Call `amplitude.reset()` on logout to unlink future events from the current user. If both frontend and backend code exist, pass a consistent user/device ID via custom request headers to maintain event correlation.

package/skills/integration/integration-android/references/amplitude-quickstart.md

@@ -81,7 +81,7 @@
     }
   </style>
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tocbot/4.25.0/tocbot.css">
-  <link href="/docs/css/site.css?id=cf9c3f0a1066ff8b5d94a25cd8d407e1" rel="stylesheet">
+  <link href="/docs/css/site.css?id=6e2f9e1efe9343c4ba65666223648444" rel="stylesheet">
   <link href="/docs/css/algolia.css?id=e343cc9490e043fefffa37d2817ddf8c" rel="stylesheet">
   <link href="/docs/css/dracula-prism.css?id=a5713888be640854bb66b8b74c1037ce" rel="stylesheet">
 <style>