Skip to content

fix(browser): normalize empty instance names - #1956

Draft
Mercy811 wants to merge 1 commit into
mainfrom
codex/sdkw-59-normalize-empty-instance-name
Draft

fix(browser): normalize empty instance names#1956
Mercy811 wants to merge 1 commit into
mainfrom
codex/sdkw-59-normalize-empty-instance-name

Conversation

@Mercy811

Copy link
Copy Markdown
Contributor

Summary

  • Add a shared Analytics Core normalizer so undefined and exactly '' resolve to $default_instance.
  • Make connector lookup defensive and retain the normalized value in BrowserConfig.
  • Route Browser Analytics initialization and identity updates through the normalized connector.
  • Let the Browser Experiment plugin inherit the Analytics instance name unless explicitly overridden.
  • Add regression coverage for default, empty, custom, whitespace, and explicit-override cases.

Why

Browser Analytics could bind identity and its event receiver to an empty-string connector while Experiment resolved the same input to $default_instance. The SDKs would initialize successfully but silently lose identity synchronization and Experiment exposure-event forwarding.

PR #1944 fixed the React Native occurrence that exposed this issue. This PR applies the corresponding Browser/Core fix tracked by SDKW-59.

Safety and storage impact

  • A full packages/analytics-browser search found that the configured instance name only routes in-memory connector activity.
  • The similarly named snippet createInstance(instanceName) registry is separate and is not changed.
  • The Analytics Connector stores identity, listeners, its receiver, and its bounded event queue only in memory under globalThis.analyticsConnectorInstances.
  • Browser identity/session, unsent-event, and attribution storage keys are based on the API key, not instanceName; no persistent storage migration is involved.
  • Non-empty custom names remain isolated and unchanged. Whitespace-only names are intentionally not trimmed.

Validation

  • Analytics Core: 884 tests passed, 100% coverage.
  • Browser Analytics: 509 tests passed, 100% coverage.
  • Browser Experiment plugin: 12 tests passed, 100% coverage.
  • Typecheck and lint passed for all three affected packages.

Ticket: https://linear.app/amplitude/issue/SDKW-59/normalize-empty-instancename-across-browser-analytics-and-experiment

Route Browser Analytics, Experiment, and identity updates through the same canonical connector.

Preserve explicit custom instance names. Refs SDKW-59.
@linear-code

linear-code Bot commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

SDKW-59

@github-actions

Copy link
Copy Markdown

size-limit report 📦

Path Size
packages/analytics-browser/lib/scripts/amplitude-min.js.gz 64.28 KB (+0.01% 🔺)
packages/session-replay-browser/lib/scripts/session-replay-browser-min.js.gz 134.98 KB (+0.01% 🔺)
packages/unified/lib/scripts/amplitude-min.umd.js.gz 218.42 KB (+0.02% 🔺)
@amplitude/element-selector (gzipped esm) 3.4 KB (0%)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant