Documentation

Everything you need to install, configure, and get the most out of Pulse.

Quick Start

Get Pulse running on your site in under 5 minutes.

1. Sign up

Create your account at pulse.hatched.digital/login. You'll get a 14-day free trial — no credit card required.

2. Add your site

In the onboarding flow, enter your site's URL. We'll generate a unique API key for you.

3. Add the tracker snippet

Add this single script tag to your site's <head>:

<script defer src="https://pulse.hatched.digital/t.js"
  data-site-id="YOUR_SITE_ID">
</script>

Replace YOUR_SITE_ID with the site ID shown in your dashboard. It's a public identifier — not a secret.

4. Verify

Click "Verify" in the onboarding flow. Pulse will check that events are coming through.

That's it — you're live. Your first AI report will arrive at the end of the week.

Tracker Reference

The Pulse tracker is a < 8KB JavaScript file that collects behavioural data without cookies or personal data.

Script Attributes

Attribute	Required	Description
`data-site-id`	Yes	Your site ID (shown in the dashboard)
`data-endpoint`	No	Custom endpoint URL (defaults to script origin)

Automatic Tracking

The tracker automatically collects:

Core events (v1):

Pageviews — path, referrer category, breakpoint, connection type, UTM parameters, isLanding flag
Scroll depth — milestones at 25%, 50%, 75%, 90%, 100%
Clicks — 10×20 grid coordinates (no personal data)
Rage clicks — 3+ clicks in same zone within 2 seconds
Dead clicks — clicks with no DOM response within 500ms
Form interactions — focus, blur, abandon, submit (field names only, no values)
Exit intent — mouse leaving viewport (fires once per session)

Advanced behavioural events (v2):

Scroll velocity — fast-scrolling segments that reveal content being skipped
Content exposure — time-in-viewport per section (using data-pulse-section)
CTA hesitation — hover over CTA > 2s without clicking (indicates friction)
First interaction — time from page load to first meaningful action
Copy text — fires when user copies text (captures nothing about the text itself)
Tab focus — visibility changes to detect multi-tab browsing patterns
Performance — Core Web Vitals sampled from real sessions
Outbound clicks — clicks on external links with destination domain

Element Tracking

Add data-pulse-track to any element to track visibility and clicks:

<button data-pulse-track="cta-hero">Get Started</button>

Section Time

Add data-pulse-section to measure time spent in viewport:

<section data-pulse-section="pricing">...</section>

Conversion Tracking

Fire custom conversion events from JavaScript:

window.pulse.track("signup_completed");
window.pulse.track("checkout_started");

SPA Support

The tracker automatically detects SPA navigation by intercepting pushState, replaceState, and popstate. No extra configuration needed for Next.js, React Router, Vue Router, etc.

Privacy

The tracker never collects:

IP addresses
Cookies
User agent strings (parsed to OS family + browser family only)
Form field values
DOM content
Full referrer URLs

Element Tracking

Track any element's visibility and click rate by adding a data-pulse-track attribute.

Setup

<!-- Track a CTA button -->
<button data-pulse-track="hero-cta">Start Free Trial</button>

<!-- Track a pricing card -->
<div data-pulse-track="pricing-pro">...</div>

<!-- Track a form -->
<form data-pulse-track="signup-form">...</form>

What gets tracked

For each tracked element, Pulse measures:

Visibility rate — % of sessions where the element was visible in the viewport
Click rate — % of sessions with a click on the element
Rage clicks — when users click the same element 3+ times rapidly

Dashboard

View element performance in the Elements tab of your dashboard. Elements are classified as:

🟢 Healthy — good visibility and click rates
🟡 Watch — underperforming on one metric
🔴 Underperforming — needs attention

Limits

Starter plan: 20 tracked elements per site
Pro plan: 20 tracked elements per site
Scale plan: 20 tracked elements per site

Funnel Tracking

Define multi-step conversion funnels to see where users drop off.

Setup

Funnels are configured in the Pulse dashboard under Sites > Edit Site > Funnels.

Each funnel step is either:

