--- name: umami description: Self-hosted Umami Analytics integration with username/password authentication. Use to create websites, get tracking codes, and fetch analytics data. --- # 📊 Umami Analytics Skill **Skill Name:** `umami` **Category:** `quick` **Load Skills:** `[]` --- ## 🚀 Purpose Integrate with self-hosted Umami Analytics using username/password authentication (like Easypanel): - ✅ **Auto-login** - Get bearer token from credentials - ✅ **Create websites** - Auto-create Umami website for new projects - ✅ **Get tracking code** - Retrieve script URL for website integration - ✅ **Fetch analytics** - Get pageviews, visitors, bounce rate - ✅ **List websites** - Get all websites in Umami instance **Use Cases:** 1. Auto-create Umami website when generating new website 2. Add tracking code to Astro website automatically 3. Fetch analytics data for SEO analysis 4. Manage multiple Umami websites --- ## 📋 Pre-Flight Questions **MUST ask before using:** 1. **Umami Instance URL:** - What's your Umami URL? (e.g., https://analytics.moreminimore.com) 2. **Authentication:** - Username/email - Password 3. **For Website Creation:** - Website name - Website domain 4. **For Existing Website:** - Website name or domain (to find in Umami) --- ## 🔄 Workflows ### **Workflow 1: Auto-Login (First Step for All Operations)** ```python Input: Umami URL, username, password Process: 1. POST /api/auth/login 2. Get bearer token 3. Save token for subsequent requests Output: Bearer token + user info ``` ### **Workflow 2: Create Umami Website** ```python Input: Website name, domain Process: 1. Login (get token) 2. POST /api/websites 3. Get website ID Output: Website ID, name, domain, tracking URL ``` ### **Workflow 3: Get Tracking Code** ```python Input: Website ID or domain Process: 1. Get website ID 2. Generate tracking script URL Output: Script tag or URL ``` ### **Workflow 4: Add Tracking to Website** ```python Input: Website repo path, Umami website ID Process: 1. Get tracking code 2. Find Astro root layout 3. Add script to 4. Save file Output: Updated layout file ``` ### **Workflow 5: Fetch Analytics** ```python Input: Website ID, date range Process: 1. GET /api/websites/:id/stats 2. Parse response Output: Pageviews, visitors, bounce rate, etc. ``` --- ## 🔧 Technical Implementation ### **Authentication:** ```python POST {umami_url}/api/auth/login Content-Type: application/json { "username": "your-username", "password": "your-password" } Response: { "token": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": "uuid", "username": "admin", "isAdmin": true } } ``` ### **Create Website:** ```python POST {umami_url}/api/websites Authorization: Bearer {token} Content-Type: application/json { "name": "My Website", "domain": "example.com" } Response: { "id": "website-uuid", "name": "My Website", "domain": "example.com", "createdAt": "2026-03-08T..." } ``` ### **Get Tracking Code:** ```javascript // Script URL format // Or for Fathom-style (if enabled) ``` ### **Get Stats:** ```python GET {umami_url}/api/websites/{website_id}/stats ?startAt={timestamp} &endAt={timestamp} Authorization: Bearer {token} Response: { "pageviews": 1234, "uniques": 567, "bounces": 89, "totaltime": 12345 } ``` --- ## 📁 Commands ### **Create Umami Website:** ```bash python3 skills/umami/scripts/umami_client.py \ --action create-website \ --umami-url "https://analytics.moreminimore.com" \ --username "admin" \ --password "your-password" \ --website-name "My Website" \ --website-domain "example.com" ``` ### **Get Tracking Code:** ```bash python3 skills/umami/scripts/umami_client.py \ --action get-tracking \ --umami-url "https://analytics.moreminimore.com" \ --username "admin" \ --password "your-password" \ --website-id "website-uuid" ``` ### **Add Tracking to Website:** ```bash python3 skills/umami/scripts/umami_client.py \ --action add-tracking \ --umami-url "https://analytics.moreminimore.com" \ --username "admin" \ --password "your-password" \ --website-name "My Website" \ --website-repo "/path/to/astro-website" ``` ### **Fetch Analytics:** ```bash python3 skills/umami/scripts/umami_client.py \ --action get-stats \ --umami-url "https://analytics.moreminimore.com" \ --username "admin" \ --password "your-password" \ --website-id "website-uuid" \ --days 30 ``` --- ## ⚙️ Environment Variables **Updated for username/password auth:** ```bash # Umami Analytics (Self-Hosted) UMAMI_URL=https://analytics.yoursite.com UMAMI_USERNAME=admin UMAMI_PASSWORD=your-password ``` **Note:** Changed from API key to username/password like Easypanel --- ## 📊 Output Examples ### **Create Website Output:** ```json { "success": true, "website_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "My Website", "domain": "example.com", "tracking_url": "https://analytics.moreminimore.com/script.js", "tracking_script": "", "created_at": "2026-03-08T16:00:00.000Z" } ``` ### **Stats Output:** ```json { "success": true, "website_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "period": "last_30_days", "stats": { "pageviews": 12500, "uniques": 8900, "bounces": 1200, "totaltime": 245000, "avg_session_duration": 27.5, "bounce_rate": 13.5 } } ``` --- ## 🔄 Integration with Other Skills ### **website-creator Integration:** ```python # After creating Astro website umami_result = create_umami_website( umami_url, username, password, website_name, website_domain ) if umami_result['success']: # Add tracking to Astro layout add_tracking_to_astro( website_repo, umami_result['tracking_script'] ) ``` ### **seo-data Integration:** ```python # Replace umami_connector.py stub from umami import UmamiClient umami = UmamiClient(umami_url, username, password) stats = umami.get_page_data(website_id, days=30) ``` --- ## ✅ Success Criteria - [ ] Can login with username/password - [ ] Can create new Umami website - [ ] Can get tracking code - [ ] Can add tracking to Astro website - [ ] Can fetch analytics data - [ ] Token cached for subsequent requests --- ## ⚠️ Important Notes 1. **Self-Hosted Only:** This skill is for self-hosted Umami instances 2. **Username/Password:** Uses login API, not API keys (Umami Cloud uses API keys) 3. **Token Caching:** Bearer token should be cached to avoid repeated logins 4. **Website Domain:** Must be full domain (https://example.com) 5. **Script URL:** Depends on Umami instance URL --- ## 📖 API Reference - **Login:** POST /api/auth/login - **Create Website:** POST /api/websites - **Get Website:** GET /api/websites/:id - **Get Stats:** GET /api/websites/:id/stats - **List Websites:** GET /api/websites Full docs: https://umami.is/docs/api --- **Use this skill when you need to integrate with self-hosted Umami Analytics using username/password authentication.**