# Factorize Analytics — Quickstart

Five minutes from activation to your first drill-down. There are no settings, no API keys, and no cron jobs to set up — the plugin starts counting the moment it is active.

## Prerequisites

- WordPress 6.2 or newer, PHP 7.4 or newer
- **WooCommerce installed and active.** Without it the plugin stays inert (no fatal errors, just nothing to count): views are only counted on product pages, carts via WooCommerce's add-to-cart event, and sales come from WooCommerce itself.
- An admin or shop-manager account (`manage_woocommerce`) to see the Store Stats dashboard.

## Install

1. Upload the `factorize-analytics` folder to `/wp-content/plugins/` (or install the zip via **Plugins → Add New → Upload Plugin**).
2. Activate it. A **Factorize** menu appears in the admin sidebar — that hub is shared by all Factorize plugins, and any one of them alone creates it.

## First value in 5 steps

1. **Open Factorize → Store Stats.** On a fresh install everything reads 0 — that is expected; the counters only start with real traffic.
2. **Generate a few views.** Open two or three product pages in a *private/incognito window*. This matters: views from logged-in users who can edit products (admins, shop managers) are deliberately skipped, so browsing while logged in to wp-admin counts nothing.
3. **Add something to a cart** in that same private window.
4. **Reload Store Stats.** Site totals tick up; the category table shows where the action happened. Click a category name to drill into its per-product rows (views, carts, sold, popularity, stock).
5. **Check the other two surfaces:** the **Products → All Products** list now has Views / Carts / Sold columns (each "this week / all time", Views and Carts sortable), and once a product has non-zero weekly numbers its single product page shows a small social-proof line under the price ("3 views this week · 1 added to cart").

## Configuration

Version 1.0.0 has **no tunables** — the table below is intentionally empty. The config plumbing exists so future settings can land without changing call sites.

| key | default | effect |
| --- | ------- | ------ |
| *(none yet)* | — | — |

How the plumbing works when keys do exist:

- `update_option( 'factorize-analytics_options', array( ... ) )` overrides any subset of defaults (the legacy `empire-product-analytics_options` option is still read as a fallback).
- The merged array passes through the `factorize-analytics_config` filter for code-level overrides.
- `empire_analytics_config( $key )` returns one value; `empire_analytics_config()` returns the whole array.

Where the data lives — six post-meta keys per product: `_et_views_total`, `_et_views_week`, `_et_views_week_key`, `_et_carts_total`, `_et_carts_week`, `_et_carts_week_key`. The weekly keys store the ISO week (`2026-36`), which is how the 7-day figures reset themselves without cron.

## Troubleshooting

- **"I browsed my own store and the view count stayed at 0."** Working as intended. Logged-in users with the `edit_products` capability are skipped, and user agents matching bot/crawler patterns are ignored. Test logged out or in a private window.
- **"Weekly Sold is 0 and Popularity shows a dash."** Those two figures come from the sibling **Factorize Catalog** plugin (`empire_tools_weekly_sales()` and the `et_popularity` meta). Without it they read 0 / — while lifetime Sold (straight from WooCommerce) and everything else keeps working.
- **"The product page shows no stats line."** Only metrics with a non-zero weekly number are printed — a new product shows nothing rather than a row of zeros. Also note the line is an unstyled `<p class="et-stats">`; the plugin ships no CSS, so give it a style in your theme if it looks plain.
- **"Store Stats is slow."** The page recomputes totals by reading meta for every product (published and draft) on each load. That is instant on the 950-product store it was built for, but a catalog in the tens of thousands will feel it.
