Angeo AEO Brand Visibility for Magento 2

Measure whether AI assistants actually name your store when a shopper asks them
where to buy something.

The module asks ChatGPT, Claude, Perplexity, Gemini and Groq a set of shopping
questions, reads their answers, and scores how visible your brand is. It repeats
every question several times, so the score comes with a confidence interval
instead of pretending one sample is the truth.

It plugs into angeo/module-aeo-audit
as a live_signal checker, and also runs on its own from the admin panel, cron
or the command line.

Why this exists

Classic SEO tools tell you where you rank on a results page. They tell you
nothing about what a language model says when someone asks it a question. This
module measures that directly: it asks, then reads the answer.

What is measured

Each answer is scored on five signals:

A sixth signal, negative tone, is not weighted. It reduces the earned score
by the configured penalty, because "avoid this shop" is worse than not being
mentioned at all.

On top of the per-answer score the module reports:

• Share of voice — your weight against every tracked competitor in the same
  answer, based on how often you are named and how early.
• Win rate — the share of answers where you are named before every
  competitor.
• Accuracy issues — answers where a model attributes a website you do not
  own to your brand.

Reading the score honestly

Two things decide whether the number means anything.

Grounding. A model answering from memory reflects a training set that is
months old. Nothing you change on your store will move that number this quarter.
A grounded model searches the live web before answering, so it responds to your
work within days. Perplexity is always grounded; ChatGPT, Claude and Gemini can
be, per provider, in the configuration. Groq cannot. If you want a metric that
reacts to what you do, enable grounding.

Sampling. Language models are not deterministic. The same prompt returns
different answers. Every provider and prompt pair is therefore asked N times
(three by default) and reported as a mean with the half-width of its 95%
confidence interval — the ± figure next to the score. A movement smaller than
that margin is noise, and the alert system will not fire on it.

Requirements

• Magento Open Source or Adobe Commerce 2.4.6 – 2.4.8
• PHP 8.2, 8.3 or 8.4
• angeo/module-aeo-audit 3.x or 4.x
• At least one AI provider API key
• A running message queue consumer (or inline run mode, see below)

Installation

composer require angeo/module-aeo-brand-visibility
bin/magento module:enable Angeo_AeoBrandVisibility
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Start the consumer that executes queued audits:

bin/magento queue:consumers:start angeoBrandVisAuditRun

On most installations consumers_runner in app/etc/env.php starts it from
cron automatically. If your platform does not run message queue consumers at
all, set Run Mode to Inline in the configuration; be aware that a full run
then happens inside the admin request and may hit the PHP or gateway timeout.

Configuration

Stores → Configuration → Angeo AEO → Brand Visibility (AI Models)

Almost every setting is available per website and per store view, so a
multi-store installation can measure each brand separately.

General

Set the store category. When it is empty and the catalogue gives nothing
useful, prompts fall back to a generic phrase, and generic phrases are won by
the large marketplaces every time. This single field moves the score more than
any other.

Providers

Each provider has its own group with the same fields: enable, API key (stored
encrypted), model, grounding, max tokens, temperature and timeout.

Model identifiers change often. Pick the closest option, and expect to revisit
the field after a provider release.

Queries

Six built-in prompts, each with its own on/off switch and optional override
text: best stores in category, where to buy, tell me about this brand, product
search, compare with competitors, gift guide. Add your own under Custom
Prompts, one per line, as key: prompt text.

Placeholders: {{brand}}, {{domain}}, {{category}}, {{products}}.

Samples per Query controls how many times each pair is asked. Cost scales
linearly with it; the confidence interval narrows with the square root of it.

Analysis

Phrase matching supports English, Ukrainian, Dutch, German, French and
Spanish. English phrases are always matched in addition to the selected
language, because AI answers mix languages freely.

Extra Top-Level Domains matters for the accuracy check: without nl, de
or co.uk in that field, a wrong country domain attributed to your brand will
not be flagged.

Alerts

An alert fires when the score drops by more than the configured number of points
against the trailing average and the drop exceeds the confidence margin of
the run, or when a competitor outranks you, or negative tone or a wrong URL is
detected.

