Eve library

Analytics Event Schemas - Non-PII Definitions

Guide

Revision 1

On this page

Overview#

This document defines privacy-compliant event schemas for the Lilith wisdom platform. All schemas follow non-PII principles, using session IDs, hashed user IDs, and aggregate metrics to protect user privacy while providing valuable analytics.

Privacy Principles#

  • No Direct PII: No names, emails, or identifying information
  • Hashed User IDs: Cryptographically hashed with rotating salts
  • Session-Based Tracking: Temporary session identifiers for user flows
  • Consent-Required: All events require explicit user consent
  • Retention Limits: Automatic deletion after defined periods
  • Aggregation-First: Individual events aggregated before analysis

Base Event Structure#

All events follow this base schema:

typescript
interface BaseEvent {
  event_id: string; // UUID for deduplication
  event_type: string; // Event type identifier
  timestamp: string; // ISO 8601 timestamp
  session_id: string; // Temporary session identifier
  user_hash?: string; // Optional hashed user ID (if consented)
  platform: 'web' | 'ios' | 'android';
  version: string; // App/platform version
  locale: string; // User locale (e.g., 'en-US')
  timezone: string; // User timezone
}

1. Conversation & Chat Events#

ConversationStarted#

typescript
interface ConversationStartedEvent extends BaseEvent {
  event_type: 'conversation.started';
  persona: string; // Selected persona (zen, stoic, sufi)
  conversation_id: string; // Conversation identifier
  input_modality: 'text' | 'voice';
  context_type?: 'course' | 'freeform' | 'reflection';
  course_id?: string; // If part of course
}

MessageCompleted#

typescript
interface MessageCompletedEvent extends BaseEvent {
  event_type: 'message.completed';
  conversation_id: string;
  message_id: string;
  persona: string;
  latency_ms: number; // Total response time
  tokens_in: number; // Input token count
  tokens_out: number; // Output token count
  rag_hit_rate: number; // 0.0-1.0 retrieval success
  citations_count: number; // Number of citations provided
  safety_flags: string[]; // Moderation flags triggered
  user_rating?: number; // 1-5 if user rated response
}

ConversationEnded#

typescript
interface ConversationEndedEvent extends BaseEvent {
  event_type: 'conversation.ended';
  conversation_id: string;
  persona: string;
  duration_ms: number; // Total conversation time
  message_count: number; // Total messages exchanged
  user_initiated_end: boolean; // User ended vs timeout
}

2. Learning & Course Events#

CourseStarted#

typescript
interface CourseStartedEvent extends BaseEvent {
  event_type: 'course.started';
  course_id: string;
  course_type: 'meditation' | 'philosophy' | 'lifestyle';
  course_tradition: string; // Buddhist, Stoic, Sufi, etc.
  difficulty_level: 'beginner' | 'intermediate' | 'advanced';
  estimated_duration_minutes: number;
}

LessonCompleted#

typescript
interface LessonCompletedEvent extends BaseEvent {
  event_type: 'lesson.completed';
  course_id: string;
  lesson_id: string;
  lesson_order: number; // Position in course
  completion_time_ms: number; // Time to complete
  engagement_score: number; // 0.0-1.0 based on interaction
  modality_mix: {
    // Time spent per modality
    text_ms: number;
    audio_ms: number;
    reflection_ms: number;
  };
}

CourseCompleted#

typescript
interface CourseCompletedEvent extends BaseEvent {
  event_type: 'course.completed';
  course_id: string;
  total_duration_ms: number; // Time from start to finish
  completion_rate: number; // 0.0-1.0 lessons completed
  average_lesson_score: number; // Average engagement
  reflections_completed: number;
  final_rating?: number; // 1-5 course rating
}

ReflectionSubmitted#

typescript
interface ReflectionSubmittedEvent extends BaseEvent {
  event_type: 'reflection.submitted';
  course_id?: string; // If part of course
  lesson_id?: string; // If lesson-specific
  reflection_type: 'daily' | 'lesson' | 'insight' | 'gratitude';
  word_count: number; // Text length (no content)
  completion_time_ms: number; // Time to write
  is_private: boolean; // User privacy preference
}

3. Media & TTS Events#

TTSStarted#

typescript
interface TTSStartedEvent extends BaseEvent {
  event_type: 'tts.started';
  request_id: string;
  voice_id: string; // Voice identifier (not user voice)
  text_length: number; // Character count
  expected_duration_ms: number;
}

TTSCompleted#

typescript
interface TTSCompletedEvent extends BaseEvent {
  event_type: 'tts.completed';
  request_id: string;
  voice_id: string;
  duration_ms: number; // Actual audio duration
  first_byte_ms: number; // Time to first audio byte
  quality_score?: number; // MOS rating if provided
  error_code?: string; // If failed
}

AudioPlaybackEvent#

typescript
interface AudioPlaybackEvent extends BaseEvent {
  event_type: 'audio.playback';
  content_id: string; // Lecture, meditation, etc.
  action: 'started' | 'paused' | 'resumed' | 'completed' | 'skipped';
  position_ms: number; // Playback position
  total_duration_ms: number; // Total audio length
  playback_speed: number; // 0.5x, 1.0x, 1.5x, etc.
}

4. Engagement & Session Events#

SessionStarted#

