Skip to content

Commit 343937a

Browse files
jumskijumski
committed
feat: add Plausible event tracking to documentation and components (#356)
- Introduced CSS class-based and manual JavaScript event tracking for Plausible - Updated CodeOverlay.astro to track reveal code button clicks - Added tracking to JoinCommunity.astro link - Enhanced index.md with data attributes for CTA buttons - Updated links in index.md to include plausible-event-name classes - Improved consistency and coverage of event tracking across site components and content
1 parent 354e149 commit 343937a

File tree

5 files changed

+340
-10
lines changed

5 files changed

+340
-10
lines changed

‎.claude/settings.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959
"Skill(note-review)",
6060
"Skill(notes-sync)",
6161
"Skill(pgtap-testing)",
62+
"Skill(restack)",
6263
"Skill(schema-dev)",
6364
"Skill(unblock)",
6465
"AskUserQuestion",

‎pkgs/website/ANALYTICS.md‎

Lines changed: 329 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,329 @@
1+
# Website Analytics - Plausible Setup
2+
3+
This document describes the Plausible Analytics implementation for the pgflow website.
4+
5+
## Overview
6+
7+
The website uses [Plausible Analytics](https://plausible.io/) for privacy-friendly, lightweight analytics. Events are tracked using CSS class-based tracking (preferred) and manual JavaScript tracking (for complex interactions).
8+
9+
## Configuration
10+
11+
### Script Setup
12+
13+
The Plausible script is configured in `astro.config.mjs` (lines 91-102):
14+
15+
```javascript
16+
{
17+
tag: 'script',
18+
attrs: {
19+
defer: true,
20+
'data-domain': DOMAIN_NAME,
21+
'data-api': PLAUSIBLE_PROXY.url + PLAUSIBLE_PROXY.eventPath,
22+
src: PLAUSIBLE_PROXY.url + PLAUSIBLE_PROXY.scriptPath,
23+
},
24+
}
25+
```
26+
27+
**Script extensions enabled:**
28+
- `.tagged-events` - CSS class-based event tracking
29+
- `.outbound-links` - Automatic external link tracking
30+
- `.pageview-props` - Custom pageview properties
31+
32+
### Proxy Configuration
33+
34+
Analytics are proxied through Cloudflare Workers to avoid ad blockers:
35+
- Proxy URL: Set via `PLAUSIBLE_PROXY_URL` environment variable
36+
- Required for production deployments
37+
- See `DEPLOYMENT.md` for setup instructions
38+
39+
## Event Tracking Methods
40+
41+
### Method 1: CSS Class-Based Tracking (Preferred)
42+
43+
Add the `plausible-event-name=EventName` CSS class to any clickable element:
44+
45+
```html
46+
<button class="plausible-event-name=home:cta-click">
47+
Click Me
48+
</button>
49+
```
50+
51+
**Naming convention:**
52+
- Format: `page:action` or `section:action`
53+
- Use hyphens for multi-word actions
54+
- Examples: `home:cta-get-started`, `discord:join-click`
55+
56+
**Parent element tracking:**
57+
Plausible can track clicks on child elements if the parent has the tracking class:
58+
59+
```html
60+
<div class="plausible-event-name=home:card-click">
61+
<a href="/link">This link will be tracked</a>
62+
</div>
63+
```
64+
65+
### Method 2: Manual JavaScript Tracking
66+
67+
For complex interactions that can't use CSS classes (like scroll events):
68+
69+
```javascript
70+
// Check if plausible is available
71+
if (typeof window.plausible !== 'undefined') {
72+
window.plausible('event:name');
73+
}
74+
```
75+
76+
**When to use manual tracking:**
77+
- Scroll events
78+
- Form submissions with validation
79+
- Multi-step interactions
80+
- Events triggered by timers or animations
81+
82+
## Tracked Events
83+
84+
All custom events must be configured as goals in the Plausible dashboard before they appear.
85+
86+
### Homepage Events
87+
88+
| Event Name | Type | Description | Location |
89+
|------------|------|-------------|----------|
90+
| `home:cta-get-started` | CSS | Hero "Get Started" button click | index.mdx hero |
91+
| `home:cta-how-it-works` | CSS | Hero "How It Works" button click | index.mdx hero |
92+
| `home:reveal-code` | CSS | Reveals boilerplate code overlay | CodeOverlay.astro |
93+
| `home:code-scroll` | Manual | User manually scrolls code (once per session) | CodeOverlay.astro |
94+
| `home:cta-install-bottom` | CSS | Bottom CTA card click | index.mdx |
95+
| `home:supabase-guide-click` | CSS | Supabase blog guide link | index.mdx |
96+
97+
### Community Events
98+
99+
| Event Name | Type | Description | Location |
100+
|------------|------|-------------|----------|
101+
| `discord:join-click` | CSS | Discord join link clicks | JoinCommunity.astro |
102+
103+
### Test Events (Development Only)
104+
105+
| Event Name | Type | Description | Location |
106+
|------------|------|-------------|----------|
107+
| `test:css-button-click` | CSS | Test CSS tracking | plausible-test.mdx |
108+
| `test:manual-button-click` | Manual | Test manual tracking | plausible-test.mdx |
109+
110+
## Plausible Dashboard Configuration
111+
112+
### Required Custom Event Goals
113+
114+
To see tracked events in your Plausible dashboard:
115+
116+
1. Go to **Settings** → **Goals**
117+
2. Click **+ Add goal**
118+
3. Select **Custom event**
119+
4. Add each event name listed above
120+
121+
**Production goals:**
122+
```
123+
home:cta-get-started
124+
home:cta-how-it-works
125+
home:reveal-code
126+
home:code-scroll
127+
home:cta-install-bottom
128+
home:supabase-guide-click
129+
discord:join-click
130+
```
131+
132+
**Development/testing goals:**
133+
```
134+
test:css-button-click
135+
test:manual-button-click
136+
```
137+
138+
### Viewing Events
139+
140+
After configuring goals:
141+
- Events appear at the bottom of the dashboard
142+
- First conversion must occur before goal shows up
143+
- Real-time data typically appears within 1-2 minutes
144+
- Historical data aggregates over time
145+
146+
## Automatic Tracking
147+
148+
The following are tracked automatically (no configuration needed):
149+
150+
### Outbound Links
151+
All external links are automatically tracked with the event name:
152+
- Event: `Outbound Link: Click`
153+
- Property: `url` (destination URL)
154+
155+
This includes:
156+
- Social links (GitHub, Discord, Twitter)
157+
- External documentation links
158+
- Supabase blog references
159+
160+
### Pageviews
161+
All pageviews are automatically tracked with:
162+
- URL
163+
- Referrer
164+
- Browser/OS information
165+
- Geographic location (privacy-friendly)
166+
167+
## Adding New Events
168+
169+
### For CSS-Trackable Elements
170+
171+
1. Add the CSS class to the element:
172+
```html
173+
<button class="plausible-event-name=section:action-name">
174+
Button Text
175+
</button>
176+
```
177+
178+
2. Add the event to this documentation file
179+
180+
3. Configure the custom event goal in Plausible dashboard
181+
182+
4. Test on a preview deployment before production
183+
184+
### For Complex Interactions
185+
186+
1. Add TypeScript declaration (if not exists):
187+
```typescript
188+
declare global {
189+
interface Window {
190+
plausible?: (event: string, options?: { props?: Record<string, string | number> }) => void;
191+
}
192+
}
193+
```
194+
195+
2. Add tracking code with safety check:
196+
```typescript
197+
if (typeof window.plausible !== 'undefined') {
198+
window.plausible('section:action-name');
199+
}
200+
```
201+
202+
3. Follow steps 2-4 from CSS tracking above
203+
204+
## Testing
205+
206+
### Local Development
207+
208+
1. Start dev server: `pnpm nx dev website`
209+
2. Visit `/plausible-test/` page
210+
3. Open browser console (F12)
211+
4. Click test buttons
212+
5. Check console for:
213+
- `window.plausible` is defined
214+
- No JavaScript errors
215+
- Event tracking calls logged
216+
217+
### Browser Console Checks
218+
219+
```javascript
220+
// Check if Plausible is loaded
221+
typeof window.plausible
222+
// Expected: "function"
223+
224+
// Check script element
225+
document.querySelector('script[data-domain]')
226+
// Expected: <script> element
227+
228+
// Check domain configuration
229+
document.querySelector('script[data-domain]')?.getAttribute('data-domain')
230+
// Expected: "www.pgflow.dev"
231+
232+
// Manually trigger test event
233+
window.plausible('test:manual-trigger')
234+
// Expected: No errors, event sent
235+
```
236+
237+
### Preview Deployments
238+
239+
1. Push to PR branch
240+
2. Wait for preview deployment
241+
3. Visit preview URL: `https://pr-{number}.pgflow.pages.dev`
242+
4. Test event tracking
243+
5. Check Plausible dashboard for events (may take 1-2 minutes)
244+
245+
## Troubleshooting
246+
247+
### Events Not Appearing in Dashboard
248+
249+
**Issue:** Clicked buttons but no events show up
250+
251+
**Solutions:**
252+
1. **Configure custom event goals** - This is the most common issue
253+
- Go to Settings → Goals in Plausible
254+
- Add custom event with exact event name
255+
- Wait 1-2 minutes and refresh dashboard
256+
257+
2. **Check script loading**
258+
- Open browser console
259+
- Verify `typeof window.plausible === "function"`
260+
- Check for JavaScript errors
261+
262+
3. **Verify proxy URL**
263+
- Check `PLAUSIBLE_PROXY_URL` is set correctly
264+
- Test proxy: `curl -I https://your-proxy-url/assets/script...js`
265+
- Should return 200 OK
266+
267+
4. **Ad blocker interference**
268+
- Try disabling ad blockers
269+
- Verify proxy is working (bypasses most blockers)
270+
- Check browser extensions
271+
272+
### CSS Class Not Working
273+
274+
**Issue:** Added `plausible-event-name=...` class but clicks not tracked
275+
276+
**Solutions:**
277+
1. **Verify class syntax**
278+
- Must be exactly: `plausible-event-name=EventName`
279+
- Use `+` for spaces: `plausible-event-name=Button+Click`
280+
- Some CMSs replace `=` with `-`, use `--` instead
281+
282+
2. **Check element is clickable**
283+
- Must be `<a>`, `<button>`, or element with click handler
284+
- Parent element with class can track child clicks
285+
286+
3. **Inspect HTML in browser**
287+
- Right-click → Inspect element
288+
- Verify class was actually added to HTML
289+
- Check for class name transformations
290+
291+
### Script Not Loading
292+
293+
**Issue:** `window.plausible` is undefined
294+
295+
**Solutions:**
296+
1. **Check proxy URL**
297+
- Verify `PLAUSIBLE_PROXY_URL` environment variable
298+
- Test URL in browser: should return JavaScript file
299+
300+
2. **Check network tab**
301+
- Open DevTools → Network tab
302+
- Look for script load
303+
- Check for 404 or CORS errors
304+
305+
3. **Verify domain configuration**
306+
- Check `data-domain` matches Plausible site configuration
307+
- Currently: `www.pgflow.dev`
308+
309+
## Privacy & Performance
310+
311+
### Privacy
312+
- No cookies used
313+
- No personal data collected
314+
- No cross-site tracking
315+
- GDPR, CCPA, PECR compliant
316+
- IP addresses anonymized
317+
318+
### Performance
319+
- Script size: ~1KB (gzipped)
320+
- Loads asynchronously (defer)
321+
- No impact on page load time
322+
- Events batched for efficiency
323+
324+
## References
325+
326+
- [Plausible Custom Events Documentation](https://plausible.io/docs/custom-event-goals)
327+
- [Plausible Script Extensions](https://plausible.io/docs/script-extensions)
328+
- Proxy setup: See `DEPLOYMENT.md`
329+
- Environment variables: See `DEPLOYMENT.md`

‎pkgs/website/src/components/CodeOverlay.astro‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
❌ Error handling & retries<br/>
1313
🔗 Manual step coordination
1414
</div>
15-
<button class="reveal-button sl-button-primary" aria-label="Reveal 250+ lines of traditional code">
15+
<button class="reveal-button sl-button-primary plausible-event-name=home:reveal-code" aria-label="Reveal 250+ lines of traditional code">
1616
Show me the boilerplate code ↓
1717
</button>
1818
</div>
@@ -317,11 +317,7 @@
317317
if (!button || !overlay || !scrollableContainer || !scrollableInner) return;
318318

319319
button.addEventListener('click', () => {
320-
// Track custom event in Plausible
321-
if (typeof window.plausible !== 'undefined') {
322-
window.plausible('home:reveal-code');
323-
}
324-
320+
// Event tracking handled by CSS class: plausible-event-name=home:reveal-code
325321
scrollableContainer.classList.add('scrollable-enabled');
326322
overlay.style.opacity = '0';
327323

‎pkgs/website/src/components/JoinCommunity.astro‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,5 @@ import { Card } from '@astrojs/starlight/components';
77
<Card title="Connect on Discord" icon="discord">
88
Have questions or need help? pgflow is just getting started - join us on Discord to ask questions, share feedback, or discuss partnership opportunities.
99

10-
<h5><strong><a href="https://pgflow.dev/discord/">Join Discord →</a></strong></h5>
10+
<h5><strong><a href="https://pgflow.dev/discord/" class="plausible-event-name=discord:join-click">Join Discord →</a></strong></h5>
1111
</Card>

0 commit comments

Comments
 (0)