=== SG5 InsightHub ===
Contributors: sg5biz
Tags: search, woocommerce, analytics, ai, abandoned cart
Requires at least: 6.0
Tested up to: 7.1
Stable tag: 2.44.0
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI-powered search, search analytics, chat, reviews and abandoned-cart recovery for WordPress and WooCommerce, driven by the InsightHub engine.

== Description ==

SG5 InsightHub connects your WordPress or WooCommerce site to the InsightHub engine and upgrades your on-site search with AI-powered matching, typo correction, synonyms and relevance ranking — while giving you a full picture of what your visitors are actually searching for.

= Search =

* **Three refinement modes** — *Off* (analytics only), *Refine* (the engine steps in only when native WordPress search finds nothing) and *Replace* (the engine ranks and returns every search result).
* **Typo correction and synonyms** — a zero-result search is retried with the engine's corrected term or synonym, with a clear "showing results for…" notice.
* **Products and content together** — products, variations, posts and pages are matched and interleaved by true relevance.
* **Works with your theme** — supports WooCommerce layered-nav filtering and sorting, and routes search requests through the standard results page so refinement and analytics apply consistently.

= Analytics =

* Log every search with its result count, the products and content shown, and whether the engine recovered a search that would otherwise have returned nothing.
* Optional visitor and customer attribution for search analytics, fully consent-gated (WP Consent API compatible).

= WooCommerce extras (all opt-in, off by default) =

* **Order tracking** — push completed orders to the engine for search-to-purchase analytics.
* **Abandoned-cart capture and recovery** — capture carts (with checkout consent), send recovery emails from the engine, and restore carts via a one-click link.
* **Reviews slider** — show your latest product reviews anywhere with the `[sg5ih_reviews]` shortcode.

= Chat widget =

Optionally embed the InsightHub chat widget, which can answer shopper questions and look up their orders (opt-in).

= Privacy =

The plugin integrates with the WordPress privacy tools: personal data collected through abandoned-cart capture is included in Tools → Export Personal Data and Tools → Erase Personal Data, and suggested privacy-policy text is provided. Customer identity fields are only ever sent when you enable the corresponding toggle.

