SaaS Onboarding Optimization: Reducing Time-to-Value

Signup → Activation → Adoption → Retention → Expansion

from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import List, Dict, Optional

@dataclass
class OnboardingMetrics:
    """Track key onboarding metrics."""
    
    # Activation metrics
    activation_rate: float  # % reaching activation
    time_to_activation: timedelta  # Average time
    activation_step_completion: Dict[str, float]  # Per-step
    
    # Adoption metrics  
    day_1_retention: float  # % returning day 1
    day_7_retention: float
    day_30_retention: float
    
    # Engagement metrics
    feature_adoption: Dict[str, float]  # Per-feature usage
    session_frequency: float  # Sessions per week
    session_duration: timedelta
    
    # Business metrics
    time_to_first_value: timedelta
    time_to_paid: timedelta
    nps_score: float


class OnboardingAnalyzer:
    """Analyze onboarding performance."""
    
    def __init__(self, analytics):
        self.analytics = analytics
        
    def calculate_activation_rate(self, cohort: str) -> float:
        """Calculate percentage of users reaching activation."""
        total_signups = self.analytics.count_signups(cohort)
        activated = self.analytics.count_activated(cohort)
        
        if total_signups == 0:
            return 0.0
            
        return (activated / total_signups) * 100
    
    def calculate_time_to_activation(self, cohort: str) -> timedelta:
        """Calculate average time to activation."""
        events = self.analytics.get_activation_events(cohort)
        
        if not events:
            return timedelta(0)
            
        times = [
            (event.activation_time - event.signup_time).total_seconds()
            for event in events
        ]
        
        avg_seconds = sum(times) / len(times)
        return timedelta(seconds=avg_seconds)
    
    def identify_drop_off_points(self, cohort: str) -> List[Dict]:
        """Find where users drop off in onboarding."""
        steps = [
            "signup",
            "email_verified",
            "profile_completed",
            "first_action",
            "first_success",
            "activation"
        ]
        
        dropoffs = []
        prev_count = self.analytics.count_signups(cohort)
        
        for step in steps:
            current_count = self.analytics.count_at_step(cohort, step)
            dropoff_rate = ((prev_count - current_count) / prev_count) * 100 if prev_count > 0 else 0
            
            dropoffs.append({
                "step": step,
                "users": current_count,
                "dropoff_rate": dropoff_rate
            })
            
            prev_count = current_count
            
        return dropoffs

def identify_aha_moment(events: List[Dict]) -> Optional[Dict]:
    """
    Find the event that best predicts retention.
    """
    from collections import defaultdict
    
    event_retention = defaultdict(lambda: {"total": 0, "retained": 0})
    
    for user in events:
        retained = user["retained_after_30_days"]
        
        for event in user["events"]:
            event_retention[event["type"]]["total"] += 1
            if retained:
                event_retention[event["type"]]["retained"] += 1
    
    # Calculate retention rate per event
    aha_candidates = []
    for event_type, data in event_retention.items():
        if data["total"] >= 100:  # Minimum sample
            retention_rate = data["retained"] / data["total"]
            aha_candidates.append({
                "event": event_type,
                "retention_rate": retention_rate,
                "frequency": data["total"]
            })
    
    # Sort by retention impact
    aha_candidates.sort(key=lambda x: x["retention_rate"], reverse=True)
    
    return aha_candidates[0] if aha_candidates else None


def design_aha_path(aha_event: str) -> List[Dict]:
    """
    Design minimal path to aha moment.
    """
    return [
        {
            "step": 1,
            "action": "Simplest possible setup",
            "expected_completion": 0.95
        },
        {
            "step": 2,
            "action": "Quick win (low effort, visible result)",
            "expected_completion": 0.80
        },
        {
            "step": 3,
            "action": "Aha moment event",
            "expected_completion": 0.60,
            "is_aha": True
        }
    ]

// Progressive onboarding with user segments
class OnboardingFlow {
  constructor(user) {
    this.user = user;
    this.currentStep = 0;
    this.completedSteps = [];
    this.skippedSteps = [];
  }

  getOnboardingPath() {
    const basePath = [
      { id: 'welcome', title: 'Welcome', required: true },
      { id: 'profile', title: 'Set up profile', required: true },
      { id: 'connect_data', title: 'Connect your data', required: false },
      { id: 'first_report', title: 'Create your first report', required: true },
      { id: 'invite_team', title: 'Invite your team', required: false },
      { id: 'upgrade', title: 'Explore premium features', required: false }
    ];

    // Customize based on user segment
    if (this.user.role === 'admin') {
      return basePath;  // Admins get full onboarding
    } else if (this.user.role === 'viewer') {
      return basePath.filter(step => step.id !== 'invite_team');
    } else if (this.user.fromCompetitor) {
      // Speed up for power users
      return basePath.filter(step => step.required);
    }

    return basePath;
  }

