# WooCommerce Plugin

The BasketBooster Recommender plugin syncs your WooCommerce catalog, tracks
shopper events, and renders recommendation and search widgets — auto-injected
on product/cart/shop pages and available as shortcodes and Gutenberg blocks.
No theme edits or code required.

## Requirements

- WordPress with WooCommerce active.
- A BasketBooster account (<https://dashboard.basketbooster.eu/register> —
  14-day free trial, no card).
- An active trial or plan (catalog sync requires one).

## Install

1. Download the plugin:
   <https://api.basketbooster.eu/plugin/basketbooster-recommender.zip>
   (also linked from your dashboard's setup page).
2. wp-admin → **Plugins → Add New Plugin → Upload Plugin** → choose the zip →
   **Install Now** → **Activate**.
   (Or: `wp plugin install basketbooster-recommender.zip --activate`.)
3. Open **WooCommerce → BasketBooster Recommender** (the plugin settings page).

## Connect

From your BasketBooster dashboard copy two keys into the plugin settings:

- **Publishable key** (`pk_...`) — *Recommender → Widget snippet* page. Used by
  the widgets in the shopper's browser.
- **Secret API key** — *API Keys* page (create one; it is shown only once).
  Used by WordPress server-side for catalog sync.

Set the **API base URL** to `https://api.basketbooster.eu`, then click
**Test connection**. A successful test also registers the plugin with your
account (platform, store URL, plugin version), which checks off the setup steps
on your dashboard's Home page.

## Sync your catalog

Click **Sync now** on the settings page. The plugin pushes your products
(title, image, price, categories, stock status, URL) to BasketBooster; the
search index and recommendation engines are provisioned and filled
automatically. After the first sync, product changes in WooCommerce are synced
incrementally.

The settings page shows live engine status — catalog items, last engine sync,
last trained — plus **Sync catalog to engines** and **Train now** buttons,
useful after a big import.

## Widgets

Once connected, widgets appear automatically:

- **Product pages** — "You may also like" and Frequently Bought Together.
- **Cart** — "Complete the cart" suggestions based on the basket contents.
- **Shop page** — trending products.

For custom placements, use shortcodes or the Gutenberg blocks anywhere:

```
[bbr_recommendations layout="carousel"]
[bbr_search]
```

Both accept a per-placement `layout="grid|carousel"` override.

## Appearance

Two places, one source of truth (stored in your BasketBooster account, fetched
live by the widgets):

- **Dashboard designer** — colors, fonts, custom CSS.
- **Plugin settings** — layout (grid ↔ carousel with arrows).

## Purchase tracking

The plugin tracks views, add-to-carts, and purchases automatically — including
the `order_id` grouping that feeds the Frequently-Bought-Together model. To
seed FBT with pre-existing sales, upload your order history CSV on the
dashboard (see [v1-api-reference](v1-api-reference.md), `POST /orders/upload`).

## Troubleshooting

- **Mixed content**: an HTTPS store must use the HTTPS API base — browsers
  block `http://` calls from `https://` pages. The settings page warns about
  this.
- **CORS**: publishable keys with an empty origin allowlist accept any origin.
  If you configured an allowlist in the dashboard, add your store's domain.
- **Sync errors**: shown verbatim on the settings page. The most common cause
  is an expired trial with no plan selected — pick a plan on the dashboard's
  Billing page (`402 billing_inactive`).
- **Widgets not visible**: confirm the publishable key is saved and check the
  browser console on a product page.