API Reference - Analytics

Documentation complète de l'API REST Lumyria pour les endpoints d'analytics et métriques BigQuery.

Authentification JWT

Token JWT requis

Toutes les requêtes à l'API Analytics doivent inclure un token JWT valide. Obtenez votre token via l'endpoint /api/auth/login.

Authorization: Bearer YOUR_JWT_TOKEN

Content-Type: application/json

X-Team-Context: team_id (optionnel)

Base URL et configuration

# Base URLs

Production: https://your-domain.com/api

Développement: http://localhost:8080/api

# Headers requis

Authorization: Bearer <JWT_TOKEN>

Content-Type: application/json

Accept: application/json

Note: Tous les endpoints analytics sont prefixés par /analytics/. Les données proviennent directement des tables BigQuery LumApps.

Endpoints Analytics disponibles

GET/api/analytics/dashboard-metricsCore

JWT requis

Métriques principales pour le dashboard (utilisateurs actifs, contenu, engagement)

GET/api/analytics/user-activityUsers

JWT requis

Activité détaillée des utilisateurs par période et département

GET/api/analytics/user-engagementUsers

JWT requis

Niveaux d'engagement des utilisateurs avec segmentation

GET/api/analytics/content-viewsContent

JWT requis

Statistiques de consultation de contenu et temps passé

GET/api/analytics/top-contentContent

JWT requis

Classement du contenu le plus populaire par catégorie

GET/api/analytics/video-analyticsVideo

JWT requis

Métriques spécialisées pour le contenu vidéo

GET/api/analytics/video-retention/:videoIdVideo

JWT requis

Courbe de rétention détaillée pour une vidéo spécifique

GET/api/analytics/search-analyticsSearch

JWT requis

Analytics des recherches : termes populaires, taux de succès

GET/api/analytics/community-statsCommunity

JWT requis

Performance des communautés : membres actifs, contributions

GET/api/analytics/notification-statsEngagement

JWT requis

Performance des notifications : taux d'ouverture, clics

GET/api/analytics/implication-levelsUsers

JWT requis

Classification des utilisateurs par niveau d'implication

GET/api/analytics/device-breakdownTechnical

JWT requis

Répartition par type d'appareil : desktop, mobile, tablet

GET/api/analytics/billingBusiness

JWT requis

Métriques de facturation et utilisation des ressources

GET/api/analytics/directory-usageDirectory

JWT requis

Utilisation de l'annuaire : recherches, consultations de profils

Dashboard Metrics - Endpoint principal

GET /api/analytics/dashboard-metrics

Récupère les métriques principales pour l'affichage dashboard : utilisateurs actifs, contenu populaire, engagement global.

Exemple de requête

# Récupérer les métriques dashboard

curl -X GET "http://localhost:8080/api/analytics/dashboard-metrics" \

-H "Authorization: Bearer YOUR_JWT_TOKEN" \

-H "Content-Type: application/json" \

-G -d "startDate=2024-01-01" -d "endDate=2024-01-31"

Paramètres de requête

Paramètre	Type	Requis	Description
startDate	string	-	Date de début (YYYY-MM-DD)
endDate	string	-	Date de fin (YYYY-MM-DD)
teamId	string	-	Filtrer par équipe spécifique
siteId	string	-	Filtrer par site LumApps

Réponse exemple

