=== Decision Widget — Product Quiz Recommendations ===
Contributors: decisionwidget, joelchouinard
Tags: affiliate, amazon, product recommendations, quiz, embed
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn any blog post into an interactive product recommendation engine. 359 categories, 9,000+ products, live retailer deals. Free forever.

== Description ==

**Stop listing products. Start recommending them.**

DecisionWidget turns your affiliate content into an interactive recommendation engine. Instead of static "top 10" lists your readers skim and bounce from, they take a 5-question quiz and get a personalized match — with transparent scoring that shows exactly why each product was recommended.

**Drop in one shortcode. Pick from 359 categories. Done.**

= Everything included, free forever: =

* **359 ready-to-embed categories** — from stand mixers to noise-cancelling headphones to mechanical keyboards
* **9,000+ curated products** — individually vetted, 4.5+ star rated, scored against real buying criteria
* **Live retailer deal badges** — "50% off" and "Lightning Deal — 3h left" pulled in real time
* **AI-generated buying guides** — quality-scored 85+/100, written specifically for each category
* **Transparent scoring** — every recommendation shows the why, not just the what
* **Multi-market support** — automatically routes to the right regional storefront based on visitor location (US/UK/CA/AU)
* **Gutenberg block + shortcode** — works with any theme, any page builder
* **Zero maintenance** — products, prices, deals, and content update automatically

= Who this is for: =

* Affiliate bloggers who want to upgrade from link tables to conversion tools
* Review sites that need depth across many categories without hiring writers
* Content marketers who want readers to engage, not just skim
* Niche site builders who want the conversion lift industry research consistently finds with interactive content vs. static comparison tables (typically 3–5×)

= Why publishers are switching from link managers to DecisionWidget: =

Traditional affiliate plugins help you organize links. DecisionWidget helps your readers decide. That's a categorical difference. Your readers don't want another list — they want an answer to the question "which one is right for me?" DecisionWidget answers it in 30 seconds with scoring they can trust.

= Urgency that converts — without lifting a finger =

Static affiliate links have no urgency. DecisionWidget embeds surface real-time retailer deals the moment they happen:

* "50% off — today only" badges pulled live from each retailer
* Lightning Deal countdowns ("ends in 2h 47m")
* Price drops flagged automatically

Your readers see the same urgency signals they'd see at the retailer — except they're deciding before they leave your page.

= What you get vs. building it yourself: =

Major review sites spend six figures building custom recommendation engines. DecisionWidget drops the same capability into your site in 60 seconds. You focus on writing great content. We handle the products, the quiz logic, the scoring, the deals, the buying guides, the updates.

== Installation ==

1. Install: Go to Plugins → Add New → search "Decision Widget" → Install → Activate
2. Activate: Go to Settings → Decision Widget → click "Activate — Start Embedding Quizzes"
3. Add to a post: Open any post → click "+" → search "Decision" → add the Decision Widget block → pick a category → Publish

That's it. Three clicks from install to live quiz. No account needed, no configuration, no code.

For detailed help, see the "How to Use" guide inside the plugin settings page.

== Usage ==

= Embed Modes: =

**Full Quiz** (default) — Interactive 5-question recommendation quiz:
`[decisionwidget category="noise-cancelling-headphones"]`

**Inline CTA** — Subtle mid-paragraph prompt that expands to show top 3 picks:
`[decisionwidget category="noise-cancelling-headphones" mode="inline"]`

**Compact Card** — Small sidebar widget showing the #1 pick:
`[decisionwidget category="noise-cancelling-headphones" mode="compact"]`

**Versus** — Head-to-head product comparison with specs, winner badge, and verdict:
`[decisionwidget category="noise-cancelling-headphones" mode="versus" versus="sony-wh1000xm5_vs_bose-qc-ultra"]`

= With options: =

`[decisionwidget category="robot-vacuums" height="800" theme="dark"]`

= Gutenberg Block: =

Search for "Decision Widget" in the block inserter. Select a category from the dropdown, choose an embed mode, adjust height, and publish. The versus mode includes a text input for the pair slug.

= Example: =

A food blogger writes "Best Stand Mixers of 2026." Instead of a static comparison table, she drops in `[decisionwidget category="stand-mixers"]`. Her readers answer five quick questions — budget, capacity, what they bake, countertop space, color preference — and get a personalized match with live retailer pricing and a Lightning Deal badge.

Her bounce rate drops. Her affiliate revenue climbs. Her post ranks higher because visitors engage instead of skim. She wrote nothing new. She just added one line.

For a "KitchenAid vs Cuisinart" comparison post, she adds `[decisionwidget category="stand-mixers" mode="versus" versus="kitchenaid-artisan_vs_cuisinart-precision"]` for a head-to-head widget with specs and a winner badge.

== Frequently Asked Questions ==

= Is it free? =

Yes — unlimited categories, unlimited embeds, no credit card. Upgrade to Growth ($29/mo) to route commissions to your own affiliate tags.

= Do I need an affiliate account? =

Only on Growth tier ($29/mo). We support multiple affiliate networks — Amazon Associates is the most common, with specialty retailers and other networks routed where applicable. The free tier works without any affiliate account.

= How many quizzes can I embed? =

Unlimited. Embed as many different categories as you want across your entire site.

= Does it slow down my site? =

No. The quiz loads in a lightweight iframe with lazy-loading and doesn't affect your page speed score or Core Web Vitals.

= What data is sent to Decision Widget? =

Your site URL and Partner ID for click attribution. No visitor personal data is collected or transmitted. See our privacy policy for details.

= What categories are available? =

