documentation/ANALYTICS_SYSTEM.md

📊 Système d'Analytics & Tracking des Recherches

Vue d'ensemble

Le système d'analytics d'EduConnect Africa collecte et analyse toutes les recherches effectuées sur la plateforme pour comprendre les intérêts et comportements des utilisateurs.

Architecture

Modèles de Données

SearchLog

Enregistre chaque recherche individuelle avec :

• Utilisateur : Qui a effectué la recherche (null si anonyme)
• Catégorie : Type de contenu recherché (QUESTIONS, MENTORS, OPPORTUNITIES, etc.)
• Requête : Terme de recherche saisi
• Filtres : Filtres appliqués (JSON flexible)
• Résultats : Nombre de résultats retournés
• Métadonnées : Session ID, IP, User Agent, URL
• Interaction : Résultat cliqué et sa position

PopularSearch

Vue matérialisée des recherches les plus populaires :

• Catégorie
• Requête
• Nombre de fois recherchée
• Dernière recherche

API Endpoints

1. Enregistrer une recherche

POST /api/analytics/search-log/
Content-Type: application/json

{
  "category": "QUESTIONS",
  "search_query": "python django",
  "filters_applied": {
    "status": "unsolved",
    "tags": ["python"]
  },
  "results_count": 15
}

Response: 201 Created
{
  "id": 123,
  "category": "QUESTIONS",
  "search_query": "python django",
  "filters_applied": {...},
  "results_count": 15,
  "created_at": "2024-12-04T23:00:00Z"
}

2. Enregistrer un clic sur un résultat

POST /api/analytics/result-click/
Content-Type: application/json

{
  "search_log_id": 123,
  "result_id": "456",
  "position": 2
}

Response: 200 OK
{
  "status": "success"
}

3. Récupérer les recherches populaires

GET /api/analytics/popular-searches/?category=QUESTIONS&limit=10

Response: 200 OK
[
  {
    "category": "QUESTIONS",
    "search_query": "python",
    "search_count": 245,
    "last_searched": "2024-12-04T22:30:00Z"
  },
  ...
]

4. Récupérer les recherches tendances

GET /api/analytics/trending-searches/?category=QUESTIONS&days=7&limit=10

Response: 200 OK
[
  {
    "search_query": "django rest framework",
    "count": 45
  },
  ...
]

Utilisation Frontend

Hook React : useSearchTracking

Le hook personnalisé facilite l'intégration du tracking dans les composants.

Exemple d'intégration dans Questions.tsx

import { useSearchTracking } from '../hooks/useSearchTracking';

const Questions: React.FC = () => {
  const [searchTerm, setSearchTerm] = useState('');
  const [filter, setFilter] = useState<'all' | 'solved' | 'unsolved'>('all');
  const [questions, setQuestions] = useState<Question[]>([]);
  
  // Initialiser le tracking pour la catégorie QUESTIONS
  const { trackSearch, trackClick } = useSearchTracking('QUESTIONS');

  const fetchQuestions = async () => {
    try {
      const data = await forumService.getQuestions({
        page: currentPage,
        search: searchTerm,
        filter: filter === 'all' ? undefined : filter
      });
      
      setQuestions(data.results);
      
      // Tracker la recherche
      await trackSearch(
        searchTerm,
        { filter, page: currentPage },
        data.count
      );
    } catch (error) {
      console.error("Failed to fetch questions", error);
    }
  };

  const handleQuestionClick = (questionId: string, position: number) => {
    // Tracker le clic sur le résultat
    trackClick(null, questionId, position);
    
    // Naviguer vers la question
    navigate(`/questions/${questionId}`);
  };

  return (
    // ... JSX
  );
};

Service Direct

Si vous préférez utiliser le service directement :

import { analyticsService } from '../services/analytics';

// Enregistrer une recherche
const logId = await analyticsService.logSearch({
  category: 'MENTORS',
  search_query: 'python expert',
  filters_applied: { specialties: ['python', 'django'] },
  results_count: 8
});