{
  "activeUsers": 1250,
  "totalContent": 8540,
  "avgEngagement": 0.67,
  "period": "last_30_days",
  "trends": {
    "users": "+12%",
    "content": "+8%",
    "engagement": "+5%"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

User Activity Analytics

GET /api/analytics/user-activity

Analyse détaillée de l'activité utilisateurs par période, département et type d'action.

Paramètres disponibles

Paramètre	Type	Description	Exemple
startDate	string	Date de début (YYYY-MM-DD)	2024-01-01
endDate	string	Date de fin (YYYY-MM-DD)	2024-01-31
department	string	Filtrer par département	marketing
groupBy	string	Grouper par période (day, week, month)	day
limit	number	Nombre max de résultats (défaut: 100)	50

Exemple de requête avec filtres

curl -X GET "http://localhost:8080/api/analytics/user-activity" \

-H "Authorization: Bearer YOUR_JWT_TOKEN" \

-G -d "startDate=2024-01-01" \

-d "endDate=2024-01-31" \

-d "department=marketing" \

-d "groupBy=day"

Réponse exemple

{
  "data": [
    {
      "date": "2024-01-15",
      "activeUsers": 245,
      "sessions": 567,
      "pageViews": 1234,
      "avgSessionDuration": 420
    }
  ],
  "total": 1,
  "period": "daily"
}

Endpoints spécialisés

Video Analytics

GET /api/analytics/video-retention/:videoId

Courbe de rétention détaillée pour une vidéo spécifique avec points d'abandon.

Implication Levels

GET /api/analytics/implication-levels

Classification des utilisateurs par niveau d'implication dans la plateforme.

Search Analytics

GET /api/analytics/search-analytics

Statistiques des recherches : termes populaires, taux de succès, suggestions.

Directory Usage

GET /api/analytics/directory-usage

Utilisation de l'annuaire : recherches, consultations de profils.

Gestion des erreurs

Réponse d'erreur standard

{
  "error": {
    "code": "BIGQUERY_ERROR",
    "message": "Erreur lors de l'exécution de la requête BigQuery",
    "details": {
      "query": "SELECT * FROM fact_user_activity",
      "bigqueryError": "Table not found"
    }
  }
}

Gestion des erreurs BigQuery

Les erreurs liées à BigQuery (tables manquantes, permissions insuffisantes) sont encapsulées avec des détails techniques pour faciliter le débogage.

Codes de réponse HTTP

Code HTTP	Status	Description
200	OK	Requête réussie, données retournées
400	Bad Request	Paramètres invalides ou manquants
401	Unauthorized	Token JWT manquant ou invalide
403	Forbidden	Permissions insuffisantes pour cette ressource
429	Rate Limited	Trop de requêtes, ralentir le débit
500	Server Error	Erreur interne, contacter le support

Rate limiting

• 1000 requêtes par heure par utilisateur
• 50 requêtes par minute pour les analytics temps réel
• Headers X-RateLimit-* inclus dans les réponses

Exemples d'intégration

JavaScript / React

// Hook personnalisé pour les analytics

const useAnalytics = (endpoint, params = {}) => {

const [data, setData] = useState(null)

const [loading, setLoading] = useState(true)

useEffect(() => {

const fetchData = async () => {

const response = await fetch('/api/analytics/'{endpoint}', {

headers: {

'Authorization': ' Bearer '{token}',

'Content-Type': 'application/json'

}

})

setData(await response.json())

setLoading(false)

}

fetchData()

}, [endpoint, params])

return { data, loading }

}

Python

# Client Python pour API Lumyria

import requests

from datetime import datetime

class LumyriaAnalytics:'

def __init__(self, base_url, token):'

self.base_url = base_url

self.headers = {

'Authorization': f'Bearer {token}',

'Content-Type': 'application/json'

}

def get_dashboard_metrics(self, start_date=None, end_date=None):

params = {}

if start_date: params['startDate'] = start_date

if end_date: params['endDate'] = end_date

response = requests.get(

f'{self.base_url}/analytics/dashboard-metrics',

headers=self.headers, params=params

)

return response.json()

API Reference - Analytics

Authentification JWT

Token JWT requis

Base URL et configuration

Endpoints Analytics disponibles

Dashboard Metrics - Endpoint principal

GET /api/analytics/dashboard-metrics

Exemple de requête

Paramètres de requête

Réponse exemple

User Activity Analytics

GET /api/analytics/user-activity

Paramètres disponibles

Exemple de requête avec filtres

Réponse exemple

Endpoints spécialisés

Video Analytics

Implication Levels

Search Analytics

Directory Usage

Gestion des erreurs

Réponse d'erreur standard

Gestion des erreurs BigQuery

Codes de réponse HTTP

Rate limiting

Exemples d'intégration

JavaScript / React

Python

Guides pratiques

Créer des Widgets API

Authentification JWT

Permissions API