# Grandma Knows — Complete Documentation

> Conversational web analytics that answers your questions — rather than confusing you with jargon and endless filters.

## Overview

Grandma Knows is a web analytics platform built for individuals and small businesses. Instead of overwhelming users with dashboards full of numbers and filters, it centres on three pillars: **custom event tracking** via a visual point-and-click editor, a **straightforward dashboard** with drag-and-drop tiles adapted to your role, and a **conversational UI** that lets you ask questions about your data in plain English. The platform tracks page views, clicks, scroll depth, conversions, and custom events without requiring any code. Made in the UK 🇬🇧 by Pixel Takeaway Limited.

## Core Pillars

### Custom Event Tracking
Point and click on any element in the visual editor to track it as a custom event — clicks, page visits, or scroll depth. No coding required. Set up conversion goals and Grandma counts the wins.

### Straightforward Dashboard
Drag-and-drop metric tiles arranged to your liking. Role-based views adapt which tiles appear (designer, developer, marketer, manager). Toggle between beginner mode (plain-English labels) and professional mode (technical terminology). No gobbledygook — just the stats that matter.

### Conversational UI
Ask about your analytics in plain English instead of navigating complex dashboards and filters. "How many people clicked Subscribe?" — Grandma knows, and she'll tell you like it is.

## Pricing

- **Free** — £0/month: 1 website, 1,000 page views/month, 5 custom events, real-time analytics, conversion goals
- **Pro** — £5/month: 5 websites, 50,000 page views/month, unlimited custom events, everything in Free
- **Business** — £19/month: Unlimited websites, unlimited page views/month, priority support, everything in Pro

Cancel anytime. No questions asked. No minimum contract.

## Competitive Comparison

| Feature | Grandma Knows | Google Analytics | Mixpanel | Adobe Analytics | Plausible | Fathom | Hotjar |
|---|---|---|---|---|---|---|---|
| Ask questions in plain English | Yes | No | No | No | No | No | No |
| Visual conversion tracking (no code) | Yes | No | No | No | No | No | Partial |
| Visual scroll depth tracker | Yes | No | No | No | No | No | Partial |
| Free tier | Yes | Yes | Yes | No | No | No | Yes |
| Privacy-friendly | Yes | No | Partial | No | Yes | Yes | Partial |
| No minimum contract | Yes | N/A | Annual | Annual | Annual | Annual | Monthly |
| Setup time | < 2 min | 30+ min | 15 min | 30+ min | 5 min | 5 min | 10 min |
| Learning curve | Easy | Steep | Moderate | Steep | Easy | Easy | Easy |
| Lightweight script | < 5 KB | ~80 KB | ~40 KB | ~100 KB | ~1 KB | ~6 KB | ~15 KB |
| Custom event tracking (no code) | Yes | No | No | No | No | No | Partial |
| Made in UK 🇬🇧 | Yes | No | No | No | No | No | No |

## Architecture

### Client-Side Script (grandmaknows.js)

The analytics script is a self-contained IIFE (~4 KB) that:

1. Reads the `data-site-id` attribute from its own script tag to identify the website
2. Tracks page views, clicks, time on page, scroll depth, and goal completions
3. Reports events to the tracking endpoint
4. Supports SPA navigation via history API monitoring

#### Installation

```html
<script src="https://grandmaknows.com/grandmaknows.js" data-site-id="YOUR_SITE_ID" defer></script>
```

#### Event Types

- `page_view` — Fired on initial load and SPA navigations (includes device, screen, viewport, and language metadata)
- `click` — Batched click tracking (up to 5 per flush, debounced at 1s)
- `time_on_page` — Heartbeat every 30s + final beacon on page unload
- `scroll_depth` — Milestone-based tracking at 25%, 50%, 75%, and 100%
- `goal_completion` — Triggered by page visit, element click, or scroll depth goals
- `error_page` — Tracks 404 and error pages
- `outbound_click` — Tracks clicks on external links
- `form_submission` — Tracks form submit events

#### SPA Support

The script monitors `history.pushState`, `history.replaceState`, and `popstate` events. On navigation:
- Flushes pending click events
- Sends final time-on-page for the previous page
- Resets scroll depth milestones
- Tracks a new page view with full device metadata
- Re-checks page visit goals

#### Security

- Sensitive query parameters (tokens, passwords, API keys) are stripped from tracked URLs
- Password and hidden input clicks are excluded from tracking
- Class names and IDs are truncated to prevent oversized payloads
- URLs are capped at 2048 characters

### Backend

#### Edge Functions

**get-site-config** (GET, public)
- Input: `site_id` query parameter
- Returns: website ID and active conversion goals

