內容簡介
SmartMatch Search 是一款提升 WordPress 搜尋功能的外掛，能夠根據使用者的意圖提供最相關的搜尋結果，並將最佳匹配的文章顯示在搜尋結果的最上方，改善使用者體驗。
【主要功能】
• 根據意圖提供最佳匹配結果
• 支援多語言搜尋
• 過濾無關內容，提升搜尋精準度
• 保留原有搜尋結果不變
• 整合 Burst Statistics 確保真實訪客數據
外掛標籤
開發者團隊
原文外掛簡介
SmartMatch Search keeps the normal WordPress search results intact and surfaces
the most semantically relevant post(s) on top as a “Best match” suggestion.
Search that understands intent
Classic WordPress search matches keywords: when the words in the query do not
literally appear in a post, the visitor gets “nothing found” — even when your
site has exactly the right page. SmartMatch Search judges meaning instead, so
visitors can search the way they actually talk:
“page where I can find my orders” surfaces your Order history page,
even though none of those words appear in its title.
“how do I get my money back” finds your Returns & refunds policy —
no overlap in wording needed.
“wo finde ich meine rechnung” (German) still lands on your Invoices
page: the model matches meaning across languages, so visitors searching in
their own language get the right result.
“cancel my subscription” surfaces Manage your membership, instead of
every post that happens to contain the word “cancel”.
“what time are you open on saturday” finds your Contact & visiting
information page.
And it filters as well as it finds: a query like “burst viewer” will not match
a post just because the word “burst” appears somewhere — only posts that are
genuinely about the topic are suggested. The native results stay untouched
below the suggestion, so search never gets worse, only better.
Why SmartMatch Search connects to Burst
The Burst Statistics integration exists for two reasons:
Real visitors only. Every AI search is a paid model call, so you only
want to spend it on real people. Burst already knows which visits are
validated human visits — its tracking filters out bots, crawlers and spam
before a visit is recorded, in both cookie and cookieless mode. SmartMatch
Search runs the AI only for those validated visits; bots silently get the
normal search results at zero AI cost.
Searches land in your statistics. Searches run through the normal
WordPress search request, so they show up directly in Burst’s Engagement
tab. You see what visitors are looking for — and where your content falls
short — in the same dashboard you already use.
How it works
SmartMatch Search is a thin integration layer between two plugins:
AI (WordPress\AI) — supplies the configured provider and text model.
Provider/model selection is delegated entirely to the AI plugin via
WordPress\AI\get_ai_service() and the wpai_preferred_text_models filter.
Burst Statistics / Burst Pro — supplies visit validation. The AI search
only runs for a validated Burst visit (a uid with a recorded hit in the
last 30 minutes), which excludes bots. Works in both cookie mode
(burst_uid cookie) and cookieless mode (session fingerprint).
How it works on a search request (?s=...):
The visitor must be a validated Burst visit, otherwise the native results
are shown untouched.
Public, published posts of public post types are collected (title +
excerpt, capped, freshest first) and sent to the model with the search
term.
The model returns only the genuinely relevant post IDs, ranked.
Those posts are merged into the main query’s result array itself (via the
the_posts filter): prepended above the native matches, de-duplicated, and
optionally tagged with a configurable badge (via the_title). Because the
change happens at the data layer, placement does not depend on how the theme
renders the loop — it works the same for classic templates and block themes.
When the native search found nothing, the suggestions become the results so
the page is not empty.
Results are cached per search term (transient), invalidated when the
candidate set changes. Suggestions appear on the first results page only.
If the AI is unavailable, errors, or finds nothing relevant, nothing is added
and the normal results (or “nothing found”) are displayed as usual.
Settings
The plugin adds a “SmartMatch Search” item to the Burst settings menu
(Statistics → Settings → SmartMatch Search), with the options stored in the
Burst settings store:
Daily search budget (default 50, seeded on activation) — the maximum
number of AI searches per day. Only actual model calls count (cached
rankings are free); once the budget is spent, visitors get the normal
search results until the site’s next midnight.
Posts sent to the AI (default 200) — how many posts (most recently
updated first) are sent to the model as candidates per search. More posts
improve coverage on large sites, but raise the token cost per search.
Excerpt length in words (default 40) — how many words of each post are
included in the prompt. Longer excerpts give the model more context to
judge relevance, but increase token usage per search.
Badge for the suggested result (default empty) — text shown before the
title of the suggested result, e.g. “(Best match)”, so visitors see why it
is on top. Leave empty to show the suggestion without a badge.
Prompt customization — extra instructions appended to the system
instruction sent to the model, e.g. to prioritize certain content or set a
tie-breaking rule.
Editing the prompt customization or excerpt length invalidates previously
cached rankings, so changes take effect immediately.
Filters
smartmatch_search_enabled (bool, WP_Query) — disable per query.
smartmatch_search_is_validated_visit (bool, uid) — override the visit gate.
smartmatch_search_post_types (string[]) — post types to search.
smartmatch_search_candidate_limit (int) — override the configured number
of candidate posts sent to the model.
smartmatch_search_excerpt_words (int) — override the configured excerpt
length in words.
smartmatch_search_cache_ttl (int seconds, default 1 hour) — ranking cache.
smartmatch_search_suggestion_count (int, default 1) — how many to surface.
smartmatch_search_badge_label (string) — override the configured badge
text; an empty string disables the badge.
smartmatch_search_badge_html (string) — replace the rendered badge markup;
an empty string suppresses the badge. The result is passed through
wp_kses_post() before it is output.
smartmatch_search_rate_limit (int, default 5) — AI searches per IP / window.
smartmatch_search_rate_window (int seconds, default 5 min) — the window.
smartmatch_search_daily_budget (int) — override the configured daily budget.
smartmatch_search_debug (bool) — toggle debug logging (see Testing).
wpai_preferred_text_models (from the AI plugin) — choose provider/model.
smartmatch_search_ranked (action: ids, term, WP_Query) — observe results.
smartmatch_search_rate_limited (action: term, WP_Query) — fired when an IP
exceeds the limit and falls back to normal search.
smartmatch_search_budget_exceeded (action: term) — fired when an AI search
is skipped because the daily budget is spent.
Testing / diagnostics
Define SMARTMATCH_SEARCH_BYPASS_GATES as true (e.g. in wp-config.php) to disable
the visitor gates — the Burst uid validation and the per-IP rate limit — so AI
search runs without a tracked Burst visit. Useful for local testing or to verify
a production setup where no validated visit is available. It does NOT bypass the
dependency, main-query or relevance checks. Leave it undefined in normal use.
define( 'SMARTMATCH_SEARCH_BYPASS_GATES', true );
Define SMARTMATCH_SEARCH_DEBUG as true to log every point where AI search bails
out silently to the PHP error log (prefixed “[SmartMatch Search]”): missing
dependencies, no validated visit, rate limit hit, no AI credentials, provider
unsupported, SDK exception, unparseable response, nothing relevant, or the IDs
finally selected. When the constant is undefined, logging follows WP_DEBUG; the
smartmatch_search_debug filter can override it. Logging stays off in normal use.
define( 'SMARTMATCH_SEARCH_DEBUG', true );
Rate limiting
To curb abuse and AI cost, each IP may run at most 5 AI searches per rolling
5-minute window (both filterable). Beyond that, the request falls back to normal
WordPress search. Only searches that trigger an actual model call count against
the limit: cached rankings are served freely. The visitor IP is resolved through
Burst’s own proxy-aware detector (Burst\Frontend\Ip\Ip::get_ip_address()) and
is only stored hashed.
Requirements
Both the “AI” plugin and Burst Statistics (free) or Burst Pro must be active.
The AI plugin needs a configured provider with valid credentials.
The AI plugin is declared through the WordPress “Requires Plugins” header, so
WordPress itself enforces it on activation. The Burst requirement is enforced
at runtime instead (with an admin notice when missing): that header is an
AND-list of wordpress.org slugs, so it cannot express “Burst free OR Burst
Pro”, and Burst Pro is not distributed on wordpress.org. The plugin simply
stays inactive (and tells you why) until both are present.
External services
SmartMatch Search does not connect to any service of its own and sends no data
to Burst or SmartMatch servers. When a search qualifies for AI ranking, the
search term and the candidate posts (post ID, post type, title and a short
excerpt of public, published content) are sent to the AI provider that you
yourself configured in the WordPress “AI” plugin — which provider that is
depends entirely on your configuration there, and its terms of service and
privacy policy apply to those requests. This happens only for validated human
visits, within the configured daily budget, and only when the ranking is not
already cached. No other data (no IP addresses, no visitor identifiers) is
included in these requests.