For analytics — search logging and abandoned-cart capture — the anonymous visitor id is only used after `statistics` consent when a consent plugin is active. The form-conversion feature is different: it is functional rather than analytical, so when a form-conversion integration is enabled the `ih_vid` cookie is set for every visitor of a page carrying such a form. It holds a random first-party identifier and no profile, and exists only to link a lead the visitor deliberately submitted to the visit it came from.

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/sg5-insighthub`, or install through the WordPress plugins screen.
2. Activate the plugin through the *Plugins* screen.
3. Go to *InsightHub* in the admin menu and follow the setup wizard to connect your InsightHub account and API key.
4. Choose your search refinement mode and enable the optional features (tracking, chat widget, order tracking, abandoned-cart capture) you want.

== Frequently Asked Questions ==

= Do I need an account? =

Yes. The search, analytics, chat and cart-recovery features are powered by the InsightHub engine, so you need an InsightHub account and API key from SG5 Digital Solutions.

= Does it work without WooCommerce? =

Yes. Search refinement and analytics work on any WordPress site (posts and pages). The order, cart and reviews features activate only when WooCommerce is installed.

= Is it GDPR-friendly? =

Yes. All personal-data features are off by default and individually opt-in. The plugin registers with the WP Consent API and gates its analytics — search logging and cart capture — on `statistics` consent, and hooks abandoned-cart data into the WordPress personal-data export and erase tools. The form-conversion integrations are functional rather than analytical: when enabled they set an anonymous first-party id so a submitted lead can be tied to its visit.

= What happens if the engine is unreachable? =

Search falls back to native WordPress search. Errors are logged to the PHP error log; shoppers just see standard results.

== External services ==

This plugin connects to the InsightHub service, a cloud service operated by SG5 Digital Solutions (Vienna, Austria), to provide AI-powered search, search analytics, chat, reviews, lead capture and abandoned-cart recovery. The plugin cannot provide these features without it: the matching, ranking and AI responses are produced by the service, not in WordPress. An InsightHub account and API key are required.

All requests go to insighthub-gateway.sg5host.com over HTTPS. Nothing is transmitted until you enter an API key and switch on the feature that sends it — every feature below is off by default.

What is sent, and when:

* Connecting your site (POST /v2/onboard, GET /v2/widget) — your site URL, site name and administrator email address, sent once when you connect the plugin to an InsightHub account and whenever it verifies the API key.
* Search (POST /v2/search) — sent on a front-end search when Search Tracking or Search Refinement is on: the search term, the number of results, a snapshot of the matching products and content, the page number, and the visitor's IP address. An anonymous visitor id, or a logged-in customer's id, name and email address, are included only when the corresponding settings and visitor consent allow.
* Content sync (POST /v2/documents/sync, POST /v2/products/sync) — sent when you save or delete a post, page or product while sync is on: its title, URL, content, and for products the price, stock, attributes and variations.
* Orders (POST /v2/orders) — sent at checkout when order tracking is on: order total, currency, line items, and the customer's name, email address and order id.
* Abandoned carts (POST/DELETE /v2/abandoned-carts, GET /v2/abandoned-carts/resolve) — sent when cart capture is on and the shopper has consented: cart contents and the shopper's email address, so the service can send a recovery email. The resolve call exchanges a token from that email for the saved cart.
* Post-purchase survey (POST /v2/post-purchase/answer) — sent when a shopper answers the survey banner: their answer and the related order id.
* Form leads (POST /v2/leads) — sent when a visitor submits a Bricks or Elementor form carrying the InsightHub action: the fields you mapped, which typically include the name, email address, phone number and message, plus the page and campaign the submission came from.
* Campaign visits (POST /v1/track) — sent on page load for pages carrying such a form: an anonymous visitor id, the page URL, the referring URL and any UTM parameters.
* Reviews (GET /v1/reviews/public/) — sent when the [sg5ih_reviews] shortcode renders: your public widget id, to retrieve approved reviews for display.
* Chat widget (widget.js) — when the widget is on, its script is loaded from the service and shopper messages are processed by it.

About the service, its terms and its privacy policy:

* InsightHub product information: https://www.sg5.biz/en/products/insighthub/
* Terms and conditions: https://www.sg5.biz/en/products/insighthub/legal/agb/
* Privacy policy: https://www.sg5.biz/en/products/insighthub/legal/datenschutz/
* Data processing agreement (Art. 28 GDPR): https://www.sg5.biz/en/products/insighthub/legal/dpa/
* Legal notice: https://www.sg5.biz/en/products/insighthub/legal/impressum/

== Changelog ==

= 2.44.0 =
* All of the plugin's internal names now use the sg5ih prefix, so they cannot collide with other plugins. This resets the plugin's settings: after updating, reconnect your API key and switch your features back on.
* The external InsightHub service is now documented in full in the readme — what is sent, when, and under which conditions — with links to the terms and privacy policy.
* Search log de-duplication now runs only where a persistent object cache is available, so search terms can no longer add rows to the options table.

= 2.43.0 =
* Bricks submits radio and checkbox fields the same way, so a radio answer is sent as its value rather than a one-item list. Checkboxes and multi-selects still send a list.
* Form leads now send their extra fields as custom_fields as well as inside raw_data, so they land in the lead's own custom fields in InsightHub. Values keep their type: a number stays a number, a multi-select becomes a list.
* If InsightHub rejects the custom fields, the lead is still recorded — it is resent without them and the reason is written to the activity log, so a mapping mistake costs the mapping rather than the lead.

= 2.42.1 =
* PMS facility and amenity values are HTML-entity-decoded before syncing (no more &amp;amp; in chat answers).

= 2.42.0 =
* Room/tour/service products sync their SG5 PMS facts as attributes: the facility fields (number of guests, beds, bathrooms, room size, ...), a normalized guests value, the rooms count, and the amenity terms — so the AI chat answers capacity and amenity questions from structured data.

= 2.41.0 =
* Product sync sends the WooCommerce product type (simple, variable, or custom types like the SG5 PMS room/tour/service) so the AI chat can answer by booking type. Needs engine 2.218.5+.

= 2.40.6 =
* Fix: equal left/right spacing for the dialog on phones — the overlay is placed in document coordinates (visualViewport.pageLeft/pageTop), sidestepping cross-browser position:fixed ambiguity on horizontally overflowing pages.

= 2.40.5 =
* Fix: the dialog banner centers on the visible screen even when the page content overflows the phone width (overlay is pinned to the visual viewport).

= 2.40.4 =
* Fix: the dialog banner centers correctly on every theme — the overlay re-parents to <body> so transformed theme wrappers can no longer shift position:fixed off-center.

= 2.40.3 =
* Fix: banner Yes/No buttons stay side by side on phones — armored against host-theme button styles (width:100%/margins stacked the pair).

= 2.40.2 =
* Fix: the dialog close button is armored against host-theme button styles (backgrounds/padding leaked over the x on some themes).

= 2.40.1 =
* Fix: coding-standards compliance (a docblock displaced by the v2.40.0 settings additions). No behavior change.

= 2.40.0 =
* New: post-purchase banner presentation — banner colors inherit the selected survey's design from InsightHub (button = primary, border/title = accent) with optional per-shop override fields, a Banner display mode (Inline in the page flow, or Dialog as a centered overlay with close button), and a restyled card: full rounded accent border instead of the green left bar.

= 2.39.0 =
* New: the five post-purchase banner texts (title, question, Yes/No buttons, thank-you line) are editable on the Surveys tab — empty fields keep the bundled German/English default.

= 2.38.0 =
* New: enable/disable switch for the post-purchase survey banner on the Surveys tab. Opt-in — off by default (GDPR/WP.org house policy); the banner renders only when this switch, order tracking and the InsightHub app setting are all on.

= 2.37.2 =
* Fix: the post-purchase survey pointer note rendered inside the order-tracking toggle and overlaid the switch column. It now lives on its own Surveys settings tab (informational — configuration stays in the InsightHub app).
* Tweak: Bricks and Elementor form conversions moved from the General tab to their own Form Conversions tab.

= 2.37.1 =
* Fix: WordPress-Coding-Standards compliance for the post-purchase banner (docblocks, house filter prefix `sg5ih_pp_banner_texts`, justified embed-tag ignore). No behavior change.

= 2.37.0 =
* New: post-purchase survey banner on the WooCommerce thank-you page. Asks the customer for feedback after checkout (YES opens the survey as a popup with their email prefilled, NO dismisses); the InsightHub engine throttles re-asks per customer (configurable). Configure in InsightHub → Settings → Surveys; requires Order tracking to be ON. No data is stored in WordPress.

= 2.36.0 =
* Every feature that contacts the InsightHub service is now off until you switch it on. Search tracking, search refinement, the chat widget and both sync options previously started working as soon as the plugin was activated; on a new install they now wait for you. Existing sites keep whatever they already have saved.
* Search result caching is now used only on sites with a persistent object cache, so search terms can no longer cause the options table to grow.
* Hardened input handling on the order-lookup, customer-orders and sync endpoints, and on WooCommerce attribute filters.
* The search notice shortcode escapes its output explicitly.
* Internal storage keys renamed for a consistent prefix. The browser debug switch is now ?sg5ih_debug=1.
* Every PHP file now blocks direct access.

= 2.35.4 =
* Fix: form submissions now reach InsightHub. They were being sent to the campaign-conversion endpoint, which accepted them and returned success but never created a lead, so nothing appeared in the dashboard. They now go to the leads endpoint, with the name, email, phone and message as their own fields and the full submission kept alongside them.
* Each submission carries its own identifier, so a resend is recognised as the same lead rather than creating a duplicate.
* Where the form was submitted from a URL carrying campaign parameters, the source and campaign are recorded with the lead.

= 2.35.1 =
* Fixed the close button on the exit-intent cart popup being pulled out of position by theme styles.
* The suggested privacy-policy text for abandoned-cart capture now follows the site language. English and Indonesian sites get English and Indonesian wording; German sites (including Austria and Switzerland) are unchanged.

= 2.35.0 =
* Form conversions no longer depend on consent. The feature is functional rather than analytical — the visitor id links a lead someone deliberately submitted to the visit it came from — so the id is now always available and no conversion is lost to a missing or declined consent signal.
* Search logging and abandoned-cart capture are unchanged: those are analytics and keep their `statistics` consent gates.

= 2.34.5 =
* Fix: saving an Elementor page with the InsightHub action selected raised a fatal error.

= 2.34.4 =
* Fix: the Elementor Lead details pickers now list the form's fields. Every one showed only "- None -".
* Fix: the last row of Extra fields can now be removed.

= 2.34.3 =
* Fix: the InsightHub action now actually appears in Elementor's Actions After Submit. It was registered a moment too late in the page lifecycle, after Elementor had already collected its form actions.

= 2.34.2 =
* The Bricks and Elementor form toggles are always visible on the settings page. When that builder isn't installed the toggle shows off and is disabled, with a note saying what's missing, instead of the row disappearing entirely.

= 2.34.0 =
* New: Elementor Pro form integration. Turn on *Elementor form conversions* and an **InsightHub** action appears under the form widget's Actions After Submit, where you can map form fields to InsightHub lead details and any extra keys you want. A page carrying such a form records a campaign visit, and each submission is sent as a conversion against it — the same flow as the Bricks integration.

= 2.33.0 =
* Lead details are now sent inside conversion_data, where InsightHub reads them, as well as top-level for the three it indexes.
* New: a Message field picker, alongside Name, Email and Phone — the four keys InsightHub recognises by name.
* The Extra fields mapping is now clearly for everything else, and says so.
* Quieter logging: one line per conversion, and a field is only reported when something is actually wrong with it.

= 2.30.1 =
* Initial WordPress.org release.
* AI search refinement with off/refine/replace modes, search analytics, chat widget, reviews slider, order tracking and abandoned-cart recovery.