**track-event** (POST, public)
- Input: `site_id`, `visitor_id`, `event_type`, `metadata`, `page_url`
- Validates event types, visitor IDs, and metadata size
- Inserts event rows into `visitor_events`

**ask-analytics** (POST, authenticated)
- Input: `question`, `website_id`, `date_from`, `date_to`, `expertise`
- Fetches website stats, goals, events, and metadata
- Adapts AI persona based on expertise mode (beginner: warm grandma tone; professional: concise technical analysis)
- Returns conversational analytics answer

**verify-installation** (POST, authenticated)
- Verifies script installation by fetching the target URL and checking for the `data-site-id` attribute
- SSRF protection: blocks internal IPs, enforces HTTP(S) only
- Requires JWT authentication and website ownership verification

#### Database Schema

- `websites` — Registered websites with site_id, URL, and ownership
- `conversion_goals` — Goal definitions (page_visit, element_click, or scroll_depth) per website
- `visitor_events` — Raw event log with visitor_id, event_type, metadata
- `profiles` — User preferences including profession_mode, expertise_mode, date_range_preference

All tables use Row Level Security. Visitor events are insert-only via service role (edge function gatekeeper).

## Dashboard

### Role-Based Views

The straightforward dashboard adapts which metric tiles are shown based on the user's selected profession:

- **Designer**: Devices, scroll depth, countries, visitors, time, traffic
- **Developer**: Traffic, browsers, errors, visitors, time, scroll, countries, devices
- **Marketer** (default): Visitors, bounce rate, visits per person, time, traffic, scroll, countries, devices
- **Manager**: Visitors, traffic, countries, time, bounce rate, scroll, devices
- **All** (many hats): All tiles including browsers and errors

### Expertise Modes

- **Beginner** (default): Simplified labels ("Visitors", "Time", "Screen") with plain-English descriptions. AI answers use warm, conversational tone.
- **Professional**: Technical labels ("Unique visitors", "Avg. session duration", "Screen breakdown") without descriptions. AI answers use concise, industry-standard terminology.

### Metrics Tracked

- Total page views and unique visitors
- Bounce rate (single-page sessions)
- Sessions per visitor
- Average session duration
- Scroll depth milestones (25%, 50%, 75%, 100%)
- Device breakdown (desktop, mobile, tablet)
- Browser distribution
- Country distribution
- Traffic sources and referrers
- UTM parameters (source, medium, campaign)
- Error pages (404s)
- Outbound clicks
- Form submissions
- Custom event / conversion goal completions

### Date Filters

Today, Yesterday, Last 7 days, Last 30 days, Last year, All time — with comparison to previous period.

## Conversion Goals

### Page Visit Goals
Triggered when a visitor navigates to a specific URL path. Uses normalized exact-match comparison.

### Element Click Goals
Triggered when a visitor clicks an element matching a CSS selector. Uses `Element.matches()` and `Element.closest()` for delegation support. Set up via visual point-and-click editor.

### Scroll Depth Goals
Triggered when a visitor scrolls past a specified percentage of the page. Set up via visual scroll picker on the live website.

Goals are deduplicated per visitor per session to prevent double-counting.

## Frequently Asked Questions

**Is my data secure?**
Yes. Grandma Knows does not collect any personally identifiable information from visitors. All data is stored securely. We comply with GDPR, are ICO registered, and Cyber Essentials certified.

**How does Grandma Knows work?**
Add a small code snippet to your webpage and tracking starts immediately — page views, clicks, time on page, scroll depth, and bounce rates. Use the visual editor to set up custom event tracking on specific elements — no coding needed. Ask questions about your data in plain English.

**What can I track with custom events?**
Clicks on buttons, links, forms, images — you name it. Use the visual point-and-click editor to select an element, give it a name, and tracking starts straight away. You can also track page visits and scroll depth.

**Do I need to know how to code?**
Not at all. The visual editor lets you set up custom event tracking with just a few clicks — no coding required.

**Will it slow down my webpage?**
No. The script is lightweight (under 5 KB) and loads asynchronously, so it won't affect page speed or Core Web Vitals scores.

**Can I cancel my plan at any time?**
Yes, absolutely. There are no contracts or commitments. Cancel from settings at any time, no questions asked.

## Getting Started

1. Sign up at [grandmaknows.com](https://grandmaknows.com)
2. Add your website URL
3. Copy the script tag and paste it into your site's HTML
4. Verify installation from the dashboard
5. Choose your role and expertise level
6. View your straightforward analytics dashboard
7. Ask questions about your data or use the visual editor to set up custom event tracking