359 categories covering electronics, kitchen, fitness, outdoor, home, office, audio, photography, gaming, and more. New categories are added regularly.

= What if Decision Widget's server is down? =

The plugin gracefully shows a "temporarily unavailable" message with a link to view recommendations on decisionwidget.net. Your page layout is never broken.

== Screenshots ==

1. Setup wizard — connect in 30 seconds
2. Category browser — search and click to copy shortcode
3. Gutenberg block — drag, drop, select category
4. Embedded quiz — visitors answer 5 questions
5. Recommendations — personalized match with deal badges

== External services ==

This plugin connects to the Decision Widget service hosted at decisionwidget.net to deliver interactive product recommendation quizzes and to power the in-product tools described below. Your readers' visit to your site does not result in any data being sent to Decision Widget; only the plugin's own administrative requests and the visitor's browser loading the embed iframe do.

The plugin makes the following requests:

**1. Category list — https://www.decisionwidget.net/api/categories**

* When: Once per day, only after you have given consent in the setup wizard. The list is cached for 24 hours.
* What is sent: The standard HTTP request only (no user data, no site URL, no cookies).
* Why: To populate the category dropdown in the Gutenberg block and shortcode picker so you can choose which quiz to embed.

**2. Account status — https://www.decisionwidget.net/api/v1/account/status**

* When: Only if you have entered a Partner ID in the plugin settings. Cached for 1 hour.
* What is sent: Your Partner ID (which you entered yourself).
* Why: To display your current plan, monthly click usage, and quota reset date in the plugin settings page.

**3. Quiz embed iframe — https://www.decisionwidget.net/embed/{slug}**

* When: When a page containing the shortcode or Gutenberg block is rendered in a visitor's browser. The iframe is loaded by the visitor's browser, not by your server.
* What is sent: The category slug you selected, your Partner ID (if set), the embed mode, and the host page URL (used for click attribution).
* Why: To render the interactive quiz inside the iframe.

**4. Deactivation feedback — https://www.decisionwidget.net/api/wp/deactivation**

* When: Only when you click "Deactivate" on the plugin and submit a choice in the deactivation modal that appears (upgrade, leave email for product updates, or deactivate with optional reason). Sent from your administrative browser, not your server.
* What is sent: Your selected action (upgrade / email / remove), an optional email address (only if you typed one), an optional reason code from the dropdown, your site host, your anonymous site ID, and your Partner ID (if set).
* Why: To track churn signals and to follow up with product updates if you opted in. Fire-and-forget — never blocks the deactivation.

**5. Post & Page Scanner — https://www.decisionwidget.net/api/wp/scan-posts**

* When: Only when you click "Scan My Posts" on the settings page. Sent from your administrative browser.
* What is sent: A list of up to 50 of your published posts and pages — for each: its WordPress post ID, title, excerpt, and URL — read from your own site's WordPress REST API.
* Why: To suggest which posts would benefit from an embedded quiz and which category best fits each one.

**6. Conversation Insights — https://www.decisionwidget.net/api/wp/scan-comments**

* When: Only when you click "Scan Comments" on the settings page. Sent from your administrative browser.
* What is sent: Up to 100 approved comments from your site — for each: its comment ID, the post it's on, the post title, the commenter's display name, and the comment content — read from your own site's WordPress REST API.
* Why: To surface which product categories your audience is already discussing in comments, so you know where to add a quiz.

By using this plugin, you agree to the Decision Widget Terms of Service and Privacy Policy:

* Terms of Service: https://www.decisionwidget.net/terms
* Privacy Policy: https://www.decisionwidget.net/privacy

== Changelog ==

= 1.1.0 =

Major upgrade to the flagship feature set, with full WordPress.org compliance applied throughout.

New features:
* Four embed modes — Full Quiz, Inline CTA, Compact Card, Versus
* Mode tab selector on the settings page with live shortcode preview
* Mode dropdown in the Gutenberg block inspector
* Live preview modal for each embed mode
* "How to Use" expandable in-product guide with Gutenberg + shortcode instructions
* Common Questions FAQ section
* "Other Platforms" HTML snippet generator (Blogger, Ghost, Substack, Squarespace, Wix, Webflow, plain HTML)
* Performance dashboard with embed loads, affiliate clicks, and estimated commission value (based on industry-standard affiliate metrics applied to your measured traffic)
* Post & Page Scanner — reads your archive and suggests which posts to embed, with one-click shortcode copy
* Conversation Insights — mines approved comments to surface which categories your audience is already discussing
* Deactivation feedback modal (with optional email opt-in for product updates)
* Embed load tracking
* Auto-height per mode

Architecture and compliance:
* All inline JavaScript moved to separate files in assets/ (admin-deactivate.js, admin-settings.js, block.js)
* Hook-gated script enqueueing — admin assets only load on plugins.php and the plugin's settings page
* All user-facing strings flow through wp_localize_script for full i18n support
* Plugin-prefixed identifiers throughout (deciwid_ / DECIWID_)
* Nonce verification on every $_GET / $_POST handler, with wp_unslash + sanitize_key / sanitize_text_field
* No direct database queries — all uninstall cleanup uses the WordPress API
* Top-level variables in uninstall.php carry the plugin prefix
* Complete External Services documentation for all 6 outbound endpoints

(Supersedes 1.0.x.)

= 1.0.0 =
* Initial release
* Shortcode and Gutenberg block support
* 3-step setup wizard with explicit consent
* Category browser with search
* Light, dark, and auto themes
* Graceful fallback when server is unreachable
* Full internationalization support
* Uninstall cleanup