  shouldShowFeature(featureId) {
    // Check if user has reached appropriate step
    const stepIndex = this.getOnboardingPath().findIndex(
      step => step.id === featureId
    );
    
    return stepIndex <= this.currentStep;
  }
}

// Feature tour implementation
class FeatureTour {
  constructor() {
    this.steps = [];
    this.currentStep = 0;
  }

  addStep({ element, title, content, position = 'bottom' }) {
    this.steps.push({
      element,
      title,
      content,
      position
    });
    return this;
  }

  start() {
    this.showStep(0);
    this.attachListeners();
  }

  showStep(index) {
    if (index >= this.steps.length) {
      this.complete();
      return;
    }

    const step = this.steps[index];
    const targetElement = document.querySelector(step.element);

    if (!targetElement) {
      // Element not found, skip to next
      this.showStep(index + 1);
      return;
    }

    // Create tooltip
    const tooltip = this.createTooltip(step, index);
    document.body.appendChild(tooltip);

    this.highlightElement(targetElement);
    this.currentStep = index;
  }

  createTooltip(step, index) {
    const tooltip = document.createElement('div');
    tooltip.className = 'feature-tooltip';
    tooltip.innerHTML = `
      <div class="tooltip-header">
        <h3>${step.title}</h3>
        <button class="close-btn">&times;</button>
      </div>
      <div class="tooltip-content">${step.content}</div>
      <div class="tooltip-footer">
        <span class="step-counter">${index + 1} of ${this.steps.length}</span>
        <button class="next-btn">${index === this.steps.length - 1 ? 'Finish' : 'Next'}</button>
      </div>
    `;

    return tooltip;
  }

  next() {
    this.cleanup();
    this.showStep(this.currentStep + 1);
  }

  skip() {
    this.cleanup();
    this.trackSkipped();
  }
}

// Usage
const tour = new FeatureTour()
  .addStep({
    element: '#create-report-btn',
    title: 'Create Your First Report',
    content: 'Click here to start building your analytics report.',
    position: 'bottom'
  })
  .addStep({
    element: '.chart-type-selector',
    title: 'Choose Visualization',
    content: 'Select from various chart types to visualize your data.',
    position: 'right'
  })
  .addStep({
    element: '#save-report-btn',
    title: 'Save & Share',
    content: 'Save your report and share it with your team.',
    position: 'left'
  });

tour.start();

from dataclasses import dataclass
from typing import List, Optional
from enum import Enum

class HelpTrigger(Enum):
    ON_VIEW = "on_view"
    ON_CLICK = "on_click"
    ON_HOVER = "on_hover"
    ON_ERROR = "on_error"

@dataclass
class HelpContext:
    """Context for showing contextual help."""
    user_id: str
    current_screen: str
    user_role: str
    plan: str
    previous_actions: List[str]
    
class ContextualHelpSystem:
    """Intelligent contextual help based on user behavior."""
    
    def __init__(self):
        self.help_content = {}
        self.triggers = {}
        
    def register_help(self, feature: str, content: str, 
                     triggers: List[HelpTrigger], 
                     conditions: dict = None):
        """Register help content for a feature."""
        self.help_content[feature] = {
            "content": content,
            "triggers": triggers,
            "conditions": conditions or {}
        }
        
    def should_show_help(self, feature: str, context: HelpContext) -> bool:
        """Determine if help should be shown."""
        if feature not in self.help_content:
            return False
            
        help_info = self.help_content[feature]
        
        # Check conditions
        conditions = help_info["conditions"]
        
        if "min_actions" in conditions:
            if len(context.previous_actions) < conditions["min_actions"]:
                return False
                
        if "required_plan" in conditions:
            if context.plan not in conditions["required_plan"]:
                return False
                
        # Check if already seen
        if self.is_help_seen(context.user_id, feature):
            return False
            
        return True
    
    def get_help_for_screen(self, screen: str, context: HelpContext) -> Optional[dict]:
        """Get relevant help for current screen."""
        relevant = []
        
        for feature, help_info in self.help_content.items():
            if self.should_show_help(feature, context):
                if self.is_feature_on_screen(feature, screen):
                    relevant.append(help_info)
        
        # Return most relevant (highest priority)
        return relevant[0] if relevant else None
    
    def is_help_seen(self, user_id: str, feature: str) -> bool:
        """Check if user has seen this help."""
        # Query database/cache
        pass
    
    def is_feature_on_screen(self, feature: str, screen: str) -> bool:
        """Check if feature exists on current screen."""
        # Check feature mapping
        pass

import sendgrid
from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail

