XTAL Search for WooCommerce -- WordPress 插件

开发者	tfpk
更新时间	2026年10月13日 01:38
PHP版本:	7.4 及以上
WordPress版本:	7.1
版权:	GPLv2 or later
版权网址:	版权信息

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:

Install and activate the plugin.
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.
Complete signup and follow the emailed invite to generate and copy your API key.
Paste the key, enable XTAL Search, and save the settings.
Email hello@xtalsearch.com when the status panel asks you to activate the account.
After XTAL confirms activation, run the first catalog sync.
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, your site's domain name, and the installation identifier to XTAL to validate the key and connect it to this website. 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
Your site's domain name (for example shop.example.com) and the installation identifier, sent with every request so each API key works on one website only
During a full sync, a random identifier for that sync and the number of products on your site, so products no longer on the site can leave search
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_attr (cookie, 2 days): for up to 20 products the shopper opened or added to the cart from XTAL search results, the search identifier and query that found each one. Set by the storefront script and read only by your own site, which records the search on the cart line so the order can say which search found each product. 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 hello@xtalsearch.com to activate your store. See xtalsearch.com/pricing for current rates.

1.2.2

Orders now record which search found each product. The plugin used to save that in the WooCommerce session through a REST route, where WooCommerce never loads the session, so every order arrived without it. The search now travels with the add-to-cart request in a new xtal_attr cookie and is stored on the cart line, then on the order line
New xtal_attr cookie (2 days, read only by your own site): the search identifier and query for up to 20 products the shopper opened or added to the cart from XTAL results
"Open XTAL Admin" button on the settings page signs the store in to XTAL Admin in one click, once XTAL recognises the store's key

1.2.1

Load More works on themes whose product grid isn't a list. It previously loaded the next products, added none to the page, and hid itself
Products added by Load More match the first page's layout on themes that set the number of columns from the page's own product loop
Full sync no longer loses a batch of 25 products when one of them sits in two categories with the same name
A sync batch XTAL rejects is logged with the field and reason XTAL gave, instead of "API request failed"

1.2.0

Each install key works on one website. The plugin tells XTAL which site it runs on, and a key already connected to another website shows "This install key is for a different website" with a link to create an account, instead of syncing into the other site's catalog
The first-run screen leads with creating an XTAL account for this website
New "Results per page" setting: XTAL search pages, and each Load More, show this many products. Left blank, they use the page size set in your XTAL account (48 unless changed). WordPress's "Blog pages show at most" no longer applies to search pages
Unpublishing a product, moving it to the trash, or setting its catalog visibility to "Shop only" or "Hidden" takes it out of search results right away. Re-publishing it makes it searchable again right away
A full sync tells XTAL which products the site still has, so products deleted from the site can leave search. A sync that stops partway never takes anything out of search
The settings page shows search as on while a store that has synced before re-syncs, and no longer shows "ready" before XTAL has switched the account on
A failed sync batch waits 1 minute, then 3 minutes, before retrying, so a short outage doesn't use up every retry
A sync batch retried by WooCommerce's scheduled actions no longer queues a second copy of the rest of the sync
Removed the xtal_search_product_payload filter. Product data beyond the standard fields goes through the "Extra fields to send to XTAL" and "Fields customers search as codes" settings

1.1.0

Product sync sends each product's dimensions, weight, and every attribute, including attributes hidden from the product page
New settings: "Extra fields to send to XTAL" sends custom fields you list, and "Fields customers search as codes" lets shoppers find a product by an exact code such as an item number. Saving a change starts a full sync
New xtal_search_product_payload filter lets developers add to the product data sent to XTAL
The search results heading shows a true count: "12 results for ..." when every match fits on the first page, or "First 24 results for ..." when more follow. WooCommerce's "Showing N results" line, which always repeated the page size, is hidden on XTAL results pages
Load More appears only when more results exist, and advances correctly when the store carries only part of its XTAL catalog
The settings page shows how many search results appear per page and links to the setting that controls it
Search, click, and add-to-cart events now go from the shopper's browser to your own site, which forwards them to XTAL with your API key; order events are sent with the key too. Shoppers' browsers no longer contact XTAL
Search pages that fall back to WooCommerce's own search are never page-cached, nginx FastCGI caches included, so XTAL results return as soon as XTAL is available
Rollout tests: XTAL can show XTAL Search to a set share of visitors while the rest keep the store's built-in search; the share in use is shown read-only on the settings page while a test runs
New _xtal_vid cookie (random visitor identifier, 30 days, renewed on each visit) keeps a visitor in the same search variant; new browser storage key xtal:exposed marks a session as already reported
Search, click, add-to-cart, and order events carry the test identifier and which search variant the visitor saw, and are reported for visitors on the store's built-in search during a test
Search results pages skip page caches, nginx FastCGI caches included, while a test runs
The plugin fetches its search configuration from XTAL about once a minute while enabled

1.0.1

WooCommerce's result count now reports the XTAL total ("Showing 1-10 of 40 results") instead of the current page size
Native paged search URLs (?paged=2) render the next slice of XTAL results instead of a 404
Load More resumes after the page that was rendered

1.0.0

Initial release
Semantic product search
Real-time product sync
Fallback to native WooCommerce search
Suggested privacy-policy text for WordPress

XTAL Search for WooCommerce

标签

下载

详情介绍:

安装:

屏幕截图:

升级注意事项:

常见问题:

更新日志: