amplitude-auto-tracker

Zero-config Amplitude auto-tracking for any browser app with a real DOM. Tracks <button> and <a> clicks with AI-generated English event names from Korean (or other) UI text at build time.

The runtime is a thin layer on @amplitude/analytics-browser and standard browser APIs—call initAmplitude once when your client UI is ready. Use AMPLITUDE_API_KEY or the apiKey option for the Amplitude key; other env names below are optional fallbacks some toolchains expose.

How it fits your stack

| Layer | What you need | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Runtime (initAmplitude) | Client-side bundle + DOM. Call it once when the UI is ready (e.g. after load / in your app’s startup hook). | | CLI (npx amplitude-auto-tracker) | Node.js. Scans ./app if that folder exists, otherwise ./src. Override with --dir for any project layout. | | Peer dependency | @amplitude/analytics-browser only. |

API key: Prefer initAmplitude({ eventNames, apiKey: "..." }). If you inject keys at build time, the library resolves (in order): AMPLITUDE_API_KEY → VITE_AMPLITUDE_API_KEY → NEXT_PUBLIC_AMPLITUDE_API_KEY. You can also map any env value into apiKey yourself.

How it works

[Build time]
npx amplitude-auto-tracker
    ↓
Scans your source files → extracts clickable text (<button>, <a>, buttonText, etc.)
    ↓
Calls OpenAI API once (new texts only)
    ↓
Updates lib/event-names.json → commit to git
    { "로그인": "login_clicked", "회원가입": "signup_clicked", ... }

[Runtime]
User clicks a button or link
    ↓
Instantly looks up event name from event-names.json (synchronous)
    ↓
Sends to Amplitude:
    - Event: "login_clicked"
    - event_display_name: "로그인"
    - location: "hero"  (from data-location or DOM inference)

Features

Auto-tracking with just button/link text

// Event name, location, and section are all mapped automatically.
<button>로그인</button>
<button>회원가입</button>
// → login_clicked, signup_clicked (with event_display_name)
// → location, section, button_type inferred from DOM

Build-time event name generation

• OpenAI API is called once at build time (only for new texts).
• Results are saved to lib/event-names.json and committed to git.
• The same text always produces the same event name across all users and sessions.

Automatic location tagging for duplicate text

When the same button/link text appears in multiple places, data-location is automatically inferred from the DOM — no manual tagging needed:

<header id="hero">
  <button>로그인</button>      // → location: "hero"
</header>
<section id="cta">
  <button>로그인</button>      // → location: "cta"
</section>
<section id="bottom-cta">
  <button>로그인</button>      // → location: "bottom-cta"
</section>

Location inference priority (traverses ancestors, manual override takes precedence):

1. Nearest <nav>, <header>, <footer>, <main>, <aside> or their id
2. <section> with an id (e.g. "cta")
3. <section> without an id → index-based (e.g. "section_2")

Manual override always wins:

<button data-location="pricing_cards">로그인</button>

Dynamic button text (toggle)

When a button label changes based on state, the event name is mapped from the visible text at the moment of the click:

const [isLoggedIn, setIsLoggedIn] = useState(false);

<button type="button" onClick={() => setIsLoggedIn((prev) => !prev)}>
  {isLoggedIn ? "로그아웃" : "로그인"}
</button>;
// Visible text is "로그인"  → login_clicked
// Visible text is "로그아웃" → logout_clicked

Installation

npm install amplitude-auto-tracker

Peer dependency:

npm install @amplitude/analytics-browser

Setup

1. Environment variables

# Amplitude (recommended; optional if you pass apiKey to initAmplitude)
AMPLITUDE_API_KEY=your-amplitude-key

# Optional — if your toolchain only exposes prefixed client env vars:
# VITE_AMPLITUDE_API_KEY=...
# NEXT_PUBLIC_AMPLITUDE_API_KEY=...

# CLI only — event name generation
OPENAI_API_KEY=sk-...

2. Generate event names

Run once, and re-run whenever you add new button/link text:

npx amplitude-auto-tracker