Page — a URL path (e.g., /pricing)
Event — a conversion event name (e.g., checkout_started)

Example Funnel

Step	Type	Value	Label
1	Page	/	Homepage
2	Page	/pricing	Pricing page
3	Event	checkout_started	Start checkout
4	Event	purchase_completed	Complete purchase

Analysis

Pulse's AI will analyse your funnel weekly and provide:

Drop-off rates per step
Behavioural context — what users did before dropping off
Fix suggestions — specific recommendations to improve conversion

Limits

Starter plan: 1 funnel per site
Pro plan: 5 funnels per site
Scale plan: 5 funnels per site

API Reference

Pulse exposes a REST API for managing sites, reports, and triggering analyses.

Authentication

All API calls require a valid session cookie (pulse_session). The cookie is set automatically when you log in.

Endpoints

#### Sites

Method	Path	Description
GET	`/api/sites`	List all sites
POST	`/api/sites`	Create a new site
GET	`/api/sites/:siteId`	Get site details
PATCH	`/api/sites/:siteId`	Update site settings
DELETE	`/api/sites/:siteId`	Delete a site

#### Reports

Method	Path	Description
GET	`/api/reports`	List reports for active site
POST	`/api/reports`	Trigger on-demand analysis
GET	`/api/reports/:reportId`	Get full report

#### Auth

Method	Path	Description
POST	`/api/auth/signup`	Create account
POST	`/api/auth/login`	Sign in
POST	`/api/auth/logout`	Sign out
GET	`/api/auth/me`	Current session
POST	`/api/auth/reset-password`	Request/execute password reset

#### Actions

Method	Path	Description
GET	`/api/actions`	List actions for active site
POST	`/api/actions`	Create an action
GET	`/api/actions/:actionId`	Get action details
PATCH	`/api/actions/:actionId`	Update action status

#### Analytics

Method	Path	Description
GET	`/api/analytics/attribution`	Channel attribution data
GET	`/api/billing/usage`	Current billing usage stats

#### Billing

Method	Path	Description
POST	`/api/stripe/checkout`	Create checkout session
POST	`/api/stripe/portal`	Open billing portal
POST	`/api/stripe/change-plan`	Change subscription plan

Agent JSON Export (Pro+)

Weekly AI reports include an agentManifest field with structured JSON suitable for developer tools:

{
  "schemaVersion": "1.0",
  "reportId": "...",
  "tenantId": "...",
  "site": "example.com",
  "generatedAt": "2026-02-20T02:00:00Z",
  "actions": [
    {
      "actionId": "...",
      "priority": "critical",
      "category": "ux",
      "targetUrl": "/pricing",
      "targetElement": ".cta-primary",
      "actionType": "increase_contrast",
      "currentState": "Low visibility button",
      "desiredState": "High contrast CTA above fold"
    }
  ]
}

Privacy & Compliance

Pulse is designed to be privacy-first from the ground up.

What we DON'T collect

❌ IP addresses — never extracted from requests
❌ Cookies — we don't set any
❌ User agent strings — parsed to OS family + browser family only
❌ Form field values — only field names are tracked
❌ DOM content — never captured
❌ Full referrer URLs — categorised as direct/search/social/email/other
❌ Personal identifiers of any kind

Session handling

Sessions are created using a client-side UUID stored in sessionStorage. This means:

Sessions die when the tab is closed
No cross-session tracking
No cross-device tracking
No fingerprinting

Data storage

All data is stored securely in AWS (ap-southeast-1, Singapore)
Encrypted at rest (SSE-S3)
13-month retention, then automatically deleted
S3 lifecycle: Standard → IA at 90 days → Glacier at 365 days → Deleted at 395 days

GDPR compliance

Since Pulse doesn't collect personal data, it doesn't require:

Cookie consent banners
DPA agreements with customers
Data Subject Access Requests (no personal data to access)
Right to Erasure requests (no personal data to erase)

Data Processing Agreement

For enterprise customers who want a formal DPA anyway, contact us at hello@hatched.digital.