# Wishlist Analytics Feature Documentation

## Overview

The Wishlist Analytics feature provides a comprehensive admin dashboard for tracking and analyzing user wishlist activity. It includes visual charts, data tables, and key metrics to help store owners understand customer behavior and optimize their product offerings.

This feature was originally planned for the premium version (see `docs/PREMIUM.md` § 4) but has been implemented in the free version.

---

## Features

| Feature | Description |
|---------|-------------|
| **Summary Cards** | Total wishlist items, active users, unique products, and conversion rate at a glance |
| **Wishlist Trend Chart** | Line chart showing daily, monthly, or yearly wishlist additions over time |
| **Conversion Trend** | Overlay on the trend chart showing wishlist-to-cart conversions |
| **User Type Distribution** | Doughnut chart showing registered vs guest user split |
| **Most Wishlisted Products** | Table of top 10 products by wishlist count |
| **Top Users by Wishlist Items** | Table of top 10 registered users by wishlist item count with "View Wishlist" option |
| **Recent Activity** | Table showing the 10 most recent wishlist additions |
| **AJAX Period Switching** | Switch between daily, monthly, and yearly trend views without page reload |
| **Date Range Picker** | Select custom start and end dates to filter trend chart data |
| **Export to CSV** | Export analytics data (top products, user data, recent activity, trends) as CSV files |
| **User Wishlist Viewer** | View any user's full wishlist with product details in a modal dialog |

---

## Accessing the Dashboard

1. Navigate to **WordPress Admin → Bizz Wishlist → Analytics**
2. The dashboard loads automatically with current data
3. Use the **Daily / Monthly / Yearly** buttons on the trend chart to switch views
4. Use the **Date Range Picker** (From/To fields + Apply) for custom date ranges
5. Click **Export CSV** to download analytics data as CSV files
6. Click **View** on any user row to see their full wishlist in a modal

---

## File Structure

```
bizzwishlist/
├── includes/
│   ├── Admin/
│   │   └── Analytics/
│   │       ├── AnalyticsRepository.php   ← Database queries for all analytics data
│   │       ├── AnalyticsPage.php         ← Admin page registration & asset loading
│   │       ├── AnalyticsAjax.php         ← AJAX handlers for dynamic chart updates
│   │       └── views/
│   │           └── dashboard.php         ← Dashboard HTML template
│   ├── Ajax/
│   │   └── WishlistAjax.php             ← Modified: conversion event tracking
│   ├── Database/
│   │   └── Installer.php                ← Modified: analytics events table creation
│   └── Plugin.php                        ← Modified: analytics component wiring
│
├── assets/
│   ├── css/
│   │   └── admin-analytics.css           ← Dashboard styles
│   └── js/
│       ├── admin-analytics.js            ← Chart.js integration & interactivity
│       └── vendor/
│           └── chart.min.js              ← Chart.js v4.4.7 (UMD build)
│
└── docs/
    ├── analytics-feature-doc.md          ← This file
    ├── analytics-developer-guide.md      ← Developer code guide
    └── tutorials/
        └── analytics.md                  ← End-user tutorial
```

---

## Database

### Existing Table: `{prefix}_bizzwishlist`

Used to calculate analytics metrics (totals, trends, top products, user data).

| Column | Type | Description |
|--------|------|-------------|
| `id` | bigint(20) UNSIGNED | Primary key |
| `user_id` | bigint(20) UNSIGNED | Registered user ID (NULL for guests) |
| `session_key` | varchar(100) | Guest session key |
| `product_id` | bigint(20) UNSIGNED | WooCommerce product ID |
| `variation_id` | bigint(20) UNSIGNED | Variation ID (0 for simple products) |
| `created_at` | datetime | When item was added |
| `updated_at` | datetime | Last update time |

### New Table: `{prefix}_bizzwishlist_events`

Tracks conversion events (wishlist → cart actions).

| Column | Type | Description |
|--------|------|-------------|
| `id` | bigint(20) UNSIGNED | Primary key |
| `event_type` | varchar(50) | Event type (e.g., `add_to_cart`) |
| `product_id` | bigint(20) UNSIGNED | Product ID |
| `variation_id` | bigint(20) UNSIGNED | Variation ID |
| `user_id` | bigint(20) UNSIGNED | User ID (NULL for guests) |
| `created_at` | datetime | Event timestamp |

**Indexes:** `event_type`, `product_id`, `created_at`

---

## Key Metrics Explained

### Total Wishlist Items
Count of all rows in the `bizzwishlist` table.

### Active Users
Count of distinct `user_id` or `session_key` values (combines registered and guest users).

### Unique Products
Count of distinct `product_id` values across all wishlists.

### Conversion Rate
`(total add_to_cart events / total wishlist items) × 100`

Conversion events are logged whenever a user adds a product to the WooCommerce cart from the wishlist (via add-all-to-cart, add-single-to-cart, or add-selected-to-cart actions).

### Wishlist Trend
Daily: Groups by `DATE(created_at)` for the last 30 days.
Monthly: Groups by `YEAR-MONTH` for the last 12 months.
Yearly: Groups by `YEAR` for the last 5 years.
Custom Range: Filters by `DATE(created_at)` between the selected start and end dates.

### User Type Distribution
Registered users: rows where `user_id IS NOT NULL AND user_id > 0`.
Guests: rows where `session_key IS NOT NULL` and `user_id` is NULL or 0.

---

## Technologies Used

| Technology | Version | Purpose |
|------------|---------|---------|
| **Chart.js** | 4.4.7 | Client-side charting library |
| **jQuery** | WordPress bundled | AJAX calls and DOM manipulation |
| **WordPress AJAX** | - | Server-side data endpoints |

---

## Security

- All AJAX handlers verify nonces (`bizzwishlist_analytics_nonce`)
- Admin capability check (`manage_options`) on AJAX endpoints
- All user inputs are sanitized via `sanitize_text_field()` and `absint()`
- All database queries use `$wpdb->prepare()` for parameterized queries
- Output is escaped with `esc_html()`, `esc_url()`, `esc_attr()`

---

## Suggestions for Future Improvements

1. ~~**Export to CSV**~~ ✅ Implemented — Admins can export analytics data as CSV files
2. ~~**Date Range Picker**~~ ✅ Implemented — Custom date ranges with Yearly option added
3. **Product Category Filter** — Filter analytics by product category
4. **Email Reports** — Scheduled email reports with analytics summary
5. **Conversion Funnel** — Visualize the full funnel: View → Wishlist → Cart → Purchase
6. **Comparison Mode** — Compare data between two time periods
7. **REST API Endpoint** — Expose analytics data via the WordPress REST API for external integrations
8. ~~**User Wishlist Viewer**~~ ✅ Implemented — Admin can view any user's full wishlist from the analytics dashboard