XTAL Search for WooCommerce

Description

XTAL Search connects WooCommerce to the hosted XTAL Search service. It syncs your catalog and ranks product results for natural-language searches while continuing to use your theme’s WooCommerce templates.

Features:

• Natural-language search – Handles queries such as “comfortable shoes for running”
• Catalog sync – Sends product changes to XTAL as they are published
• Theme-native results – Uses your existing WooCommerce product templates
• Native fallback – Uses WooCommerce search when the XTAL API is unavailable
• Safe rollout – Enable or disable XTAL at any time. XTAL can run a rollout test on your store: a set share of visitors (for example half) sees XTAL Search while the rest keep the store’s built-in search, and search, click, add-to-cart, and order events are reported for both groups so the two can be compared before you commit. The share in use is shown on the settings page while a test runs.

How It Works:

1. Install and activate the plugin.
2. In the plugin settings, open the signup link next to API Key. The link carries this installation’s random site ID so XTAL creates the correct store and collection.
3. Complete signup and follow the emailed invite to generate and copy your API key.
4. Paste the key, enable XTAL Search, and save the settings.
5. Email [email protected] when the status panel asks you to activate the account.
6. After XTAL confirms activation, run the first catalog sync.
7. Product search pages use XTAL’s ranking and your theme’s WooCommerce templates.

External Service Connection

This plugin connects to the XTAL Search service at api2.xtalsearch.com. Activating the plugin alone does not contact XTAL. Opening the account signup link sends a random installation identifier (site_uuid) and the value platform=woocommerce to XTAL. Saving an API key sends the key to XTAL for validation and connection status. When XTAL Search is enabled, the plugin fetches its search configuration from XTAL about once a minute (sending only the API key) and can send the service data listed below.

Data transmitted to xtalsearch.com:

• Product information (titles, descriptions, prices, images, SKUs, categories, tags, brand, variants, stock status, and product page links)
• Product dimensions and weight, when set on the product, with their unit (for example “15.75 x 9.75 x 9.75 in”)
• Every product attribute (taxonomy and custom, shown or hidden on the product page) as a label and its value(s)
• Any additional product field you list under Extra fields to send to XTAL in the plugin settings (a custom field or an attribute/taxonomy value from that product), sent under the name you listed
• The values of any fields you list under Fields customers search as codes in the plugin settings, sent as SKUs so a shopper who types the exact code gets an exact match
• The XTAL API key, used to authenticate the store
• A random WordPress installation identifier (site_uuid), used during signup to create the correct store and collection
• Search queries entered by customers on your store
• Search result interactions, including product clicks, result positions, and add-to-cart actions
• Completed order events used for search attribution: order ID, total, currency, line items, and the searches attributed to those items
• A pseudonymous session identifier stored in the xtal_sid cookie, used to connect searches with later clicks or purchases
• A pseudonymous visitor identifier stored in the _xtal_vid cookie, used to keep a visitor on the same search variant during a rollout test
• During a rollout test, the test identifier and which search variant the visitor saw, on search, click, add-to-cart and order events (order events carry the order ID, total, and currency)
• Your web server’s IP address, which XTAL sees on every request (for rate limiting and abuse prevention)

Shoppers’ browsers never contact XTAL. The storefront script sends search, click, and add-to-cart events to your own site, which forwards them to XTAL with your API key. Order events are sent from your site’s server the same way. Search queries and Load More requests also go through your site.

The plugin does not send customer names, email addresses, postal addresses, payment details, IP addresses of shoppers, or WordPress account data. Your server’s IP address is processed transiently for rate limiting and abuse prevention and is not stored.

Cookies and browser storage set on your storefront:

• xtal_sid (cookie, 30 days): a random session identifier, set by the storefront script, used to connect searches with later clicks or purchases. Not linked to a customer account.
• _xtal_vid (cookie, 30 days, renewed on each visit): a random visitor identifier, set by the plugin on storefront pages whenever XTAL Search is enabled, used to keep a visitor in the same search variant for the length of a rollout test. Not linked to a customer account.
• xtal:exposed (browser local storage): the current test identifier and session identifier, written once a visitor’s session has been reported as part of a rollout test so it is not reported twice from another tab.
• xtal_recent_search and xtal_cart_attribution (browser session storage, cleared when the tab closes): the most recent XTAL search in this tab and which of its results were added to the cart, used to connect purchases with the search that led to them.

While XTAL Search is enabled, search, click, add-to-cart, and order events are also reported for visitors who see the store’s built-in search during a rollout test, so the two groups can be compared. Disabling XTAL Search stops catalog syncs, takes your store out of any rollout test (every visitor sees the store’s built-in search), stops all storefront search, click, add-to-cart, and order events, and sets no cookies. Saving an API key still performs a connection check.

Pricing:

XTAL Search is a paid hosted service. Start with the signup link next to API Key in the plugin settings, then follow the emailed invite to generate your key. Paste the key, enable XTAL Search, and save; then email [email protected] to activate your store. See xtalsearch.com/pricing for current rates.

• Product Terms
• Privacy Policy

Support

Email [email protected] or visit our Help Center.

Privacy

When XTAL Search is enabled, the plugin sends product data and storefront search queries to xtalsearch.com. It also sends product clicks, result positions, add-to-cart actions, and completed order events containing order ID, total, currency, and line items. These events measure search attribution. During a rollout test, these events also carry the test identifier and which search variant the visitor saw, and they are reported for visitors who see the store’s built-in search as well as for visitors who see XTAL Search.

Events use two random identifiers: a session identifier stored in the xtal_sid cookie and a visitor identifier stored in the _xtal_vid cookie, each kept for 30 days. The browser’s local storage holds xtal:exposed (the current test and session identifiers) and its session storage holds xtal_recent_search and xtal_cart_attribution (the most recent search in the tab and the results added to the cart from it). None of these is linked to a customer account. Shoppers’ browsers never contact XTAL: events go to your own site, which forwards them to XTAL with your API key. The plugin does not send customer names, email addresses, postal addresses, payment details, shoppers’ IP addresses, or WordPress account data. Your server’s IP address is processed transiently for rate limiting and abuse prevention and is not stored.

For detailed information about data handling, please see:
* XTAL Search Privacy Policy
* Product Terms

The plugin registers privacy policy content with WordPress, which you can view and include in your site’s privacy policy at Settings → Privacy.

Technical details