The webhook must be HTTPS, and hosts resolving to private or reserved addresses
are rejected unless an operator explicitly allows them.

Command line

# Full audit for the default scope
bin/magento angeo:aeo:brand-visibility

# One store view, ignoring the cache, with the action plan
bin/magento angeo:aeo:brand-visibility --store=2 --refresh --plan

# Machine-readable output
bin/magento angeo:aeo:brand-visibility --format=json
bin/magento angeo:aeo:brand-visibility --format=markdown

# One provider and prompt, printing the raw answer
bin/magento angeo:aeo:brand-visibility --provider=perplexity --prompt=brand_direct

# Fail a CI pipeline below a threshold
bin/magento angeo:aeo:brand-visibility --fail-on=50

Admin panel

Marketing → AEO Brand Visibility

• Dashboard — pick a store view, start a run, watch it complete, read each
  answer, and generate the action plan from the latest stored run.
• Audit History — a standard grid with filters, plus a detail page and CSV
  export per run.

Access is split into four permissions, so an agency can be given read access
without the ability to spend money on API calls:

Scheduling and retention

Scheduled runs use the dedicated angeo_brand_visibility cron group, so slow
provider calls cannot delay Magento's default group. A second job applies the
retention policy nightly: runs older than the configured age, and runs beyond
the per-store-view budget, are deleted.

Cost

Cost is providers × prompts × samples requests per run. With three providers,
three prompts and three samples that is 27 requests. Weekly runs on small models
are cents; grounded searches on large models are not. Start with samples = 3
and one grounded provider.

Development

vendor/bin/phpcs --standard=vendor/angeo/module-aeo-brand-visibility/phpcs.xml
vendor/bin/phpstan analyse -c vendor/angeo/module-aeo-brand-visibility/phpstan.neon
vendor/bin/phpunit -c vendor/angeo/module-aeo-brand-visibility/phpunit.xml

Adding a provider takes an AiProviderInterface implementation and one line in
the ProviderPool argument of etc/di.xml. No existing class needs editing.

Related modules

• angeo/module-aeo-audit — the audit framework this checker plugs into
• angeo/module-llms-txt — publish llms.txt for AI crawlers
• angeo/module-rich-data — stronger Organization and Product schema
• angeo/module-robots-txt-aeo — control which AI crawlers may read the store

License

MIT. See LICENSE.

Built by Ievgenii Gryshkun — Magento 2 solution architect,
Netherlands.

Changelog

All notable changes to angeo/module-aeo-brand-visibility are documented here.
The format follows Keep a Changelog and
the project uses Semantic Versioning.

[4.0.0] — 2026-08-31

A rewrite for the Adobe Commerce Marketplace technical requirements, plus fixes
for the data-loss and methodology problems found in 3.0.0.

Breaking

• BrandVisibilityServiceInterface::run() takes a fourth argument,
  ?int $auditResultId, so a queued run can be written back onto its own row.
• AuditResultRepositoryInterface::saveReport() takes ?int $id;
  createPendingRun() and markFailed() were added; pruneOldRecords() was
  replaced by prune(int $maxPerStore, int $maxAgeDays).
• BrandQueryResult now represents a cell aggregated over N samples. Its
  signals array of booleans became signalRates (percentages), and
  rawResponse became responses with a getRawResponse() accessor.
• Configuration path angeo_brand_vis/queries/queries_per_provider was renamed
  to .../max_prompts; 0 now means "no cap" rather than "cap at zero".
• angeo_brand_vis/analysis/llm_judge was removed. It cost a second API call
  per answer and produced a number that could not be compared between runs.
• Admin route angeo_brand_vis/query/single became angeo_brand_vis/query/test
  and is POST-only; angeo_brand_vis/history/viewdata was removed in favour of
  the UI component grid.
• The single ACL resource was split into ::view, ::run, ::export and
  ::config. Existing admin roles must be re-granted.
• New database columns are added by declarative schema. Runs stored by 3.0.0
  keep their scores, but have no samples, margin or competitive data.

Added

• Repeated sampling with a 95% confidence interval on every score. The reported
  ± margin makes it possible to tell a real regression from model variance.
