351 lines
7.2 KiB
Markdown
351 lines
7.2 KiB
Markdown
---
|
|
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 <head>
|
|
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
|
|
<script defer src="{umami_url}/script.js" data-website-id="{website_id}"></script>
|
|
|
|
// Or for Fathom-style (if enabled)
|
|
<script defer src="{umami_url}/script.js" data-site-id="{website_id}"></script>
|
|
```
|
|
|
|
### **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": "<script defer src=\"https://analytics.moreminimore.com/script.js\" data-website-id=\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"></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.**
|