typescript
interface SessionStartedEvent extends BaseEvent {
  event_type: 'session.started';
  entry_point: 'app_launch' | 'notification' | 'web' | 'deeplink';
  device_type: 'mobile' | 'tablet' | 'desktop';
  network_type: 'wifi' | 'cellular' | 'unknown';
}

SessionEnded#

typescript
interface SessionEndedEvent extends BaseEvent {
  event_type: 'session.ended';
  duration_ms: number; // Total session time
  screens_visited: string[]; // Screen identifiers
  actions_performed: number; // Total user actions
  exit_reason: 'user' | 'timeout' | 'background' | 'error';
}

FeatureUsed#

typescript
interface FeatureUsedEvent extends BaseEvent {
  event_type: 'feature.used';
  feature_name: string; // 'voice_chat', 'offline_download', etc.
  feature_category: 'core' | 'premium' | 'experimental';
  usage_context: string; // Where/how feature was accessed
  success: boolean; // Feature worked as expected
}

5. Quality & Feedback Events#

ContentRated#

typescript
interface ContentRatedEvent extends BaseEvent {
  event_type: 'content.rated';
  content_id: string;
  content_type: 'response' | 'lecture' | 'course' | 'meditation';
  rating: number; // 1-5 stars
  rating_category: 'helpful' | 'accurate' | 'clear' | 'inspiring';
  persona?: string; // If persona-generated content
}

IssueReported#

typescript
interface IssueReportedEvent extends BaseEvent {
  event_type: 'issue.reported';
  issue_type: 'technical' | 'content' | 'safety' | 'accessibility';
  issue_category: string; // Specific subcategory
  severity: 'low' | 'medium' | 'high' | 'critical';
  context_id?: string; // Related content/conversation ID
  auto_collected: boolean; // System-detected vs user-reported
}

SearchPerformed#

typescript
interface SearchPerformedEvent extends BaseEvent {
  event_type: 'search.performed';
  query_length: number; // Character count (no actual query)
  search_category: 'courses' | 'wisdom' | 'practices' | 'all';
  results_count: number; // Number of results returned
  clicked_position?: number; // Position of clicked result
  has_filters: boolean; // Used search filters
}

6. Performance & System Events#

PerformanceMetric#

typescript
interface PerformanceMetricEvent extends BaseEvent {
  event_type: 'performance.metric';
  metric_name: string; // 'page_load', 'api_response', etc.
  metric_value: number; // Measured value (ms, bytes, etc.)
  metric_unit: string; // 'ms', 'bytes', 'percent', etc.
  operation_type: string; // 'chat', 'tts', 'course_load', etc.
  success: boolean; // Operation successful
}

ErrorOccurred#

typescript
interface ErrorOccurredEvent extends BaseEvent {
  event_type: 'error.occurred';
  error_code: string; // Standardized error code
  error_category: 'network' | 'auth' | 'media' | 'ai' | 'ui';
  severity: 'info' | 'warn' | 'error' | 'critical';
  operation: string; // What user was trying to do
  retry_attempted: boolean; // User retried the operation
  resolved: boolean; // Error was resolved in session
}

ConsentUpdated#

typescript
interface ConsentUpdatedEvent extends BaseEvent {
  event_type: 'consent.updated';
  consent_type: 'analytics' | 'voice_cloning' | 'research' | 'marketing';
  consent_granted: boolean; // User granted or revoked
  consent_version: string; // Version of consent text
  collection_method: 'explicit' | 'banner' | 'settings' | 'onboarding';
}

DataExportRequested#

typescript
interface DataExportRequestedEvent extends BaseEvent {
  event_type: 'data.export_requested';
  export_type: 'personal_data' | 'conversations' | 'progress' | 'all';
  request_method: 'settings' | 'support' | 'api';
}

Schema Validation & TypeScript Types#

typescript
// Union type of all events for type safety
type AnalyticsEvent =
  | ConversationStartedEvent
  | MessageCompletedEvent
  | ConversationEndedEvent
  | CourseStartedEvent
  | LessonCompletedEvent
  | CourseCompletedEvent
  | ReflectionSubmittedEvent
  | TTSStartedEvent
  | TTSCompletedEvent
  | AudioPlaybackEvent
  | SessionStartedEvent
  | SessionEndedEvent
  | FeatureUsedEvent
  | ContentRatedEvent
  | IssueReportedEvent
  | SearchPerformedEvent
  | PerformanceMetricEvent
  | ErrorOccurredEvent
  | ConsentUpdatedEvent
  | DataExportRequestedEvent;

// Event validation function
function validateEvent(event: unknown): event is AnalyticsEvent {
  // Implementation would validate required fields,
  // data types, and schema compliance
  return true; // Placeholder
}

Usage Guidelines#

  1. Consent First: Never collect events without explicit user consent
  2. Minimal Data: Only collect what's necessary for the specific metric
  3. Secure Transmission: Use HTTPS and encrypt sensitive event data
  4. Retention Policy: Auto-delete events after defined periods (30-90 days)
  5. Aggregation: Process events into aggregate metrics, delete individuals
  6. Audit Trail: Log all analytics collection and processing activities

Implementation Notes#

  • Events should be batched and sent asynchronously to avoid UX impact
  • Include circuit breakers to handle analytics service outages gracefully
  • Implement client-side sampling to reduce volume for high-frequency events
  • Use exponential backoff for failed event transmission
  • Validate all events against schemas before processing
  • Include monitoring for schema evolution and breaking changes