// Enregistrer un clic
await analyticsService.logResultClick({
  search_log_id: logId.id,
  result_id: 'mentor-123',
  position: 0
});

// Récupérer les recherches populaires
const popular = await analyticsService.getPopularSearches('QUESTIONS', 10);

// Récupérer les tendances
const trending = await analyticsService.getTrendingSearches('MENTORS', 7, 10);

Catégories de Recherche

Catégorie	Description	Pages concernées
QUESTIONS	Questions du forum	/questions
MENTORS	Recherche de mentors	/mentors
OPPORTUNITIES	Bourses, stages, concours	/opportunities
TOOLS	Outils pédagogiques	/tools
USERS	Recherche d'utilisateurs	Divers
GENERAL	Recherche globale	Barre de recherche générale

Analyses Disponibles

1. Recherches Populaires

• Top 10/20/50 des recherches les plus fréquentes
• Par catégorie ou globalement
• Mise à jour en temps réel

2. Tendances

• Recherches en hausse sur les 7/14/30 derniers jours
• Détection de nouveaux sujets d'intérêt
• Comparaison temporelle

3. Taux de Clic (CTR)

• Pourcentage de recherches suivies d'un clic
• Position moyenne des clics
• Résultats les plus cliqués

4. Recherches Sans Résultats

• Identifier les lacunes de contenu
• Opportunités d'amélioration
• Suggestions de nouveaux contenus

Exemples de Requêtes SQL Utiles

Top 10 des recherches cette semaine

SELECT search_query, COUNT(*) as count
FROM search_logs
WHERE created_at >= NOW() - INTERVAL '7 days'
  AND category = 'QUESTIONS'
GROUP BY search_query
ORDER BY count DESC
LIMIT 10;

Recherches sans résultats

SELECT search_query, COUNT(*) as count
FROM search_logs
WHERE results_count = 0
  AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY search_query
ORDER BY count DESC
LIMIT 20;

Taux de clic par catégorie

SELECT 
  category,
  COUNT(*) as total_searches,
  COUNT(clicked_result_id) as clicks,
  ROUND(100.0 * COUNT(clicked_result_id) / COUNT(*), 2) as ctr_percentage
FROM search_logs
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY category
ORDER BY ctr_percentage DESC;

Intégration Recommandée

Pages à Tracker

1. Questions (/questions)

   • Recherche par mots-clés
   • Filtres : solved/unsolved, tags

2. Mentors (/mentors)

   • Recherche par nom, spécialités
   • Filtres : rating, disponibilité

3. Opportunités (/opportunities)

   • Recherche par titre, provider
   • Filtres : type, deadline, location

4. Outils (/tools)

   • Recherche par nom d'outil
   • Filtres : catégorie

Bonnes Pratiques

1. Debounce : Attendre 300-500ms après la dernière frappe avant de tracker
2. Minimum de caractères : Ne tracker que si ≥ 2 caractères
3. Anonymisation : Respecter la vie privée (pas de données sensibles)
4. Performance : Tracker en arrière-plan (async, non-bloquant)
5. Erreurs : Ne jamais bloquer l'UX si le tracking échoue

Dashboard Admin

Dans l'admin Django (/admin/analytics/), vous pouvez :

• Consulter tous les logs de recherche
• Filtrer par catégorie, date, utilisateur
• Voir les recherches populaires
• Exporter les données pour analyse externe

Prochaines Étapes

1. Dashboard Analytics : Interface dédiée pour visualiser les tendances
2. Suggestions Intelligentes : Autocomplétion basée sur les recherches populaires
3. A/B Testing : Tester différentes interfaces de recherche
4. Machine Learning : Recommandations personnalisées basées sur l'historique
5. Alertes : Notification quand un nouveau sujet devient tendance

---

Développé avec ❤️ par Marino ATOHOUN pour Hypee