This scans your source directory for Korean text inside clickable elements (<button>, <a>, buttonText/label props) and generates English event names via OpenAI.

Options:

npx amplitude-auto-tracker --dir src              # custom scan directory (default: app/ or src/)
npx amplitude-auto-tracker --out lib/events.json  # custom output path (default: lib/event-names.json)

Commit the generated lib/event-names.json to git — it is the single source of truth for event names.

TypeScript: enable JSON imports in tsconfig.json if needed:

{
  "compilerOptions": {
    "resolveJsonModule": true
  }
}

3. Initialise tracking

Call initAmplitude once on the client after the document is ready. It attaches a document-level click listener and (when document.body exists) a MutationObserver for duplicate-text tagging.

Pass the generated event map:

import { initAmplitude } from "amplitude-auto-tracker";
import eventNames from "./lib/event-names.json";

initAmplitude({ eventNames });

Recommended: pass the key explicitly so behaviour is obvious in every bundler:

initAmplitude({ eventNames, apiKey: "your-amplitude-key" });

Example — run once on the client (adapt the lifecycle hook to your stack):

import { useEffect } from "react";
import { initAmplitude } from "amplitude-auto-tracker";
import eventNames from "./lib/event-names.json";

export default function App() {
  useEffect(() => {
    initAmplitude({ eventNames });
    // or: initAmplitude({ eventNames, apiKey: "..." });
  }, []);

  return <div>...</div>;
}

Vanilla JS example:

import { initAmplitude } from "amplitude-auto-tracker";
import eventNames from "./lib/event-names.json";

document.addEventListener("DOMContentLoaded", () => {
  initAmplitude({ eventNames, apiKey: "your-amplitude-key" });
});

4. Done!

All button and link clicks are now tracked automatically.

Manual tracking

import { handleTrackEvent } from "amplitude-auto-tracker";

handleTrackEvent("login_clicked", "로그인", {
  button_class: "primary",
});

Window event

Every tracked event fires an amplitude:track window event, useful for debugging:

import { AMPLITUDE_TRACK_EVENT } from "amplitude-auto-tracker";
import type { AmplitudeTrackDetail } from "amplitude-auto-tracker";

window.addEventListener(AMPLITUDE_TRACK_EVENT, (e) => {
  const { name, displayName, props } = (e as CustomEvent<AmplitudeTrackDetail>)
    .detail;
  console.log(name, props);
});

Data attributes

Override inferred values on any element:

<button
  data-location="pricing_cards"
  data-section="conversion"
  data-button-type="cta"
>
  시작하기
</button>

| Attribute | Description | Auto-inferred | | ------------------ | ---------------------- | ---------------------------------- | | data-location | Page-level location | Yes (nav/header/footer/section) | | data-section | Section classification | Yes (nearest <section id="...">) | | data-button-type | Element type hint | Yes (button or link) |

Event structure

// Basic
{
  event_type: "login_clicked",
  event_properties: {
    event_display_name: "로그인",
    button_text: "로그인",
    element_type: "button",
    text_length: 3
  }
}

// Duplicate text — location auto-tagged
{
  event_type: "signup_clicked",
  event_properties: {
    event_display_name: "회원가입",
    location: "cta",      // auto-inferred
    section: "main",
    ...
  }
}

// Manual data-* override
{
  event_type: "signup_clicked",
  event_properties: {
    event_display_name: "회원가입",
    location: "cta_section",  // manual value takes precedence
    section: "conversion",
    ...
  }
}

Event properties reference

| Property | Description | | --------------------------- | ----------------------------------- | | button_text / link_text | Element text content | | link_href | href for <a> elements | | element_id | Element's id attribute | | element_type | button or link | | text_length | Character count | | button_type | button or link | | location | DOM-inferred or overridden location | | section | DOM-inferred or overridden section | | event_display_name | Human-readable display name |

Overriding event names

Edit lib/event-names.json directly to rename events. Re-running npx amplitude-auto-tracker will never overwrite existing entries.

{
  "시작하기": "get_started_clicked",
  "로그인": "login_clicked",
  "회원가입": "signup_clicked"
}

Licence

MIT