email marketing

seo-tracker/README.md

@@ -0,0 +1,94 @@
+# SEO Rank Tracker (standalone)
+
+Eigenständiger Rank-Tracker für `qrmaster.net` über die [Serper.dev](https://serper.dev)
+Google-SERP-API. Läuft komplett außerhalb der Next.js-App, greift auf keine
+Datenbank zu und hat keine npm-Dependencies — nur **Node 18+**.
+
+Ersetzt kostenpflichtige Rank-Tracker (Wincher, SerpRobot, ~10–25 €/Monat) für
+ein paar Cent pro Lauf.
+
+## Setup
+
+```bash
+cd seo-tracker
+cp .env.example .env
+# SERPER_API_KEY in .env eintragen
+```
+
+## Nutzung
+
+```bash
+node track.mjs --dry-run          # zeigt Keywords + Credit-Schätzung, ohne API-Calls
+node track.mjs --limit 5 --num 20 # kleiner Testlauf (~10 Credits)
+node track.mjs                    # voller Lauf
+node track.mjs --num 20           # nur Top 20 prüfen — spart 80% Credits
+
+# eigene Liste / eigene Ausgabedatei (z. B. für Ad-hoc-Checks)
+node track.mjs --keywords test.txt --out test.csv --num 20
+```
+
+Ergebnisse werden an `results.csv` angehängt (eine Zeile pro Keyword pro Lauf).
+Beim zweiten Lauf zeigt die Konsole automatisch die Δ-Veränderung gegenüber dem
+vorherigen Durchlauf.
+
+## Keywords pflegen
+
+`keywords.txt`, eine Zeile pro Keyword. `#` = Kommentar.
+Land optional per Pipe anhängen:
+
+```
+qr code generator
+qr code generator kostenlos | de
+```
+
+## Credits im Blick behalten
+
+Serper rechnet **1 Credit pro 10 Ergebnisse** ab:
+
+| Tiefe (`--num`) | Credits/Keyword | 43 Keywords | Läufe mit 2.500 Credits |
+|---|---|---|---|
+| 100 | 10 | 430 | ~5 |
+| 20 | 2 | 86 | ~29 |
+| 10 | 1 | 43 | ~58 |
+
+**Empfehlung:** `RESULTS_PER_QUERY=20` in der `.env` und wöchentlich laufen lassen.
+Damit reicht das kostenlose Guthaben gut ein halbes Jahr, und Positionen jenseits
+von Platz 20 sind ohnehin kaum handlungsrelevant.
+
+Für die tiefe Sicht (Top 100) einmal im Quartal `node track.mjs --num 100` laufen lassen.
+
+## Automatisierung
+
+Wöchentlich, montags 6 Uhr:
+
+**Windows (Aufgabenplanung)**
+```
+schtasks /create /tn "QR Master Rank Tracker" /tr "node C:\Users\timo\Documents\qrmaster\QR-master\seo-tracker\track.mjs" /sc weekly /d MON /st 06:00
+```
+
+**Linux/Server (crontab)**
+```
+0 6 * * 1 cd /pfad/zu/seo-tracker && node track.mjs >> tracker.log 2>&1
+```
+
+## Ausgabe-Spalten
+
+| Spalte | Bedeutung |
+|---|---|
+| `date` | Datum des Laufs |
+| `keyword` / `country` | Abgefragte Query und Land |
+| `position` | Position von qrmaster.net (leer = nicht in Top N) |
+| `url` | Welche URL rankt |
+| `top_competitor` | Domain auf Platz 1 (ausser eigener) |
+| `ai_overview` | 1 = Google zeigte AI Overview / Answer Box |
+| `error` | Fehlermeldung, falls der Call fehlschlug |
+
+Die Spalte `ai_overview` ist der Einstieg ins AEO-Tracking: Keywords, bei denen
+Google eine AI-Antwort ausspielt, verlieren organische Klicks — die gehören
+priorisiert in die AEO-Backlog-Liste in `CLAUDE.md`.
+
+## Blinder Fleck
+
+Der Tracker sieht nur, was Serper sieht — Google-Rankings. Für **echte**
+Impressions/Klicks empfiehlt sich zusätzlich die Google-Search-Console-API
+(kostenlos, offizielle Daten).