mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-15 03:21:08 +02:00
d36b321d9d
Applied formatting to 1487+ files using pnpm format:write - TypeScript/JavaScript files - Svelte components - Astro pages - JSON configs - Markdown docs 13 files still need manual review (Astro JSX comments)
242 lines
5.5 KiB
Markdown
242 lines
5.5 KiB
Markdown
# Umami Analytics Setup
|
|
|
|
This document describes how to set up Umami Analytics for the Picture platform.
|
|
|
|
## Overview
|
|
|
|
Umami Analytics has been integrated into both the landing page and web app to provide privacy-friendly analytics tracking.
|
|
|
|
## Architecture
|
|
|
|
### Landing Page (Astro)
|
|
|
|
- **Location**: `apps/landing/src/layouts/Layout.astro`
|
|
- **Framework**: Astro
|
|
- **Integration**: Script tag in `<head>` section
|
|
|
|
### Web App (SvelteKit)
|
|
|
|
- **Location**: `apps/web/src/routes/+layout.svelte`
|
|
- **Framework**: SvelteKit
|
|
- **Integration**: Script tag in `<svelte:head>` section
|
|
|
|
## Configuration
|
|
|
|
Both apps use environment variables for Umami configuration:
|
|
|
|
```bash
|
|
PUBLIC_UMAMI_URL=https://your-umami-instance.com
|
|
PUBLIC_UMAMI_WEBSITE_ID=your-website-id
|
|
```
|
|
|
|
### Setting up Environment Variables
|
|
|
|
#### For Landing Page
|
|
|
|
Create or update `apps/landing/.env`:
|
|
|
|
```bash
|
|
PUBLIC_UMAMI_URL=https://analytics.yourdomain.com
|
|
PUBLIC_UMAMI_WEBSITE_ID=your-landing-website-id
|
|
```
|
|
|
|
#### For Web App
|
|
|
|
Create or update `apps/web/.env`:
|
|
|
|
```bash
|
|
PUBLIC_UMAMI_URL=https://analytics.yourdomain.com
|
|
PUBLIC_UMAMI_WEBSITE_ID=your-webapp-website-id
|
|
```
|
|
|
|
> **Note**: You can use the same Umami instance for both apps, but you should create separate website IDs in Umami to track them independently.
|
|
|
|
## Features
|
|
|
|
### Privacy-First Tracking
|
|
|
|
- ✅ **Do Not Track**: Respects browser DNT settings via `data-do-not-track="true"`
|
|
- ✅ **No Cookies**: Umami doesn't use cookies by default
|
|
- ✅ **GDPR Compliant**: No personal data collection
|
|
- ✅ **Conditional Loading**: Only loads when environment variables are set
|
|
|
|
### Automatic Tracking
|
|
|
|
The integration automatically tracks:
|
|
|
|
- Page views
|
|
- Referrers
|
|
- Browser/device information (anonymized)
|
|
- Geographic location (country level only)
|
|
|
|
## Setup Steps
|
|
|
|
### 1. Set Up Umami Instance
|
|
|
|
You have two options:
|
|
|
|
#### Option A: Use Umami Cloud
|
|
|
|
1. Sign up at [umami.is](https://umami.is)
|
|
2. Create a new website for your landing page
|
|
3. Create another website for your web app
|
|
4. Copy the website IDs
|
|
|
|
#### Option B: Self-Host Umami
|
|
|
|
1. Follow the [Umami self-hosting guide](https://umami.is/docs/install)
|
|
2. Deploy Umami to your preferred platform
|
|
3. Create websites for both apps
|
|
4. Note your instance URL
|
|
|
|
### 2. Configure Environment Variables
|
|
|
|
#### Development
|
|
|
|
1. Copy `.env.example` to `.env` in both `apps/landing` and `apps/web`
|
|
2. Add your Umami credentials:
|
|
```bash
|
|
PUBLIC_UMAMI_URL=https://your-umami-instance.com
|
|
PUBLIC_UMAMI_WEBSITE_ID=your-website-id
|
|
```
|
|
|
|
#### Production
|
|
|
|
Add the environment variables to your deployment platform:
|
|
|
|
**Vercel/Netlify:**
|
|
|
|
- Go to Project Settings → Environment Variables
|
|
- Add `PUBLIC_UMAMI_URL` and `PUBLIC_UMAMI_WEBSITE_ID`
|
|
|
|
**Other platforms:**
|
|
|
|
- Follow your platform's documentation for setting environment variables
|
|
- Ensure variables are prefixed with `PUBLIC_` to be exposed to the client
|
|
|
|
### 3. Verify Integration
|
|
|
|
1. Start your development servers:
|
|
|
|
```bash
|
|
# Landing page
|
|
cd apps/landing
|
|
pnpm dev
|
|
|
|
# Web app
|
|
cd apps/web
|
|
pnpm dev
|
|
```
|
|
|
|
2. Open browser DevTools → Network tab
|
|
3. Look for requests to your Umami instance
|
|
4. Check your Umami dashboard for live visitors
|
|
|
|
## Testing
|
|
|
|
To verify Umami is working:
|
|
|
|
1. **Check Script Loading**:
|
|
- Open DevTools → Network
|
|
- Filter by "script.js"
|
|
- Verify the Umami script loads successfully
|
|
|
|
2. **Check Tracking**:
|
|
- Navigate to different pages
|
|
- Open DevTools → Network
|
|
- Look for POST requests to `/api/send`
|
|
|
|
3. **Check Dashboard**:
|
|
- Log in to your Umami instance
|
|
- Navigate to Realtime → Current visitors
|
|
- Verify your session appears
|
|
|
|
## Troubleshooting
|
|
|
|
### Script Not Loading
|
|
|
|
- ✅ Verify environment variables are set correctly
|
|
- ✅ Ensure `PUBLIC_` prefix is used
|
|
- ✅ Check that Umami instance is accessible
|
|
- ✅ Restart dev server after adding env vars
|
|
|
|
### No Data in Dashboard
|
|
|
|
- ✅ Verify website ID matches the one in Umami
|
|
- ✅ Check browser console for errors
|
|
- ✅ Ensure ad blocker is disabled
|
|
- ✅ Verify network requests are successful
|
|
|
|
### Development vs Production
|
|
|
|
- In development: Tracking works but may be blocked by ad blockers
|
|
- In production: Use a custom domain for Umami to avoid ad blockers (e.g., `analytics.yourdomain.com`)
|
|
|
|
## Advanced Configuration
|
|
|
|
### Custom Events
|
|
|
|
To track custom events, use the Umami JavaScript API:
|
|
|
|
```typescript
|
|
// Track a custom event
|
|
if (window.umami) {
|
|
window.umami.track('button_click', {
|
|
button_name: 'sign_up',
|
|
});
|
|
}
|
|
```
|
|
|
|
### Domain Filtering
|
|
|
|
To only track specific domains, add `data-domains` attribute:
|
|
|
|
```html
|
|
<script
|
|
defer
|
|
src="..."
|
|
data-website-id="..."
|
|
data-domains="yourdomain.com,www.yourdomain.com"
|
|
></script>
|
|
```
|
|
|
|
### Disable Automatic Tracking
|
|
|
|
To disable automatic page view tracking:
|
|
|
|
```html
|
|
<script defer src="..." data-website-id="..." data-auto-track="false"></script>
|
|
```
|
|
|
|
Then manually track page views:
|
|
|
|
```typescript
|
|
if (window.umami) {
|
|
window.umami.track((props) => ({
|
|
...props,
|
|
url: '/custom-page',
|
|
}));
|
|
}
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
- ✅ All tracking is done client-side
|
|
- ✅ No sensitive data is collected
|
|
- ✅ Website ID is public (not a security concern)
|
|
- ✅ Only analytics data is sent to Umami instance
|
|
- ✅ No third-party cookies or trackers
|
|
|
|
## Resources
|
|
|
|
- [Umami Documentation](https://umami.is/docs)
|
|
- [Umami Cloud](https://cloud.umami.is)
|
|
- [Umami GitHub](https://github.com/umami-software/umami)
|
|
- [Privacy Policy Template](https://umami.is/docs/privacy)
|
|
|
|
## Support
|
|
|
|
For issues specific to:
|
|
|
|
- **Umami**: [Umami Discord](https://discord.gg/4dz4zcXYrQ)
|
|
- **Integration**: Create an issue in this repository
|