Intégration PostHog pour Astro (Hybrid)

Ce skill vous aide à ajouter l'analytics PostHog à vos applications Astro (Hybrid).

Workflow

Suivez ces étapes dans l'ordre pour compléter l'intégration :

1. basic-integration-1.0-begin.md - Configuration PostHog - Début ← Commencez ici
2. basic-integration-1.1-edit.md - Configuration PostHog - Édition
3. basic-integration-1.2-revise.md - Configuration PostHog - Révision
4. basic-integration-1.3-conclude.md - Configuration PostHog - Conclusion

Fichiers de référence

• references/EXAMPLE.md - Code du projet exemple Astro (Hybrid)
• references/astro.md - Astro - documentation
• references/identify-users.md - Identifier les utilisateurs - documentation
• references/basic-integration-1.0-begin.md - Configuration PostHog - début
• references/basic-integration-1.1-edit.md - Configuration PostHog - édition
• references/basic-integration-1.2-revise.md - Configuration PostHog - révision
• references/basic-integration-1.3-conclude.md - Configuration PostHog - conclusion

Le projet exemple montre le pattern d'implémentation cible. Consultez la documentation pour les détails de l'API.

Principes clés

• Variables d'environnement : Utilisez toujours des variables d'environnement pour les clés PostHog. Ne les codez jamais en dur.
• Changements minimaux : Ajoutez le code PostHog aux côtés des intégrations existantes. Ne remplacez ni ne restructurez le code existant.
• Suivre l'exemple : Votre implémentation doit suivre les patterns du projet exemple aussi fidèlement que possible.

Directives du framework

• Utilisez toujours la directive is:inline sur les balises de script PostHog pour empêcher Astro de les traiter et de causer des erreurs TypeScript
• Utilisez le préfixe PUBLIC_ pour les variables d'environnement côté client dans Astro (par ex. PUBLIC_POSTHOG_PROJECT_TOKEN)
• Créez un composant posthog.astro dans src/components/ pour l'initialisation réutilisable sur les pages
• Importez le composant PostHog dans un Layout et enveloppez toutes les pages avec ce layout
• Utilisez posthog-node dans les routes API sous src/pages/api/ pour le suivi d'événements côté serveur
• Stockez l'instance du client posthog-node dans un pattern singleton (src/lib/posthog-server.ts) pour éviter de créer plusieurs clients
• Dans Astro 5, utilisez output static (le défaut) avec un adaptateur - les pages sont prérenderisées par défaut
• Utilisez export const prerender = false pour faire participer des pages spécifiques à SSR quand elles ont besoin du rendu côté serveur
• Seules les pages qui ont besoin du suivi PostHog côté serveur (comme les formulaires adossés à une API) doivent se retirer du prérenderisage

Identifier les utilisateurs

Identifiez les utilisateurs lors des événements de connexion et d'inscription. Reportez-vous au code exemple et à la documentation pour le pattern d'identification correct pour ce framework. Si du code frontend et backend coexistent, passez la session côté client et l'ID distinct en utilisant les en-têtes X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID pour maintenir la corrélation.

Suivi des erreurs

Ajoutez le suivi des erreurs PostHog aux fichiers pertinents, en particulier autour des flux utilisateur critiques et des limites d'API.