Skip to content

feat: instrument ViewedAPIDocumentation with standardized properties#44

Merged
lhagenWP merged 1 commit into
whitepages:mainfrom
nkotolenko-cpu:smb-1310-amplitude-event-updates
Jun 8, 2026
Merged

feat: instrument ViewedAPIDocumentation with standardized properties#44
lhagenWP merged 1 commit into
whitepages:mainfrom
nkotolenko-cpu:smb-1310-amplitude-event-updates

Conversation

@nkotolenko-cpu

@nkotolenko-cpu nkotolenko-cpu commented Jun 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Replaces the code-side `WPAPIDocsPageViewed` rename plugin with the correct event name set at the SDK config level (`ViewedAPIDocumentation`), and adds an enrichment plugin that attaches Whitepages-standardized event properties to every Amplitude event fired from the docs site.

Changes

  • `src/lib/amplitude.ts`: remove `renameEventsEnrichmentPlugin` (which was renaming `[Amplitude] Page Viewed` → `WPAPIDocsPageViewed`); switch `pageViews: true` to `pageViews: { trackHistoryChanges: "all", eventType: "ViewedAPIDocumentation" }`; add `whitepagesPropertiesPlugin` that appends `PathName`, `Url`, `ReferringUrl`, `ReferringSite`, and `PageType: "APIDocumentation"` to all events — additive, preserving existing `[Amplitude] Page *` autocapture properties
  • `commitlint.config.js`: fix pre-existing ESM syntax (`export default`) incompatible with the CJS loader used by commitlint

Verification

On `bun run preview` (open-next + wrangler, mirrors production):

  • Navigate between two docs pages
  • DevTools → Network → filter `amplitude`: confirm POST payloads contain `event_type: "ViewedAPIDocumentation"`
  • Confirm each event has `PathName`, `Url`, `ReferringUrl`, `ReferringSite`, `PageType: "APIDocumentation"` in `event_properties`
  • Confirm `[Amplitude] Page *` autocapture properties are still present alongside the new ones

Ticket: SMB-1310

image

@nkotolenko-cpu nkotolenko-cpu force-pushed the smb-1310-amplitude-event-updates branch from e5e6207 to 9e33f22 Compare June 8, 2026 13:45
Comment thread src/lib/amplitude.ts Outdated
try {
return new URL(url).hostname;
} catch {
return "";

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This function returning an empty string does make particular sense. Allowing this to throw an exception seems more reasonable.

Comment thread src/lib/amplitude.ts Outdated
PathName: window.location.pathname,
Url: window.location.href,
ReferringUrl: referringUrl,
ReferringSite: referringUrl ? extractHostname(referringUrl) : "",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The referring site is not "" it is undefined.

Comment thread src/lib/amplitude.ts
autocapture: {
pageViews: true,
pageViews: {
trackHistoryChanges: "all",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like something that the Amplitude package would return an enumeration for.

Rename the autocaptured page-view event from the project-side
transformation name to ViewedAPIDocumentation at the SDK level.
Add an enrichment plugin that attaches PathName, Url, ReferringUrl,
ReferringSite, and PageType to every Amplitude event — additive,
preserving existing [Amplitude] Page * autocapture properties.

Ticket: SMB-1310
@nkotolenko-cpu nkotolenko-cpu force-pushed the smb-1310-amplitude-event-updates branch from 9e33f22 to cfdd515 Compare June 8, 2026 15:41
@nkotolenko-cpu

Copy link
Copy Markdown
Contributor Author

Addressed all three comments (force-pushed):

  • extractHostname: removed the try/catch and the helper entirely. document.referrer is spec-guaranteed to be either an empty string or a valid absolute URL, so new URL() won't throw on it.
  • ReferringSite: "": switched to a conditional spread so the key is omitted entirely when there's no referrer, rather than set to an empty string.
  • trackHistoryChanges: "all": checked the installed package — PageTrackingHistoryChanges is exported from @amplitude/analytics-core as a string literal union type ('all' | 'pathOnly'), not an enum. The string literal is the correct and idiomatic usage.

@lhagenWP lhagenWP merged commit 39305e0 into whitepages:main Jun 8, 2026
1 check passed
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.

2 participants