• Web-grounded answers per provider: Claude's server-side search tool, Gemini's
  Google Search tool, OpenAI search-preview models. Perplexity is always
  grounded; Groq cannot be.
• Three-valued tone. Negative wording around the brand is detected and reduces
  the earned score by a configurable penalty.
• Real share of voice, weighted by mention count and by how early the brand
  appears, replacing the 1/N placeholder.
• Asynchronous runs over the message queue, with a pending row, a polling admin
  screen and an inline fallback for installations without consumers.
• A dedicated angeo_brand_visibility cron group, and a nightly retention job
  with a per-store-view row budget and a maximum age.
• A standard UI component grid for audit history, with filters, bookmarks and
  row actions.
• Configurable extra top-level domains, so the accuracy check recognises nl,
  de, co.uk and other country domains.
• Unit tests for the aggregator, the share-of-voice calculator, the report
  aggregation, the webhook guard and the configuration reader.
• i18n/en_US.csv, etc/csp_whitelist.xml, phpcs.xml, phpstan.neon and
  phpunit.xml.

Changed

• Providers are injected as an array through ProviderPool in di.xml instead
  of being hard-coded in the service constructor. A new provider is now one
  interface implementation and one di.xml line.
• All HTTP traffic uses the framework HTTP client instead of raw cURL calls, and
  all JSON goes through SerializerInterface.
• The admin templates contain no inline <script>, no inline <style> and no
  event attributes. Behaviour moved to a RequireJS module loaded through
  data-mage-init, so the screens work under a restrictive content security
  policy.
• The action plan is built from the latest stored run instead of triggering a
  fresh billable audit on every request.
• Retention runs in its own cron job rather than inside every save.
• OpenAI reasoning models receive max_completion_tokens and no temperature,
  so o-series and search-preview models no longer return HTTP 400.
• Provider labels, model option lists and the analysis language list are derived
  from code rather than duplicated in static arrays.

Fixed

• Analyser metadata — competitors, share of voice, winner, tone and accuracy —
  is now persisted. In 3.0.0 saveReport() dropped the meta key, so the
  headline feature of that release was lost on write and never reached the
  history or the CSV export.
• getLatest(), getStatistics() and retention are scoped by store view.
  Previously a multi-store installation averaged unrelated brands together, and
  alerts compared a store against that mixed average.
• The audit checker honours the StoreInterface it is given. Previously the
  argument was ignored and every store view was scored against the default
  scope.
• cache_ttl_hours = 0 disables the cache, as the field comment always claimed;
  it was previously coerced back to 24. The same fix applies to a temperature of
  0.
• A prompt override text is ignored while its enable toggle is off.
• The result cache lifetime is read from the scoped configuration rather than
  the unscoped instance.
• The Gemini API key travels in the x-goog-api-key header instead of the query
  string, where it was written to proxy and access logs.
• The alert webhook is validated: HTTPS only, and hosts resolving to private or
  reserved addresses are rejected unless explicitly allowed. This closes a
  server-side request forgery path to internal services.
• The CLI used an invalid <e> style tag, which threw instead of printing the
  error it was trying to report.
• Dutch and German separable verbs ("raad ik … aan", "empfehle ich") are matched
  as recommendations.
• magento/module-email is declared in composer.json and sequenced in
  module.xml; it was used but never required.
• Documentation drift: the supported analysis languages are en, uk, nl, de, fr, es (there is no Russian phrase set), negative sentiment is real rather than
  aspirational, and the CLI description lists every provider.

Security

• No raw cURL, no API keys in URLs, no unvalidated outbound requests.
• Every billable action is POST-only and behind its own ACL resource.
• Admin output is escaped in PHP and built with the DOM API in JavaScript, so a
  provider answer cannot inject markup into the admin panel.

[3.0.0]

Added

• Competitor tracking, share of voice and answer-accuracy checking.
• Gemini and Groq providers.
• Recommendation engine and CSV export.

[1.1.1]

Added

• Initial release: ChatGPT, Claude and Perplexity providers, five scoring
  signals, admin dashboard and the live_signal audit checker.