diff --git a/src/components/analytics/README.md b/src/components/analytics/README.md new file mode 100644 index 0000000..6772263 --- /dev/null +++ b/src/components/analytics/README.md @@ -0,0 +1,265 @@ +# 📊 Sistema de Analytics + +Este diretório contém a implementação do sistema de analytics do Leiturama, utilizando Rudderstack como principal ferramenta de tracking. + +## 📦 Componentes + +### PageTracker +Componente responsável pelo tracking automático de visualizações de página. + +```tsx +// App.tsx + +``` + +### GoogleTagManager +Componente para integração com Google Tag Manager. + +```tsx +// App.tsx + +``` + +## 🎯 Hooks Disponíveis + +### useButtonTracking + +Hook para rastreamento de interações com botões e elementos clicáveis. + +```typescript +const { trackButtonClick } = useButtonTracking({ + category?: string; // Categoria do evento (default: 'interaction') + location?: string; // Localização do botão (default: pathname atual) +}); + +// Uso: +trackButtonClick('button-id', { + label: 'Botão de Login', + variant: 'primary', + position: 'header', + section: 'auth' +}); +``` + +### useFormTracking + +Hook para rastreamento de interações com formulários. + +```typescript +const { + trackFormStarted, + trackFormStepCompleted, + trackFormSubmitted, + trackFormError, + trackFormAbandoned, + trackFieldInteraction +} = useFormTracking({ + formId: string; // ID único do formulário + formName: string; // Nome descritivo do formulário + category?: string; // Categoria (default: 'form') +}); + +// Exemplos de Uso: +// Início do formulário +trackFormStarted(); + +// Completou um passo +trackFormStepCompleted('dados-pessoais', true); + +// Submeteu o formulário +trackFormSubmitted(true, { + user_type: 'student' +}); + +// Erro no formulário +trackFormError('validation', 'Email inválido', 'email'); + +// Abandonou o formulário +trackFormAbandoned('payment'); + +// Interação com campo +trackFieldInteraction('email', 'focus'); +``` + +### useStudentTracking + +Hook especializado para rastreamento de atividades do estudante. + +```typescript +const { + trackStoryGenerated, + trackAudioRecorded, + trackExerciseCompleted, + trackInterestAdded, + trackInterestRemoved +} = useStudentTracking(); + +// Exemplo: Rastrear geração de história +trackStoryGenerated({ + story_id: 'story-123', + theme: 'aventura', + prompt: 'Uma história sobre...', + generation_time: 2.5, + word_count: 300, + student_id: 'student-123' +}); + +// Exemplo: Rastrear exercício completado +trackExerciseCompleted({ + exercise_id: 'ex-123', + story_id: 'story-123', + student_id: 'student-123', + exercise_type: 'pronunciation', + score: 85, + time_spent: 120 +}); +``` + +### useErrorTracking + +Hook para rastreamento de erros e exceções. + +```typescript +const { + trackError, + trackErrorBoundary, + trackApiError +} = useErrorTracking({ + category?: string; // Categoria (default: 'error') + userId?: string; // ID do usuário + userEmail?: string; // Email do usuário +}); + +// Exemplo: Rastrear erro genérico +trackError(error, { + componentName: 'LoginForm', + action: 'submit', + metadata: { attempt: 2 } +}); + +// Exemplo: Rastrear erro de API +trackApiError(error, '/api/login', 'POST', { + email: 'user@example.com' +}); +``` + +## 📝 Padrões de Nomenclatura + +### Eventos + +- Use snake_case para nomes de eventos +- Formato: `{objeto}_{ação}` +- Exemplos: + - `button_clicked` + - `form_submitted` + - `story_generated` + - `exercise_completed` + +### Propriedades + +- Use snake_case para nomes de propriedades +- Categorize propriedades por namespace: + ```typescript + { + // Propriedades de página + page_url: string; + page_title: string; + + // Propriedades de usuário + user_id: string; + user_type: string; + + // Propriedades de elemento + element_type: string; + element_id: string; + + // Propriedades de formulário + form_id: string; + form_name: string; + } + ``` + +### Categorias + +Categorias predefinidas disponíveis em `EVENT_CATEGORIES`: +- `page`: Eventos de visualização de página +- `user`: Eventos relacionados ao usuário +- `story`: Eventos de histórias +- `exercise`: Eventos de exercícios +- `interaction`: Eventos de interação do usuário +- `error`: Eventos de erro +- `subscription`: Eventos de assinatura +- `auth`: Eventos de autenticação +- `navigation`: Eventos de navegação +- `form`: Eventos de formulário + +## 🔨 Exemplos de Implementação + +### Botão com Tracking + +```typescript + +``` + +### Formulário com Tracking + +```typescript +
+ {/* campos do formulário */} +
+``` + +### Link com Tracking + +```typescript + + Dashboard + +``` + +### Tracking de Erro em Try/Catch + +```typescript +try { + await submitForm(data); +} catch (error) { + errorTracking.trackError(error, { + componentName: 'SignupForm', + action: 'submit', + metadata: { + formData: data, + attempt: retryCount + } + }); +} +``` \ No newline at end of file