@kissmetrics/install
v0.5.0
Published
Zero-config installer for the Kissmetrics web tracking snippet. Run: npx @kissmetrics/install --api-key <KEY>
Downloads
542
Readme
@kissmetrics/install
Add Kissmetrics tracking to your website with one command, no tracking code to write.
This installer finds your project's framework, drops the Kissmetrics snippet into the right file, and from then on your pageviews, clicks, and form submissions are tracked automatically. (That automatic tracking is called autocapture: you don't add a tracking call to each button or form yourself.)
Heads-up on form data: autocapture records form-field values. Fields that look like personal data (email, phone, name, address, …) are masked to
<redacted>by default, and password/file/hidden fields are never sent — but any other field's value is captured unless you mark it. See Control form field values to opt fields in or out.
npx @kissmetrics/install --api-key <YOUR_PRODUCT_KEY>Local use at the bottom. Everything else below works exactly the same.
Requirements
- Node 18 or newer. Check with
node --version. - Your Kissmetrics product key: the value you pass to
--api-key, found in your product's settings in Kissmetrics.
Quick start
From the root of the project you want to track:
npx @kissmetrics/install --api-key <YOUR_PRODUCT_KEY>Want to see what it would change before it touches anything? Add --dry-run.
What happens when you run it
- Scans the current directory (or the one you pass with
--dir <path>). - Detects your framework and picks the file to edit:
- Next.js (App Router): adds
import Script from "next/script"and a<Script id="kissmetrics">just inside<body>of yourapp/layout.*(orsrc/app/layout.*). - Plain HTML / SPA: inserts the
<script>before</head>of yourindex.html/public/index.html(or before</body>if there's no<head>). - Anything it can't safely edit: prints the snippet for you to paste in by hand. It never guesses.
- Next.js (App Router): adds
- Shows you the change and asks you to confirm (skip the prompt with
--yes). - Writes the snippet. This step is idempotent: if the file already has the snippet, it's left untouched, so re-running is always safe.
Next.js Pages Router isn't auto-edited yet. For those projects the installer prints the snippet for you to paste into
pages/_app.
Verify it's working
- Deploy your site, or run it locally.
- Open a page in your browser and click around or submit a form.
- In Kissmetrics, open your product and click Verify installation. It turns green once your first events arrive.
What gets tracked automatically
Once the snippet is in place and the Kissmetrics library loads, the following
are captured with zero app code. Each kind of interaction is recorded as
one generic event, and what specifically was clicked or submitted lives in
the event's properties. That keeps reports clean: you get one
Button Clicked event you break down by Text, not a new event per label.
Properties with no value are dropped, never sent empty.
| Captured | Event name | Properties |
|---|---|---|
| Pageviews: the first page load, plus client-side route changes in single-page apps (History API / back-forward button). | Viewed Page | Current Page, Page URL; Previous Page (site-relative path, on SPA navigation) or Referrer URL (the full external URL, on first load) |
| Clicks on any <button> or <a> | Button Clicked | Element, Current Page, Text (plus Id / Href when the element has them) |
| Form submissions | Form Submitted | Current Page, Form Id / Action when present, and a single Form Values object holding each visible field keyed by its name/id (nested so your field names can't collide with standard properties). Password, file, hidden, and button fields are never captured; checkboxes and radios only when checked. Fields that look like personal data (email, phone, name, address, SSN, card, and similar) have their value masked to <redacted> by default so the field's presence is recorded without leaking its value. |
Customize what's tracked
You rarely need to touch code, but you have full control. The names and values
below ("Upgrade Clicked", "Watched Demo", [email protected], …) are just
examples; swap in whatever matches your product.
Give one element its own event name: add data-km-event="..." to a button,
link, or form. That element then records under your name instead of the generic
Button Clicked / Form Submitted:
<button data-km-event="Upgrade Clicked">Go Pro</button>
<form id="signup" data-km-event="Signup Submitted">…</form>Exclude an element from tracking: add data-km-skip to any button, link,
or form you don't want captured:
<form id="internal-search" data-km-skip>…</form>Control form field values: sensitive-looking fields are masked to
<redacted> by default. Override per field: data-km-capture sends the real
value (for a non-sensitive field you do want, like a plan chooser), and
data-km-redact masks any field you consider private.
<input name="plan" data-km-capture /> <!-- send the value -->
<input name="coupon" data-km-redact /> <!-- always mask it -->Record your own event from code: the snippet sets up the _kmq queue, and
each command is one _kmq.push([...]):
window._kmq = window._kmq || [];
// Record a custom event; the object holds properties describing it.
window._kmq.push(['record', 'Watched Demo', { seconds: 90 }]);
// Identify the visitor: ties this browser's events (including the anonymous
// ones from before) to a known person. Call once, at login / signup.
window._kmq.push(['identify', '[email protected]']);
// Set a property on the person (their current state, not a one-off event).
window._kmq.push(['set', { plan: 'pro' }]);Only pass properties you actually have; skip one rather than send a placeholder.
identify is all you need to put a name to a visitor. The rarer alias merges
two already-known identities (e.g. an email change). Note KM's built-in alias
takes the surviving id first, then the old one, so to merge old into new:
window._kmq.push(['alias', '[email protected]', '[email protected]']).
Options
| Flag | Description |
|------|-------------|
| --api-key <key> | Your Kissmetrics product key (required) |
| --framework <id> | Force a target: nextjs or html (default: auto-detect) |
| --dir <path> | Project directory to install into (default: current directory) |
| --dry-run | Show what would change without writing any files |
| --yes, -y | Skip the confirmation prompt |
| -h, --help | Show help |
When it can't finish
If the installer can't complete (no target it can safely edit, or a write that doesn't land), it never leaves you stuck. It prints a recovery ladder: the exact snippet to paste by hand, the one command to add our Claude Code skill, and where to verify. It also sends one anonymous diagnostic to Kissmetrics so we can see and fix installs that fail.
A verified success is silent. The diagnostic never includes your product key, your
file contents, or your hostname: only the outcome, this package's version, your
Node version, your OS, and the detected framework. Turn it off with
--no-telemetry, or KM_DISABLE_TELEMETRY=1 / DO_NOT_TRACK=1. The recovery
ladder still prints.
Troubleshooting
| Symptom | Likely cause & fix |
|---|---|
| command not found / a 404 for the package | You need Node 18+ and network access. Check node --version; re-run npx @kissmetrics/install@latest --api-key <key>. |
| "Couldn't safely auto-install" | The installer only auto-edits Next.js App Router and plain HTML/SPA entry points. For any other stack it prints exact paste-in steps — follow those. |
| It ran, but Verify installation stays gray | (1) You haven't deployed the change yet, or you're viewing a build that predates it. (2) You opened the page but didn't click / navigate, so no event fired. (3) An ad/tracker blocker is blocking trk.kissmetrics.io — test in a clean profile. Give it ~1–2 minutes after the first event. |
| Installed in a monorepo but nothing tracks | You may have run it in the wrong package. Re-run with --dir <path-to-the-web-app>. |
| Two <head>s / multiple app entry points | The installer edits the first one it finds. Confirm the file it reported is the one your site actually serves; use --framework / --dir to steer it. |
| Duplicate pageview or click events | You likely have both this snippet and a legacy KM Event Manager rule. The snippet de-dupes KM's click/submit rules automatically, but remove any duplicate hand-written tracking. |
Still stuck? Paste the snippet by hand (see When it can't finish) — it works on any stack.
Privacy & consent
This snippet begins tracking as soon as it loads. If you operate under GDPR, ePrivacy, CCPA, or a similar regime, you are responsible for obtaining any required consent before it runs. Two common patterns:
- Gate the snippet: only inject / load it once the visitor has accepted analytics
in your consent banner (e.g. render the
<script>conditionally). - Mask aggressively: sensitive-looking fields are
<redacted>by default; adddata-km-redactto any additional field you consider personal, and avoiddata-km-captureon anything that could identify a person without consent.
Kissmetrics is a data processor for the events you send; deciding the lawful basis and wiring up consent is the site owner's responsibility.
Local development
Working on the installer itself? Run it straight from a clone of this folder against any project:
# from the project you want to track:
npx --yes /path/to/km-npx-installer --api-key <KEY> --framework nextjs
# or run the bin directly, with --dir (preview using --dry-run):
node /path/to/km-npx-installer/bin/cli.js --api-key <KEY> --dir ./my-site --dry-run