class OnboardingEmailSequence:
    """Automated email onboarding sequence."""
    
    def __init__(self, sg_client: SendGridAPIClient):
        self.sg = sg_client
        self.templates = {}
        
    def load_templates(self):
        """Load email templates."""
        self.templates = {
            "welcome": "d-1234567890ab",
            "setup_reminder": "d-abcdef123456",
            "activation_Congrats": "d-9876543210ab",
            "checkin_3day": "d-fedcba654321",
            "checkin_7day": "d-0123456789cd",
            "reengagement": "d-abcd1234efgh",
            "upgrade_prompt": "d-5678ij9012kl"
        }
    
    def send_welcome_email(self, user: dict):
        """Send welcome email immediately after signup."""
        message = Mail(
            from_email='[email protected]',
            to_emails=user['email'],
            subject='Welcome to Example SaaS!',
            html_content=self.render_template('welcome', user)
        )
        
        self.sg.send(message)
        
        # Schedule follow-up
        self.schedule_email('setup_reminder', user['id'], delay_days=1)
        
    def send_activation_congrats(self, user: dict):
        """Celebrate when user reaches activation."""
        message = Mail(
            from_email='[email protected]',
            to_emails=user['email'],
            subject="🎉 You've unlocked the power of Example!",
            html_content=self.render_template('activation_congrats', user)
        )
        
        self.sg.send(message)
        
    def send_reengagement(self, user: dict):
        """Re-engage dormant users."""
        # Get user's last action
        last_action = self.get_last_action(user['id'])
        days_since = (datetime.now() - last_action).days
        
        # Personalize based on where they dropped off
        template = self.templates.get(f"reengagement_{days_since // 7}week", 
                                     'reengagement')
        
        message = Mail(
            from_email='[email protected]',
            to_emails=user['email'],
            subject="We miss you! Let's get you unstuck",
            html_content=self.render_template(template, user)
        )
        
        self.sg.send(message)
    
    def render_template(self, template_name: str, user: dict) -> str:
        """Render email template with user data."""
        template_id = self.templates.get(template_name)
        
        # Use SendGrid dynamic templates
        return ""  # Return HTML
        
    def schedule_email(self, template: str, user_id: str, delay_days: int):
        """Schedule email to be sent later."""
        # Use job queue (Celery, RQ, etc.)
        pass

def personalize_onboarding_email(user: dict, template: str) -> str:
    """Personalize email content based on user data."""
    
    variables = {
        "first_name": user.get("first_name", "there"),
        "company_name": user.get("company_name", "your team"),
        "plan_name": user.get("plan_name", "free"),
        "role": user.get("role", "user"),
        "days_since_signup": (datetime.now() - user["signup_date"]).days
    }
    
    # Customize based on user segment
    if user.get("role") == "admin":
        variables["cta"] = "Set up your team"
        variables["admin_tips"] = get_admin_tips()
    else:
        variables["cta"] = "Start exploring"
        variables["quick_start"] = get_quick_start_guide()
    
    # Segment by source
    if user.get("source") == "referral":
        variables["referrer_name"] = user.get("referrer_name", "your friend")
        
    return render_template(template, variables)

from dash import Dash, html, dcc
import plotly.express as px

class OnboardingDashboard:
    """Real-time onboarding metrics dashboard."""
    
    def __init__(self, analytics_db):
        self.db = analytics_db
        self.app = Dash(__name__)
        self.setup_layout()
        
    def setup_layout(self):
        self.app.layout = html.Div([
            html.H1("Onboarding Analytics"),
            
            # Key metrics row
            html.Div([
                self.metric_card("Activation Rate", "activation_rate"),
                self.metric_card("Avg Time to Activation", "time_to_activation"),
                self.metric_card("Day 7 Retention", "day_7_retention"),
                self.metric_card("NPS Score", "nps_score")
            ], className="metrics-row"),
            
            # Funnel chart
            dcc.Graph(id="funnel-chart"),
            
            # Time series
            dcc.Graph(id="activation-trend"),
            
            # Drop-off analysis
            dcc.Graph(id="dropoff-analysis"),
            
            # Filters
            html.Div([
                dcc.DatePickerRange(id="date-range"),
                dcc.Dropdown(
                    id="cohort-filter",
                    options=[
                        {"label": "All Users", "value": "all"},
                        {"label": "Enterprise", "value": "enterprise"},
                        {"label": "SMB", "value": "smb"}
                    ],
                    value="all"
                )
            ])
        ])
        
    def metric_card(self, title: str, metric_id: str) -> html.Div:
        return html.Div([
            html.H3(title),
            dcc.Loading(dcc.Graph(id=metric_id))
        ])
        
    def get_funnel_data(self, date_range, cohort):
        """Get funnel data for visualization."""
        query = """
            SELECT 
                step_name,
                COUNT(DISTINCT user_id) as users
            FROM onboarding_events
            WHERE date BETWEEN %s AND %s
                AND cohort = %s
            GROUP BY step_name
            ORDER BY step_order
        """
        return self.db.query(query, [date_range[0], date_range[1], cohort])