juanesal-lab/mapa-calor

Was macht mapa-calor?

Zwei sich ergänzende Diagnosen:

Teil	Beantwortete Frage	Quelle	Skript
Videos	Bei welcher Sekunde springen die Leute von meiner Anzeige ab?	Meta Graph API (nur GET)	scripts/retencion_videos.py
Landings	Scrollen, lesen und klicken die Leute, oder gehen sie gleich wieder weg?	Microsoft Clarity Data Export API	scripts/landing_clarity.py
Verbindung	Ist alles verbunden?	beide	scripts/conexion.py

Die Skripte liegen im Ordner scripts/ innerhalb des Skill-Ordners (Claude Code zeigt diesen als "Base directory for this skill" an; normalerweise ~/.claude/skills/mapa-calor). In den folgenden Befehlen steht $SK für diesen Ordner. Verwende python3 (oder python unter Windows).

Was tun, je nach Anfrage

• /mapa-calor ohne weitere Angabe, oder beim ersten Mal → führe conexion aus und frage dann, ob der Benutzer Videos, Landings oder beides möchte.
• /mapa-calor conexion → python3 "$SK/scripts/conexion.py". Fehlt etwas, führe Schritt für Schritt durch die README-Abschnitte „Meta verbinden“ / „Clarity verbinden“. Weiß der Benutzer seine act_ nicht: python3 "$SK/scripts/conexion.py" --cuentas.
• /mapa-calor videos → python3 "$SK/scripts/retencion_videos.py" (letzte 7 Tage, aktive Anzeigen). Optionen: --periodo last_14d, --desde YYYY-MM-DD --hasta YYYY-MM-DD, --todos (auch pausierte), --png mapa.png, --video datei.mp4 (Standbilder der ersten 4 s, alle 0,5 s ein Frame).
• /mapa-calor landing → python3 "$SK/scripts/landing_clarity.py". Optionen: --url /products/x, --meta (kreuzt mit Link-CTR und Warenkörben aus Meta), --solo-cache, --cuota.
• /mapa-calor todo → zuerst Videos, dann Landing mit --meta, und abschließend eine gemeinsame Diagnose.
• Ohne Verbindung oder zum Üben → eines der beiden mit --entrada <datei.json> (es gibt Beispieldateien im Ordner ejemplos/ des Repos).

So interpretierst du (sag es in einfachen Worten, mit der Zahl daneben)

Videos

1. Schau auf die Spalte 3s der Heatmap: das ist der Prozentsatz, der nach 3 Sekunden noch zusieht.
   • < 25 % → der Haken funktioniert nicht. Konkrete Empfehlung: die ersten 2,5 s neu machen.
   • 25–39 % → mittelmäßig. Teste eine Version mit dem Produkt im ersten Frame.
   • ≥ 40 % → der Haken funktioniert; suche den nächsten Abfall (das Skript markiert ihn: „nach dem Haken...“).
2. Das Produkt (oder das Problem, das es löst) sollte vor Sekunde 2,5 erscheinen. Videos, die es in Sekunde 0 zeigen, binden besser. Wenn der Benutzer die Videodatei hat, schlage --video vor und sieh dir die Standbilder an (lies sie mit dem Bildwerkzeug), um zu sagen, was genau an der Stelle zu sehen ist, an der die Leute abspringen.
3. Ein starker Abfall von Sekunde 0 auf 1 ist im Feed normal: vergleiche die Videos untereinander, nicht gegen 100 %.
4. Weniger als 100 Impressionen → keine Schlussfolgerung. Sag das klar und empfehle nicht, das Video zu pausieren oder hochzuskalieren.
5. Verbinde Bindung mit Verkäufen: guter Haken + 0 Käufe → der Bremser könnte die Landing sein (schlage /mapa-calor landing vor).

Landings

• pierde_arriba (mittleres Scrollen < 21 %) → die erste Bildschirmseite optimieren: klare Überschrift, Produktfoto in Verwendung, Nutzen und Preis ohne Scrollen sichtbar. Wenn zusätzlich der Link-CTR ≥ 1,5 % ist, bringt die Anzeige zwar Leute – der Bremser ist dann die Seite.
• friccion (Wutklicks > 5 %, tote Klicks > 20 % oder Quickback > 25 %) → öffne die VISUELLE Heatmap in Clarity (der Link steht im Bericht) und suche nach Elementen, die angeklickt werden, aber nicht reagieren.
• retiene / oferta_precio (Scrollen ≥ 30 %, aber < 4 Warenkörbe pro 100 Besuche) → das Problem ist Angebot oder Preis.
• creativo (Seite okay, CTR < 1,5 %) → ändere den Haken der Anzeige, nicht die Seite.
• muestra_chica (< 30 Besuche) → keine Schlussfolgerung.
• Das Bild der Heatmap (wo geklickt wird, wie weit gescrollt wird) sieht man nur im Clarity-Panel → Heatmaps. Die Skill liefert die Zahlen und den Link; erfinde nicht, was das Bild zeigt.

Beende immer mit maximal 3 konkreten Handlungen, geordnet nach Wirkung, und sag, was danach gemessen werden soll („in 3 Tagen führst du /mapa-calor videos erneut aus und schaust, ob die Spalte 3s gestiegen ist“).

Unveränderliche Regeln

• Gib niemals einen Token aus, kopiere ihn oder speichere ihn. Führe kein echo $META_TOKEN aus, lies keine .env-Datei laut vor und füge keine Tokens in Repository-Dateien ein. Wenn der Benutzer einen Token im Chat einfügt, sag ihm, er solle ihn im Schlüsselbund oder in ~/.mapa-calor/.env speichern und aus Sicherheitsgründen später erneuern.
• Nur lesender Zugriff. Diese Skill erstellt, pausiert oder bearbeitet nie Anzeigen. Wenn jemand etwas in Meta ändern möchte, erkläre, wie es im Anzeigenmanager geht; führe es nicht selbst aus.
• Beachte das Clarity-Kontingent (10 Aufrufe/Tag pro Projekt). Das Skript speichert bereits einen Cache (3 h) und hält bei 8 Aufrufen an. Verwende --forzar nur, wenn der Benutzer es verlangt und weiß, dass es einen Aufruf kostet. Für erneute Ansicht derselben Daten nutze --solo-cache. Um den aktuellen Verbrauch zu erfragen: --cuota.
• Ziehe keine Schlüsse aus kleinen Stichproben (< 100 Impressionen bei Videos, < 30 Besuche bei Landings).
• Wenn ein Skript fehlschlägt, lies die Fehlermeldung (sie ist bereits auf Spanisch mit der Lösung) und führe den Benutzer; die häufigsten Fehler stehen im README („Häufige Fehler“).