Getting started

Goals, and who the visitor is

A goal is a thing a visitor did that you care about. Identifying a visitor is what turns a trail of visits into a person, and what lets a payment be matched by email when nothing else carries the identity.

Updated All docs as one Markdown file

A button as a goal

HTML
<button data-ml-goal="signup_click">Get started</button> <a href="/checkout" data-ml-goal="checkout_click" data-ml-goal-plan="pro">Buy Pro</a>

No JavaScript needed. Use short snake_case names; every data-ml-goal-* attribute becomes a property of the goal, so plan="pro" above is recorded with it. Funnels are built from goals and pageviews in the dashboard, step by step.

A goal from code

JavaScript
window.geckostats?.('goal', 'signup_completed', { plan: 'pro' });

Call it with optional chaining so a page never breaks when the script is blocked. Calls made before the script has loaded are queued and sent once it has. A goal that completes on your server goes through POST /api/v1/goals instead.

Identify a signed-in user

JavaScript
window.geckostats?.('identify', { user_id: user.id, email: user.email, name: user.name });

After a login or signup, and on app load when a session already exists. Earlier anonymous visits by the same visitor join the person, their profile shows the whole trail, and a payment that arrives with only an email is matched to them.

Newsletter links

Put ?ml_uid=<your subscriber id> on the links in a newsletter and the click is tied to that subscriber: the visit, what they read, and anything they buy afterwards. The id is yours and opaque here; never put an email address in it. The parameter is stripped from every address the script reports.

TypeScript

geckostats.d.ts
declare global { interface Window { geckostats?: ((cmd: 'goal' | 'identify' | 'pageview', a?: unknown, b?: unknown) => void) & { attribution?: () => { ml_visitor_id?: string; ml_session_id?: string }; }; } } export {};