PennyLens
Get Started

SaaS Events

PennyLens detectors recognize a small set of reserved event names that describe the lifecycle of a SaaS user — signup, activation, engagement, and trial milestones. Wire these once and the AI insights pick up everything else automatically.

The SDK doesn't enforce the names — they're a convention the detectors look for. Anything you track outside of these still lands in your event stream as normal custom events.

Reserved event names

| Event | Purpose | | --- | --- | | signup | User account creation. Anchors cohort retention and trial timing. | | first_action | The "aha moment" — defined by you (e.g. created first project). Anchors activation-gap detection. | | core_feature_used | Engagement signal. The churn-risk detector uses frequency of this event to grade accounts. | | trial_started | Trial activation. Optional — if absent we fall back to signup + a configurable trial length. | | trial_expired | Trial end. Optional — used for trial-to-value reporting. |

Wiring example

pennylens.track("signup");
pennylens.track("first_action", { feature: "created_first_project" });
pennylens.track("core_feature_used", { feature: "invited_teammate" });

first_action and core_feature_used accept any JSON-serializable property bag. The feature field is conventional but not required.

Trial timing model

PennyLens uses a hybrid trial-timing model so you can be as precise or as loose as you want:

  • If both trial_started and trial_expired events are emitted, the trial-to-value detector uses those exact timestamps.
  • If they aren't emitted, the detector falls back to the signup timestamp plus your project's configured trial length (default 14 days).
  • If you set the trial length to null in your project settings, trial-to-value detection is skipped entirely — useful for free-forever products.
  • Activation-gap and D7 retention detection still run without any trial events.

When you haven't wired engagement yet

If a project has zero core_feature_used events when the detectors run, the churn-risk detector emits a low-severity insight:

Wire engagement events to unlock churn detection

The insight is dismissible per-user. It re-emits 30 days after dismissal if the instrumentation is still missing.

Fallback behavior for uninstrumented sites

Projects marked as SaaS but with none of the reserved events wired up behave gracefully — no errors, no false-positive insights. Detectors return null and the dashboard surfaces empty-state guidance instead.

The cohort retention chart on Overview displays:

Cohort retention appears once you have 2+ weeks of signup data.

until enough weekly cohorts exist to render the chart.

Next steps