=== Aqurate Connect for WooCommerce ===
Contributors: 3ds
Tags: woocommerce, recommendations, personalization, cross-sell, upsell
Requires at least: 5.8
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect your WooCommerce store to Aqurate: automated data sync, Aqurate Pixel tracking and personalized product recommendation touchpoints.

== Description ==

Aqurate Connect for WooCommerce integrates your shop with [Aqurate](https://aqurate.ai/), the e-commerce personalization platform. Enter your API key once, the plugin takes care of the rest.

**Connection**

Link your store to Aqurate with your API key (used for data sync and recommendations) and your Client ID (used by the Aqurate Pixel). A one-click connection test tells you immediately whether your credentials are valid.

**Data sync**

The plugin pushes your catalog and order data to Aqurate on a schedule you choose: hourly, every 6 hours, every 12 hours, or daily. Synced tables:

* Categories (full category tree)
* Items (products and their variations: name, price, image, URL, SKU, description, brand, currency)
* Item categories (product-to-category assignments)
* Stock (per product/variation availability)
* Orders (configurable history lookback, incremental after the initial backfill)
* Line items (per-order products, quantities and unit prices)
* Customers (billing email, only when you explicitly opt in)

Sync runs in the background via Action Scheduler (with a WP-Cron fallback), respects Aqurate's rate limits, and can also be triggered manually from the dashboard.

**Aqurate Pixel**

When enabled, the pixel tracks four events on your storefront and sends them directly from the visitor's browser to Aqurate's tracker:

* Product view
* Add to cart (product pages and AJAX add-to-cart on archives)
* Purchase (order confirmation page, fired once per order)
* Recommendation click (clicks on products inside Aqurate touchpoints)

**Recommendation touchpoints**

Create unlimited touchpoints in the admin (Aqurate > Personalize > Touchpoints) and place them on the product page, cart page, shop archive, or anywhere via shortcode. Products are rendered with your theme's own product card template, so touchpoints match your store's look automatically. Available recommendation types:

* You may also like (similar)
* Frequently bought together (cross_sell)
* Upsell (up_sell)
* Alternative products (substitutes)
* Popular in same category (bestseller_in_category)
* Popular now (bestseller)
* New in store (new_in)
* Popular in category (category_bestseller)
* New in category (category_new)
* Recommended for you (user_recs)
* Recently viewed (recently_viewed)
* Buy again (recently_bought)

**Shortcodes**

Render a saved touchpoint by its ID:

`[aqurate_touchpoint id="1"]`

Render an ad-hoc recommendation block:

`[aqurate_recommendations type="similar" count="4" columns="4" title="You may also like" product_id="" category_id=""]`

Attributes for `[aqurate_recommendations]`:

* `type`: one of the recommendation type keys listed above (default `similar`)
* `count`: number of products to show, 1–12 (default 4)
* `columns`: grid columns, 2–6 (default 4)
* `title`: heading text; defaults to the type's standard label
* `product_id`: product context for product-based types; auto-detected on product pages
* `category_id`: category context for category-based types; auto-detected on category archives

**Usage data (opt-in)**

The plugin asks once, on its own admin pages, whether it may send 3DS (the plugin's developer) a short daily report. It sends nothing until you click Allow, and you can switch it off any time under Aqurate > Integration > Usage data. See External services below for exactly what is sent.

== Installation ==

1. Upload the `aqurate-connect` folder to `/wp-content/plugins/`, or install the ZIP via Plugins > Add New > Upload Plugin.
2. Activate **Aqurate Connect for WooCommerce** through the Plugins screen. WooCommerce 6.0+ must be active.
3. Get your API key at [app.aqurate.ai](https://app.aqurate.ai/account/api-keys). The key needs these scopes: `write:input_tables`, `read:item_recs`, `read:user_recs`.
4. Copy your Aqurate Client ID from your Aqurate account.
5. Go to **Aqurate > Dashboard**, paste the API key and Client ID, click **Save**, then **Test connection**.
6. Enable data sync and the pixel, pick a sync frequency, and optionally click **Sync now** to start the initial backfill immediately.
7. Create your first touchpoint under **Aqurate > Personalize > Touchpoints**.

== Frequently Asked Questions ==

= Does the plugin respect Aqurate's API rate limits? =

Yes. Pushes are chunked to at most 1,000 rows per request, batches are staggered a few seconds apart, and the sync never exceeds Aqurate's limit of 1 request per second. Recommendation responses are cached in transients (TTL configurable, default 6 hours) so storefront traffic does not hammer the API.

= Is the plugin compatible with HPOS (High-Performance Order Storage)? =

Yes. The plugin declares HPOS compatibility and reads orders exclusively through the WooCommerce CRUD APIs (`wc_get_orders()` / `WC_Order`), never through direct post meta.

= Exactly what data is synced to Aqurate? =

Categories, products and variations (name, price, image URL, permalink, SKU, short description, brand, currency, active flag), product-to-category assignments, stock availability, orders (ID, anonymized customer reference, date, status) and order line items (product, quantity, unit price). Customer emails are synced **only** if you enable the separate "Sync customers" opt-in.

= What about customer privacy? =

By default no personal data is pushed. Guest orders are keyed by a hash of the billing email, not the email itself. Only when you explicitly enable the customer sync opt-in does the plugin push a customers table containing billing email addresses, enable it only if this is covered by your privacy policy.

= What happens if my API key is missing or invalid? =

Nothing breaks. Touchpoints simply render nothing, the pixel stays silent unless a Client ID is set, and sync runs are skipped. The Integration page connection note shows the error.

= Does deactivating or uninstalling leave anything behind? =

Deactivation unschedules all background sync actions. Uninstalling deletes every plugin option, cached transient and scheduled action.

= Does the plugin send data to anyone besides Aqurate? =

Only if you opt in to usage data. Then the plugin sends 3DS a daily report about the plugin itself (versions, enabled features, connection status) plus a notice when it is deactivated, reactivated or uninstalled. It never sends customer, order or product data, or your API key. Turning the option off sends one last notice and deletes the site's telemetry ID.

== External services ==

**Aqurate API** (`https://api.aqurate.ai`). Data sync pushes your catalog and order data (see the FAQ for the exact fields), and touchpoints fetch recommendations. Requests start once you add an Aqurate API key. Provided by Aqurate, [aqurate.ai](https://aqurate.ai/).

**Aqurate tracker** (`https://tracker.aqurate.ai`). When the pixel is enabled, shoppers' browsers send product views, add-to-cart events, purchases and recommendation clicks to Aqurate. Provided by Aqurate, [aqurate.ai](https://aqurate.ai/).

**Aqurate update server** (`https://cdn.aqurate.ai`). WordPress checks a version file on the Aqurate CDN when it looks for plugin updates (at most every 6 hours) and downloads the new version from there when you update. The request sends no site data. Provided by Aqurate, [aqurate.ai](https://aqurate.ai/).

**3DS usage data** (`https://aq.3ds.gr`). Off until a site admin opts in. Then the plugin sends a daily report and a notice when it is deactivated, reactivated or uninstalled, or when usage data is switched off. Each report contains the site address, the plugin, WordPress, WooCommerce and PHP versions, the site language, whether the site is a multisite, the Aqurate connection status, which plugin features are on, the number of touchpoints and a rough catalog size (for example "100-1k" products). Provided by 3DS, the plugin's developer, [3ds.gr](https://3ds.gr).

== Third-party libraries ==

This plugin bundles [Swiper](https://swiperjs.com) 11.2.10 (MIT license, (c) Vladimir Kharlampidi) for the carousel touchpoint layout. It is served locally from the plugin, no CDN or external requests.

== Changelog ==

= 1.3.0 =
* Updates now come from the Aqurate CDN and show up in Dashboard > Updates and on the Plugins page like any other plugin, including auto-updates and the "View version details" window.

= 1.2.0 =
* Opt-in usage data. A one-time banner on the Aqurate pages asks before anything is sent, and Aqurate > Integration > Usage data turns it on or off. Opted-in sites send a daily report and lifecycle notices (activated, deactivated, uninstalled, opted out) to 3DS. Reports keep going while WooCommerce is inactive.
* New External services section in this readme.

= 1.1.0 =
* Admin restructured into three pages: Integration, Personalize and Search. The old Reports, Widgets and Settings pages redirect into them.
* New Aqurate Search page with an Overview report of the three essential measurements (Sessions, Orders, Revenue), Top searches and Searches with no results, plus deep links into the Aqurate app.
* New Aqurate Personalize card on Integration with an enable toggle and touchpoint status.
* Widgets renamed to touchpoints throughout. New `[aqurate_touchpoint]` shortcode, `[aqurate_widget]` still works.
* Touchpoint editor is now a fly-in panel; the default recommendation type is Alternative products.
* The Client ID field is gone. It is decoded from the API key, which is a JWT carrying the client id.
* Pixel: the `tv` payload parameter now carries the integrator (`ss-1.0.0-3ds`), and link clicks are captured for both Personalize and Search from any `aqurate` class or query parameter.
* Multi-language: only default-language products, variations and categories are synced, order line items map back to the default language, and recommendations render the translation for the visitor's language (WPML and Polylang).
* Restyled to the Aqurate design system.

= 1.0.0 =
* Initial release: Aqurate connection, scheduled data sync (categories, items, item categories, stock, orders, line items, opt-in customers), Aqurate Pixel (view_item, add_to_cart, purchase, recommendation clicks), recommendation touchpoints with locations and shortcodes.
