# 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 `` section ### Web App (SvelteKit) - **Location**: `apps/web/src/routes/+layout.svelte` - **Framework**: SvelteKit - **Integration**: Script tag in `` 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 ``` ### Disable Automatic Tracking To disable automatic page view tracking: ```html ``` 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