juanesal-lab/mapa-calor

Que fait mapa-calor ?

Deux diagnostics complémentaires :

Partie	Question répondue	Source	Script
Vidéos	À quelle seconde les gens quittent mon annonce ?	Meta Graph API (GET uniquement)	scripts/retencion_videos.py
Landings	Les gens descendent-ils, lisent-ils et touchent-ils, ou repartent-ils vers le haut ?	API Microsoft Clarity Data Export	scripts/landing_clarity.py
Connexion	Tout est-il connecté ?	les deux	scripts/conexion.py

Les scripts se trouvent dans le dossier scripts/ à l'intérieur du dossier de cette skill (Claude Code l'affiche comme "Répertoire de base pour cette skill" ; normalement ~/.claude/skills/mapa-calor). Dans les commandes ci-dessous, $SK représente ce dossier. Utilisez python3 (ou python sur Windows).

Que faire selon la demande

• /mapa-calor sans rien, ou la première fois → exécute connexion puis demande s'il souhaite voir les vidéos, la landing ou tout.
• /mapa-calor conexion → python3 "$SK/scripts/conexion.py". Si quelque chose manque, guide pas à pas avec le README (section « Connexion Meta » / « Connexion Clarity »). S'il ne connaît pas son act_ : python3 "$SK/scripts/conexion.py" --cuentas.
• /mapa-calor videos → python3 "$SK/scripts/retencion_videos.py" (7 derniers jours, annonces actives). Options : --periodo last_14d, --desde AAAA-MM-DD --hasta AAAA-MM-DD, --todos (inclut les arrêtées), --png mapa.png, --video archivo.mp4 (feuille des 4 premières secondes, une image toutes les 0,5 s).
• /mapa-calor landing → python3 "$SK/scripts/landing_clarity.py". Options : --url /products/x, --meta (croise avec CTR de lien et paniers Meta), --solo-cache, --cuota.
• /mapa-calor todo → d'abord vidéos, puis landing avec --meta, et termine par un diagnostic conjoint.
• Sans connexion ou pour s'entraîner → l'un ou l'autre avec --entrada <archivo.json> (il y a des exemples fictifs dans ejemplos/ du dépôt).

Comment interpréter (dites-le en mots simples, avec le nombre à côté)

Vidéos

1. Regardez la colonne 3s de la carte : c'est le % qui continue à regarder à 3 secondes.
   • < 25 % → l'accroche échoue. Recommandation concrète : refaire les 2,5 premières secondes.
   • 25–39 % → moyen. Essayez une version avec le produit dans le premier plan.
   • ≥ 40 % → l'accroche fonctionne ; cherchez la prochaine fuite (le script le signale : « passé l'accroche… »).
2. Le produit (ou le problème qu'il résout) doit apparaître avant la seconde 2,5. Les vidéos qui le montrent à la seconde 0 retiennent mieux. Si l'utilisateur a le fichier vidéo, suggérez --video et regardez la feuille d'images (lisez-la avec l'outil d'images) pour dire ce qu'on voit exactement au moment où les gens décrochent.
3. Une forte baisse de la seconde 0 à 1 est normale dans le fil d'actualité : comparez les vidéos entre elles, pas par rapport à 100 %.
4. Moins de 100 impressions → ne pas conclure. Dites-le clairement et ne recommandez pas de désactiver ni d'augmenter le budget de cette vidéo.
5. Combinez rétention et ventes : bonne accroche + 0 achats → le frein peut être la landing (suggérez /mapa-calor landing).

Landings

• pierde_arriba (scroll moyen < 21 %) → corriger le premier écran : titre clair, photo du produit en usage, bénéfice et prix visibles sans descendre. Si en plus le CTR du lien est ≥ 1,5 %, l'annonce attire bien du monde : le frein est la page.
• friccion (rage > 5 %, clics morts > 20 % ou quickback > 25 %) → ouvrir la carte de chaleur VISUELLE dans Clarity (le lien apparaît dans le rapport) et chercher ce qu'ils touchent et qui ne répond pas.
• retiene / oferta_precio (scroll ≥ 30 % mais < 4 paniers pour 100 vues) → le problème est l'offre ou le prix.
• creativo (page correcte, CTR < 1,5 %) → changer l'accroche de l'annonce, pas la page.
• muestra_chica (< 30 visites) → ne pas conclure.
• L'image de la carte de chaleur (où ils touchent, jusqu'où ils descendent) ne se voit que dans le panneau Clarity → Heatmaps. La skill donne les chiffres et le lien ; n'inventez pas ce que montre l'image.

Terminez toujours par 3 actions concrètes au maximum, classées par impact, et dites quoi mesurer ensuite (« dans 3 jours, relance /mapa-calor videos et regarde si la colonne 3s a augmenté »).

Règles à ne pas enfreindre

• N'imprimez, ne copiez et ne sauvegardez jamais un jeton. Ne faites pas echo $META_TOKEN, ne lisez pas le .env à voix haute, ne collez pas de jetons dans des fichiers du dépôt. Si l'utilisateur colle un jeton dans le chat, dites-lui de le sauvegarder dans le Trousseau ou dans ~/.mapa-calor/.env et, par sécurité, de le régénérer plus tard.
• Lecture seule. Cette skill ne crée, ne met en pause et ne modifie jamais d'annonces. Si on vous demande de changer quelque chose dans Meta, expliquez quoi faire dans le Gestionnaire d'annonces ; ne le faites pas vous-même.
• Respectez le quota Clarity (10 appels/jour par projet). Le script met déjà en cache (3 h) et se limite à 8 appels. N'utilisez pas --forzar sauf si l'utilisateur le demande et sait qu'il consomme 1 appel. Pour revoir les mêmes données, utilisez --solo-cache. Pour connaître le nombre d'appels restants : --cuota.
• Ne tirez pas de conclusions avec des échantillons trop petits (< 100 impressions pour les vidéos, < 30 visites pour les landings).
• Si un script échoue, lisez le message (il est déjà en espagnol avec la solution) et guidez l'utilisateur ; les erreurs courantes sont dans le README (« Erreurs courantes »).