# Dashboard Guide

> Complete guide to using your Databuddy analytics dashboard


import { Tab, Tabs } from "@/components/docs";
import { Callout } from "@/components/docs";
import { Card, Cards } from "@/components/docs";
import { Accordion, Accordions } from "@/components/docs";
import { CodeBlock } from "@/components/docs";

Your Databuddy dashboard provides comprehensive analytics insights with real-time data, detailed reports, and powerful filtering capabilities.

<Callout type="info">
  **Access**: Visit [app.databuddy.cc](https://app.databuddy.cc) to view your
  analytics dashboard
</Callout>

## Overview Tab

The overview tab gives you a high-level view of your website's performance with key metrics and trends.

### Key Metrics

<Cards>
  <Card title="Core Analytics">
    - **Pageviews** - Total page views across your site
    - **Visitors** - Unique visitors (deduplicated by anonymous ID)
    - **Sessions** - User sessions with 30-minute timeout
    - **Bounce Rate** - Percentage of single-page sessions
    - **Session Duration** - Average time spent per session
    - **Pages per Session** - Average pages viewed per session
  </Card>

  <Card title="Performance Metrics">
    - **Load Time** - Average page load time
    - **TTFB** - Time to First Byte
    - **Core Web Vitals** - LCP, FCP, CLS when available
  </Card>
</Cards>

### Time Range Selection

<Tabs items={['Quick Ranges', 'Custom Range']}>
<Tab value="Quick Ranges">

Choose from predefined time periods:

- **Today** and **Yesterday** - Real-time insights
- **Last 7 days** and **Last 14 days** - Weekly trends
- **Last 30 days**, **This month**, and **Last month** - Monthly overview
- **Last 90 days** - Quarterly analysis

</Tab>
<Tab value="Custom Range">

Select any date range for specific analysis:

- Pick start and end dates
- Compare different periods
- Analyze specific campaigns or events
- Export data for custom ranges

</Tab>
</Tabs>

<Callout type="info">
  **Comparison Mode**: Your selected period is automatically compared with the
  previous period of the same length.
</Callout>

### Data Granularity

View your metrics at different granularities based on your time range:

<Accordions>
<Accordion title="Hourly Granularity">

**Best for**: Last 24-48 hours

- Detailed hour-by-hour breakdown
- Perfect for monitoring recent changes
- Real-time performance tracking

</Accordion>

<Accordion title="Daily Granularity">

**Best for**: Weekly/monthly views

- Day-by-day analysis
- Identify weekly patterns
- Track daily performance trends

</Accordion>
</Accordions>

### Charts and Visualizations

**Interactive Metrics Chart:**

- Line charts showing trends over time
- Toggle different metrics on/off
- Interactive hover for detailed values
- Responsive design for mobile viewing

**Performance Indicators:**

- Green indicators for positive changes
- Red indicators for areas needing attention
- Percentage changes compared to previous period
- Automatic calculation based on selected time range

## Top Pages

Discover your most popular content and page performance:

### Page Analytics

<Cards>
  <Card title="Page Metrics">
    - **Page path and title** - URL and page title
    - **Total pageviews** - Number of views
    - **Unique visitors** - Distinct users
    - **Average time on page** - Engagement duration
    - **Bounce rate** - Single-page session rate
  </Card>

  <Card title="Interactive Features">
    - **Click to visit** - Click page paths to open them
    - **Sort by metrics** - Order by any column
    - **Pagination** - Handle large datasets efficiently
    - **Search & filter** - Find specific pages quickly
  </Card>
</Cards>

### Page Insights

<Callout type="info">
  **Performance Tip**: Pages with high bounce rates but long time-on-page often
  indicate quality content that doesn't require further navigation.
</Callout>

Use this data to:

- Identify your most valuable content
- Find pages that need optimization
- Track content performance over time
- Optimize user journeys

## Traffic Sources

Understand where your visitors come from and optimize your marketing efforts:

### Referrer Categories

<Accordions>
<Accordion title="Direct Traffic">

**Source**: Users typing your URL directly or from bookmarks

**Characteristics:**

- No referrer information
- Often returning visitors
- High-intent traffic
- Brand awareness indicator

**Optimization**: Focus on brand building and memorable URLs

</Accordion>

<Accordion title="Search Engines">

**Sources**: Google, Bing, DuckDuckGo, and other search engines

**Data Shown:**

- Search engine names
- Organic traffic volume
- Search performance trends

**Optimization**: SEO improvements and content strategy

</Accordion>

<Accordion title="Social Media">

**Sources**: Facebook, Twitter, LinkedIn, Instagram, etc.

**Insights:**

- Social platform performance
- Content sharing effectiveness
- Social engagement tracking

**Optimization**: Social media strategy and content tailoring

</Accordion>

<Accordion title="External Websites">

**Sources**: Other websites linking to you

**Benefits:**

- Referral traffic analysis
- Partnership effectiveness
- Backlink impact measurement

**Optimization**: Relationship building and link acquisition

</Accordion>
</Accordions>

### Traffic Analysis

For each source, you'll see:

- **Visitor counts** - Number of users from each source
- **Percentage breakdown** - Share of total traffic
- **Source classification** - Automatic categorization with icons
- **Trend analysis** - Growth or decline over time

## Geographic Analytics

Discover your global audience and optimize for different regions:

### Geographic Breakdown

<Tabs items={['Country View', 'Regional View']}>
<Tab value="Country View">

**Country-Level Analytics:**

- Country names with flag icons
- Visitor counts and percentages
- Interactive sortable data table
- Geographic distribution insights

**Use Cases:**

- Identify primary markets
- Plan localization efforts
- Understand global reach
- Optimize content for regions

</Tab>
<Tab value="Regional View">

**Detailed Location Data:**

- State/province information
- City-level analytics (when available)
- Time zone considerations
- Geographic clustering insights

**Benefits:**

- Local market analysis
- Regional campaign targeting
- Time zone optimization
- Location-based content strategy

</Tab>
</Tabs>

<Callout type="info">
  **Privacy Note**: Location is derived from the visitor's IP address at
  ingestion and stored at city level. The IP address itself is not stored, and
  no precise location tracking is performed.
</Callout>

<Callout type="tip" title="Powering the Map View">
  The geographic data displayed on maps and in regional breakdowns is typically
  derived from the user's IP address at the beginning of a session. Page views
  and sessions are tracked automatically; there is no separate SDK option to
  enable them. See [SDK configuration](/docs/sdk/configuration) for the optional
  controls.
</Callout>

## Technology Stack Analysis

Understand your audience's technical environment:

### Device Analytics

<Cards>
  <Card title="Device Types">
    **Categories:**
    - **Desktop** - Traditional computers
    - **Mobile** - Smartphones and mobile devices
    - **Tablet** - Tablets and large mobile devices
    **Metrics:**
    - Visitor distribution
    - Device-specific performance
    - User behavior patterns
  </Card>

  <Card title="Browser Information">
    **Data Included:**
    - Browser names and versions
    - Market share among your visitors
    - Browser-specific performance data
    - Compatibility insights
  </Card>
</Cards>

### Operating System Insights

**Platform Distribution:**

- **macOS** - Apple computers
- **Windows** - Microsoft Windows
- **Linux** - Linux distributions
- **iOS** - Apple mobile devices
- **Android** - Android devices

**Strategic Benefits:**

- Optimize for popular platforms
- Debug platform-specific issues
- Understand technical demographics
- Plan feature compatibility

<Callout type="warn">
  **Cross-Platform Considerations**: Ensure your website works well across all
  popular platforms used by your audience.
</Callout>

## Custom Events Analytics

Track and analyze your business-specific events with detailed property breakdowns:

<Callout type="info" title="Populating This Section">
  The analytics, breakdowns, and examples shown here are populated by the custom
  events you actively send from your application using the
  `db.track('your_event_name', {your_properties})` method. The more relevant and
  well-structured custom events you track, the more insightful this section will
  become. For detailed guidance on how to implement custom event tracking,
  please refer to the [Tracker Helpers](/docs/sdk/tracker) guide.
</Callout>

### Enhanced Event Interface

<Tabs items={['Hierarchical View', 'Property Breakdowns', 'Interactive Features']}>
<Tab value="Hierarchical View">

**Tree-Structure Analytics:**

- **Event Level** - Overall event metrics and performance
- **Property Categories** - Organized property groupings with counts
- **Property Values** - Individual values with percentage distributions
- **Visual Hierarchy** - Color-coded dots and professional typography

**Event Display Features:**

- **Event badges** - Blue dots for main events
- **Count displays** - Total events and unique users
- **Share percentages** - Relative event frequency
- **Occurrence tracking** - First and last event timestamps

</Tab>
<Tab value="Property Breakdowns">

**Automatic Property Analysis:**

- **Property extraction** - All custom properties automatically categorized
- **Value distribution** - Percentage breakdown of property values
- **Count aggregation** - Total occurrences per property value
- **Category sorting** - Properties sorted by frequency

**Property Category Features:**

- **Category headers** - Property names with aggregate counts
- **Value lists** - Individual property values with metrics
- **Usage indicators** - Visual badges showing value counts
- **Percentage pills** - Clean percentage displays

**Example Property Structure:**

```
Event: purchase_completed (156 events, 89 users)
├── product_category (156 values)
│   ├── software: 98 (63%)
│   ├── hardware: 45 (29%)
│   └── services: 13 (8%)
├── payment_method (156 values)
│   ├── credit_card: 124 (79%)
│   ├── paypal: 22 (14%)
│   └── bank_transfer: 10 (6%)
```

</Tab>
<Tab value="Interactive Features">

**User Experience Enhancements:**

- **Individual toggles** - Expand/collapse each property category independently
- **Scrollable content** - Handle large property lists with smooth scrolling
- **Visual feedback** - Hover effects and transition animations
- **Mobile responsive** - Optimized for all device sizes

**Navigation Features:**

- **Expand arrows** - Rotating chevrons indicate expansion state
- **Value count badges** - Show number of unique values per property
- **Scroll indicators** - Visual cues when content is scrollable
- **Professional styling** - Subtle gradients and clean borders

**Performance Optimizations:**

- **Lazy rendering** - Only render visible content
- **Efficient scrolling** - Max height limits with overflow handling
- **State management** - Persistent expand/collapse states
- **Touch optimization** - Mobile-friendly interaction areas

</Tab>
</Tabs>

### Event Examples

<Cards>
  <Card title="E-commerce Events">
    <CodeBlock
      language="json"
      code={`{
    "event": "purchase_completed",
    "properties": {
      "product_id": "prod_123",
      "revenue": 29.99,
      "currency": "USD",
      "category": "software"
    }
  }`}
    />
  </Card>

  <Card title="Engagement Events">
    <CodeBlock
      language="json"
      code={`{
    "event": "feature_used",
    "properties": {
      "feature": "export_data",
      "plan": "pro",
      "usage_count": 5
    }
  }`}
    />
  </Card>
</Cards>

## Advanced Filtering & Segmentation

Slice and dice your data for specific insights:

### Available Filters

<Accordions>
<Accordion title="Time-based Filters">

- **Date range selection** - Custom time periods

</Accordion>

<Accordion title="Audience Filters">

- **Device type filtering** - Mobile, desktop, tablet
- **Geographic filtering** - Country, region, city
- **Traffic source filtering** - Direct, search, social, referral
- **Visitor type** - New vs returning (when available)

</Accordion>

<Accordion title="Content Filters">

- **Page path filtering** - Specific pages or sections
- **Event filtering** - Specific custom events
- **Property filtering** - Event property values

</Accordion>
</Accordions>

### Segmentation Strategies

<Cards>
  <Card title="User Behavior Segments">
    - **High-engagement users** - Multiple page visits
    - **Quick browsers** - Short session durations
    - **Deep readers** - Long time on page
    - **Mobile-first users** - Primarily mobile traffic
  </Card>

  <Card title="Technical Segments">
    - **Performance impact** - Fast vs slow connections
    - **Browser compatibility** - Modern vs legacy browsers
    - **Device capabilities** - Screen size and features
    - **Platform preferences** - Operating system usage
  </Card>
</Cards>

## Performance Monitoring

Monitor your website's technical health and user experience:

<Callout type="tip" title="Enabling Performance Data">
  The performance metrics, including Core Web Vitals, are populated when you
  enable `trackWebVitals={true}` in your [SDK
  configuration](/docs/sdk/configuration). This allows the SDK to collect Core
  Web Vitals from the visitor's browser.
</Callout>

### Core Web Vitals

<Tabs items={['Understanding Metrics', 'Performance Optimization']}>
<Tab value="Understanding Metrics">

**Essential Performance Metrics:**

<Cards>
  <Card title="LCP - Largest Contentful Paint">
    **Good**: ≤ 2.5 seconds Measures loading performance. Time until the largest
    content element is rendered.
  </Card>

<Card title="INP - Interaction to Next Paint">
  **Good**: ≤ 200 milliseconds Measures responsiveness across user
  interactions during the page visit.
</Card>

<Card title="CLS - Cumulative Layout Shift">
  **Good**: ≤ 0.1 Measures visual stability. Sum of all unexpected layout shift
  scores.
</Card>

  <Card title="FCP - First Contentful Paint">
    **Good**: ≤ 1.8 seconds Time until first content element is rendered on
    screen.
  </Card>
</Cards>

</Tab>
<Tab value="Performance Optimization">

**Optimization Strategies:**

**For LCP (Loading):**

- Optimize images and videos
- Use a fast CDN
- Minimize resource load times
- Implement lazy loading

**For INP (Responsiveness):**

- Reduce JavaScript bundle size
- Optimize long-running tasks
- Use web workers for heavy computation
- Improve mobile responsiveness

**For CLS (Visual Stability):**

- Set dimensions for images/videos
- Avoid inserting content above existing content
- Use transform animations over layout changes
- Preload web fonts

</Tab>
</Tabs>

### Performance Analytics

**Detailed Performance Data:**

- **Load time distribution** - Histogram of page load times
- **Performance by page** - Page-specific metrics
- **Performance trends** - Changes over time
- **Mobile vs desktop** - Device-specific performance

<Callout type="info">
  **Performance Tip**: Use the performance data to identify slow pages and
  prioritize optimization efforts where they'll have the biggest impact.
</Callout>

## Error Tracking & Debugging

Monitor and resolve issues affecting your users:

<Callout type="tip" title="Enabling Error Data Collection">
  Error tracking requires the Hobby plan or higher. To populate the error
  tracking sections of the dashboard, ensure you have `trackErrors={true}`
  enabled in your [SDK configuration](/docs/sdk/configuration). This will
  automatically capture unhandled JavaScript errors and promise rejections. For
  more detailed context on specific handled errors, you can manually send error
  events using `db.track('error', {/* custom properties */})` as described in
  the [Tracker Helpers](/docs/sdk/tracker) guide.
</Callout>

### JavaScript Error Analytics

<Accordions>
<Accordion title="Error Details">

**Comprehensive Error Information:**

- **Error messages** - Descriptive error text
- **Error locations** - File, line, and column numbers
- **Stack traces** - Detailed execution path
- **Error frequency** - How often errors occur
- **Affected users** - Number of users experiencing errors

</Accordion>

<Accordion title="Error Categorization">

**Error Types:**

- **Unhandled JavaScript errors** - Runtime exceptions with stack, page, and session context
- **Unhandled promise rejections** - Async failures with the same context

</Accordion>

<Accordion title="Debugging Tools">

**Resolution Features:**

- **Error grouping** - Similar errors grouped together
- **Error trends** - Error frequency over time
- **Error by location** - Geographic error distribution
- **Error by device** - Device-specific error patterns

</Accordion>
</Accordions>

### Error Resolution Workflow

1. **Identify** - Spot errors in the dashboard
2. **Analyze** - Review stack traces and context
3. **Prioritize** - Focus on high-frequency errors
4. **Fix** - Implement solutions
5. **Verify** - Monitor error reduction

<Callout type="warn">
  **Error Impact**: JavaScript errors can significantly impact user experience.
  Regular monitoring helps maintain site reliability.
</Callout>

## Mobile Dashboard Experience

Access your analytics on any device:

### Mobile Features

**Optimized Mobile Interface:**

- Touch-friendly charts and graphs
- Responsive table layouts
- Mobile-optimized filtering
- Fast loading on mobile networks

**Mobile-Specific Insights:**

- Mobile vs desktop performance comparison
- Mobile user behavior patterns
- Mobile-specific error tracking
- Mobile Core Web Vitals monitoring

## Data Export & Integration

Get your data where you need it:

### Export Options

<Cards>
  <Card title="Data Export">
    Download your data as JSON or CSV via Website Settings > Data Export.
  </Card>

<Card title="API Access">
  Programmatic access to your analytics data via REST API.
</Card>

  <Card title="Investigations in Slack">
    Send actionable investigations to the Slack channels configured for your organization after each daily or weekly run. Replies are included clarifications using the same investigation's saved evidence. Start a new question or fresh analysis explicitly in the dashboard.
  </Card>
</Cards>

<Callout type="info">
  Uptime monitor alerts can be delivered to a webhook destination, but there is
  no outbound webhook streaming for analytics data.
</Callout>

## Getting the Most from Your Dashboard

### Best Practices

<Callout type="info">
  **Regular Monitoring**: Check your dashboard weekly to spot trends and issues
  early.
</Callout>

**Daily Tasks:**

- Check overall visitor trends
- Monitor error reports
- Review performance metrics
- Track custom events

**Weekly Analysis:**

- Compare week-over-week growth
- Analyze geographic trends
- Review device usage patterns
- Evaluate traffic sources

**Monthly Reviews:**

- Assess monthly growth trends
- Review goal achievement
- Analyze top-performing content
- Plan optimization strategies

## Dashboard Troubleshooting

### Common Issues

<Accordions>
<Accordion title="No Data Showing">

**Possible Causes:**

- SDK not properly installed
- Tracking disabled in development
- Domain not verified
- Ad blockers preventing data collection

**Solutions:**

- Verify SDK installation
- Check browser network tab for requests
- Ensure domain verification is complete
- Test with ad blockers disabled

</Accordion>

<Accordion title="Delayed Data Updates">

**Expected Behavior:**

- Data typically updates within 1-2 minutes
- Some metrics may take up to 5 minutes
- Refresh the page to see latest data

**If data is still delayed:**

- Check your internet connection
- Verify dashboard status page
- Contact support if issues persist

</Accordion>

<Accordion title="Missing Features">

**Feature Availability:**

- Some features require specific tracking to be enabled
- Custom events need manual implementation
- Performance metrics require opt-in tracking

**Enable Missing Features:**

- Review your SDK configuration
- Enable additional tracking options
- Implement custom event tracking

</Accordion>
</Accordions>

## Related Resources

<Cards>
  <Card title="SDK Reference" href="/docs/sdk">
    Complete SDK configuration and tracking options
  </Card>
  <Card title="Custom Events" href="/docs/sdk">
    Implement custom event tracking for business insights
  </Card>
  <Card title="Performance Tracking" href="/docs/sdk">
    Optimize your website's performance metrics
  </Card>
  <Card title="Security & Privacy Settings" href="/docs/security">
    Configure access control, allowed origins, IP restrictions, etc.
  </Card>
</Cards>

<Callout type="info">
  **Need Help?** Join our [Discord community](https://discord.gg/JTk7a38tCZ) or
  [contact support](mailto:support@databuddy.cc) for dashboard assistance.
</Callout>