angeo/module-aeo-brand-visibility

Live AI brand visibility audit for Magento 2 — queries ChatGPT, Claude, Perplexity, Gemini and Groq with brand-probing prompts and scores real-world AI recall, citation rate and recommendation presence. Multilingual since 1.3: detects recommendations and sentiment in English, Dutch, German, French and Ukrainian answers, and probes models in your market's language via the {{language}} placeholder.

angeo/module-aeo-brand-visibility is an open-source Magento 2 module that answers one question: when someone asks ChatGPT "where should I buy X?", does your store appear in the answer? It runs configurable prompts across all major AI providers, detects brand signals in responses, and scores your visibility from 0 to 100 with a letter grade.

Table of contents

• What it measures
• Supported AI providers
• Requirements
• Installation
• Quick start
• Admin Panel
• CLI usage
• Full configuration reference
  • General
  • AI Providers
  • Query Prompts
  • Scoring
  • Cron
• Setup guides
  • Groq API key (free)
  • OpenAI API key
  • Anthropic Claude API key
  • Google Gemini API key
  • Perplexity API key
• Scoring explained
• How to improve your score
• Integration with angeo/module-aeo-audit
• Related modules

What it measures

Each AI query result is analysed for five signals:

Each signal has a configurable weight. The overall score is a weighted average across all successful query results, converted to 0–100 and graded A–F.

Two measurement modes (since 2.0)

AI assistants answer in two fundamentally different ways, and they measure different things:

• Training recall (default) — the model answers from what it memorised during training. Fast and cheap, but months out of date and blind to your latest content and backlinks.
• Live web search (grounded toggle) — the model actually searches the web before answering, exactly like a real ChatGPT / Gemini / Claude user's session. This is what "AI search visibility" really means.

Enable Live Web Search per provider (ChatGPT, Claude, Gemini; Perplexity is always live, Groq never is). Every result records which mode produced it, and the report reports the mix rather than averaging the two silently.

Share of voice (since 2.0)

A visibility score in isolation is hard to act on. Add competitors to the watch-list (Name | domain.tld per line) and every answer to "what are the best stores for X?" — which already names the competition — is mined for who else shows up. The report ranks your brand against each competitor: you appear in 20% of answers, competitor X in 80% names the actual problem an abstract "40/100" hides.

Supported AI providers

Extending providers (since 2.0): providers are wired as a di.xml array. Add your own (Mistral, DeepSeek, a local Ollama, …) by implementing Angeo\AeoBrandVisibility\Api\AiProviderInterface and appending one <item> to the providers argument of BrandVisibilityService — no core changes.

Enable one or more providers. Each active provider runs all configured prompts, and results are aggregated into a single score.

Requirements

• PHP 8.2, 8.3, or 8.4
• Magento 2.4.6 / 2.4.7 / 2.4.8 (Adobe Commerce / Mage-OS supported)
• angeo/module-aeo-audit ^3.0 || ^4.0
• ext-curl

v1.1.0 compatibility note: this module requires angeo/module-aeo-audit v3.0 or newer. If you're on v2.x of the audit module, either update both, or pin this module to ^1.0 which still works against v2.x.

Installation

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

Quick start

Step 1 — Configure your brand

Go to Stores → Configuration → Angeo AEO → Brand Visibility → General:

1. Brand Name → your store name as AI systems know it (e.g. Angeo)
2. Brand Domain → your domain without protocol (e.g. angeo.dev)
3. Store Category → what you sell (e.g. Magento development tools)

Step 2 — Enable a free provider (Groq)

Go to Groq Settings:

1. Get a free API key at console.groq.com — no credit card
2. Enable Groq → Yes
3. Groq API Key → paste your gsk_... key
4. Save Config

Step 3 — Run your first audit

bin/magento angeo:aeo:brand-visibility

Or from Admin Panel: Marketing → Angeo AEO → Brand Visibility → Run Audit

Admin Panel

Marketing → Angeo AEO → Brand Visibility

Run Audit

The main dashboard with:

• Score ring — overall score 0–100 with letter grade (A–F)
• Signal breakdown — mention rate, recommendation rate, URL citation rate, 1st position rate, positive sentiment rate
• Results table — per-provider, per-prompt responses with detected signals highlighted
• Action plan — prioritised recommendations to improve your score
• Single Query Tester — test one provider + one prompt without saving to history

Audit History

Grid view of all past audit runs with:

• Date, brand, score (colour-coded), grade (badge), triggered by, query count, error count
• Signal pills showing signal rates at a glance
• Click any row action → View for full detail page with raw AI responses

Configuration

Stores → Configuration → Angeo AEO → Brand Visibility

CLI usage

# Full audit — all enabled providers, all enabled prompts
bin/magento angeo:aeo:brand-visibility

# Force fresh queries — bypass cache
bin/magento angeo:aeo:brand-visibility --refresh

# Test a single provider
bin/magento angeo:aeo:brand-visibility --provider=groq

# Test a single provider + specific prompt
bin/magento angeo:aeo:brand-visibility --provider=chatgpt --prompt=brand_direct

# Output as JSON (useful for CI pipelines)
bin/magento angeo:aeo:brand-visibility --format=json

# CI mode — exit code 1 if score below threshold
bin/magento angeo:aeo:brand-visibility --fail-on=70

Full configuration reference

Path: Stores → Configuration → Angeo AEO → Brand Visibility

General

AI Providers

Each provider has its own section. Enable the ones you have API keys for.

ChatGPT (OpenAI)

Claude (Anthropic)

Perplexity

Note: Perplexity uses live web search, making it the most realistic indicator of actual AI visibility. It reflects what customers would see today, not what was in training data months ago.

Gemini (Google)

Groq (Free)

Free tier: 30 RPM, 14,400 requests/day.

Query Prompts

Six prompt types are available. Enable or disable each individually.

Additional settings:

Scoring

Signal weights determine the contribution of each detected signal to the overall score:

Grade thresholds:

Cron

Results from cron runs appear in Audit History with triggered_by: cron.

Setup guides

Groq API key (free)

1. Go to console.groq.com — create an account, no credit card required
2. API Keys → Create API key
3. Copy the key (starts with gsk_)
4. In Magento: Stores → Configuration → Angeo AEO → Brand Visibility → Groq Settings → API Key

OpenAI API key

1. Go to platform.openai.com → sign in or create account
2. API keys → Create new secret key
3. Copy the key (starts with sk-) — shown only once
4. In Magento: ... → ChatGPT Settings → API Key

Anthropic Claude API key

1. Go to console.anthropic.com → create account
2. API Keys → Create Key
3. Copy the key (starts with sk-ant-)
4. In Magento: ... → Claude Settings → API Key

Google Gemini API key

1. Go to aistudio.google.com/app/apikey
2. Create API key in new project
3. Copy the key
4. In Magento: ... → Gemini Settings → API Key

Perplexity API key

1. Go to perplexity.ai/settings/api
2. Generate → copy the key
3. In Magento: ... → Perplexity Settings → API Key

Scoring explained

Each AI query produces a BrandQueryResult with five boolean signals. Signals are weighted and averaged:

query_score = sum(signal_weight for each detected signal) /
              sum(all_signal_weights) * 100

The overall score is the average of all successful query scores. Failed queries (API errors) are excluded from the average.

Example with default weights:

• 1st Position detected → +2.0
• Recommended detected → +1.5
• URL Cited not detected → 0
• Mentioned detected → +1.0
• Positive Sentiment detected → +0.5

query_score = (2.0 + 1.5 + 1.0 + 0.5) / (2.0 + 1.5 + 1.5 + 1.0 + 0.5) * 100
            = 5.0 / 6.5 * 100 = 76.9 → Grade B

How to improve your score

Run bin/magento angeo:aeo:audit for a full 15-signal technical AEO audit to identify and fix the infrastructure issues that block AI indexing.

Integration with angeo/module-aeo-audit

When angeo/module-aeo-audit v3.0+ is installed (required dependency), this
module adds a brand_visibility checker to the AEO audit pipeline as the
16th signal alongside the 15 built-in ones.

# Full 16-signal audit including brand visibility
bin/magento angeo:aeo:audit

# Skip brand visibility (saves API calls) — runs only the 15 built-in technical checks
bin/magento angeo:aeo:audit --category=technical,feed

# Run only live signals (this checker — live_signal category is reserved for third-party live checks)
bin/magento angeo:aeo:audit --category=live_signal

Brand visibility is registered with:

• Category: live_signal — calls external APIs
• Severity: critical — headline AEO metric
• Weight: 1.0 — top-tier signal in the score

Pass/warn/fail status is driven by your configured score thresholds
(default pass = 80, warn = 60).

Custom-checker authors

This module is the canonical example of how to extend the audit pipeline.
v3 checker contract:

public function check(\Magento\Store\Api\Data\StoreInterface $store): CheckResult;
public function getCategory(): string;   // CheckerInterface::CATEGORY_*
public function getSeverity(): string;   // CheckerInterface::SEVERITY_*

Extending \Angeo\AeoAudit\Model\Checker\AbstractChecker is the easiest
path — you get HttpCache + StoreUrlSampler + JSON-LD parsing
helpers + result factory methods for free.

Related modules

Security & data handling

This module talks to external AI APIs and renders their responses in the admin
panel, so it follows defensive defaults:

• API keys for every provider (ChatGPT, Claude, Perplexity, Gemini, Groq)
  are stored with Magento's Magento\Config\Model\Config\Backend\Encrypted
  backend model and rendered as obscure fields. They are never written to
  logs. The Gemini key is sent in the x-goog-api-key request header rather
  than the URL query string, so it cannot leak into proxy or access logs.
• Outbound HTTP is HTTPS-only and does not follow redirects
  (CURLOPT_PROTOCOLS/CURLOPT_REDIR_PROTOCOLS pinned to HTTPS,
  CURLOPT_FOLLOWLOCATION disabled), with an explicit connect timeout.
• Admin AJAX endpoints are protected by ACL
  (Angeo_AeoBrandVisibility::run) and Magento's form key; mutating actions
  are POST-only. Unexpected exceptions are logged to the module log and only a
  generic message is returned to the browser.
• Output escaping: server-rendered templates use escapeHtml/escapeUrl,
  and the JS that injects AI-provider text into the admin UI routes every
  untrusted value through a strict HTML/attribute escaper before insertion.
• Serialization uses Magento's SerializerInterface throughout (no native
  json_encode/json_decode and no PHP serialize() of untrusted data),
  avoiding object-injection surfaces.
• Log contents: when Enable Logging is on, truncated prompt and response
  previews are written to var/log/angeo_aeo_brand_visibility.log. Keep logging
  off in production if your prompts may contain sensitive data.

License

MIT — free to use, modify, and distribute.

Author

Ievgenii Gryshkun · angeo.dev · [email protected]

Changelog

All notable changes to angeo/module-aeo-brand-visibility will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[2.0.0] — 2026-07-03

The measurement-validity release. Until now 4 of 5 providers measured
training recall — what a model memorised months ago — while the UI implied
live AI-search visibility. 2.0 closes that gap and adds the competitive
dimension. Breaking changes (see Upgrading below).

Added

• Grounded (live web search) mode per provider. ChatGPT via the Responses
  API + web_search tool, Gemini via Grounding with Google Search, Claude via
  the server-side web_search tool — the same retrieval real users get.
  Toggle Live Web Search under each provider (default OFF; grounded calls
  cost more and get a longer timeout). Perplexity is always grounded; Groq
  never is. Each result records which mode produced it, and the report never
  averages the two silently — groundingBreakdown() surfaces the mix.
• Share of voice. A competitor watch-list (Response Analysis → Competitor
  Watch-list, Name | domain.tld per line) turns "your score is 40" into
  "you appear in 20% of answers, competitor X in 80%". The analyzer now
  extracts every competitor mention and every domain cited in each answer;
  BrandVisibilityReport::shareOfVoice() ranks brand vs competitors, persisted
  in the new share_of_voice column and surfaced in the audit checker.
• Structured citations. Providers return their source URLs as structured
  data (ProviderResponse::$citations) instead of Perplexity smuggling them
  into the text as a "Sources:" suffix. A citation of your own domain now
  feeds url_cited directly — being a cited source is the strongest
  visibility outcome, and it is scored as such.
• Repeats per prompt (1–5). LLM answers are stochastic even at low
  temperature. Sampling each prompt N times and keeping the MEDIAN score /
  majority-vote signals turns noisy single samples into stable trend points.
  Default 1 (cost-neutral); 3 recommended for weekly tracking. A failed
  attempt no longer poisons the rest; all-failed still yields a clean error
  result.
• Pluggable provider registry. BrandVisibilityService now receives an
  AiProviderInterface[] via di.xml. Third-party modules add a provider
  (Mistral, DeepSeek, a local Ollama, …) with one di.xml <item> — no core
  edits. Ships with the five built-ins wired in etc/di.xml.

Changed

• AiProviderInterface (BC break). query() now returns a
  ProviderResponse (text + citations + grounded) instead of a bare string,
  and adds supportsGrounding() / isGrounded(). Any custom provider must be
  updated.
• BrandVisibilityService constructor (BC break). The five concrete
  provider arguments are replaced by a single providers array (injected via
  di.xml). Custom instantiation must pass the array.
• Cache namespace bumped to angeo_bv2_ — the 2.0 payload shape must not
  hydrate from 1.x cache entries. Old entries expire naturally; no action
  needed.

Database

• New nullable share_of_voice column on angeo_brand_visibility_audit
  (declarative schema — applied by setup:upgrade). No data migration.

Upgrading from 1.3.x

1. composer require angeo/module-aeo-brand-visibility:^2.0
2. bin/magento setup:upgrade && bin/magento setup:di:compile
3. If you wrote a custom AiProviderInterface implementation, update it to
   return ProviderResponse and implement the two new methods.
4. If you instantiate BrandVisibilityService yourself (not via DI),
   pass providers as the providers array argument.
5. Optional: add competitors under Response Analysis, enable Live Web
   Search per provider, and set Repeats Per Prompt to 3 for stable trends.

[1.3.0] — 2026-07-02

Release hygiene + the multilingual analyzer. Drop-in upgrade from 1.2.x
(composer update, setup:upgrade, setup:di:compile) — no DB changes;
one config field renamed with a read fallback, saved values survive.

Added

• Multilingual response analysis. Recommendation and sentiment phrases
  now come from per-language packs — English, Dutch, German, French and
  Ukrainian (Service/Analysis/PhrasePack). AI assistants answer in the
  shopper's language; before this release a Dutch "zeker aan te raden" or a
  German "sehr empfehlenswert" scored recommended = false. Languages are
  selectable under Response Analysis → Analysis Languages (empty = all
  packs, the safe default). Adding a language is one array in PhrasePack.
• {{language}} prompt placeholder plus a Query Language config field
  — probe AI models in the language of your market, not just English.
• GitHub Actions CI (.github/workflows/ci.yml): phpcs, PHPStan, PHPUnit
  on PHP 8.2/8.3/8.4, and a Mage-OS mirror installability job. The
  aeo-audit dependency resolves from GitHub until new tags reach Packagist.
• i18n/en_US.csv — base translation dictionary (46 admin strings).

Changed

• Unicode word-boundary brand matching. Brand name and keywords are now
  matched as whole words ((?<![\p{L}\p{N}]) … (?![\p{L}\p{N}])), so the
  brand "Geo" no longer matches inside "geography" and short keywords stop
  firing on unrelated words. Domain matching intentionally remains
  substring-based (domains are distinctive and live inside URLs).
• Deterministic provider temperatures. Claude now sends an explicit
  temperature: 0.2 (previously unset → provider default ≈ 1.0); Gemini and
  Groq aligned from 0.3 to 0.2. Visibility measurement needs the model's
  most probable answer — creative variance was score jitter between runs.
• "Queries Per Provider" renamed to "Max Prompts Per Provider" — the old
  name described the cap incorrectly (it limits prompts; total queries =
  prompts × providers). Values saved under the legacy path are still read.
• angeo/module-aeo-audit constraint widened to ^3.0||^4.0 — compatible
  with the aeo-audit 4.0.0 evidence-layer release.

Fixed

• GroqProviderTest::testIsConfiguredWithApiKey never mocked the enabled
  flag and silently failed — it had never actually run (no CI existed).
  Fixed; full suite green (63 tests).

[1.2.0] — 2026-06-12

Security hardening and code-quality release. No database or configuration
changes — upgrading from 1.1.x is drop-in (composer update, then
bin/magento setup:upgrade && bin/magento setup:di:compile).

Security

• Admin UI XSS hardening. The JavaScript escaper used when injecting
  AI-provider responses into the Run/History/Single-Test panels now escapes
  single quotes, backticks and slashes in addition to & < > ", making it safe
  for both HTML-text and quoted-attribute contexts. All untrusted provider text
  (raw responses, prompts, labels) is routed through it.
• Gemini API key moved out of the URL. The key is now sent in the
  x-goog-api-key header instead of the ?key= query parameter, so it can no
  longer appear in proxy logs, access logs or error messages.
• Outbound HTTP locked down. The shared provider transport is now HTTPS-only
  (CURLOPT_PROTOCOLS / CURLOPT_REDIR_PROTOCOLS), no longer follows redirects
  (CURLOPT_FOLLOWLOCATION disabled — SSRF guard), and sets an explicit
  CURLOPT_CONNECTTIMEOUT.
• No exception detail leaks to the browser. Admin AJAX controllers
  (Run, Plan, History/Data, History/ViewData) now log the full
  exception to the dedicated module log and return a generic message. The
  single-query diagnostic tool still surfaces the provider message (it is a
  manual debugging aid and no longer key-bearing).

Changed

• All (de)serialization goes through Magento SerializerInterface. Replaced
  every native json_encode / json_decode call (provider transport, audit
  result model, history grid column, CLI --format=json) with the injected
  serializer. The main service and repository now depend on the interface
  rather than the concrete Json class.
• Cache invalidation fixed. The audit cache key now includes the set of
  enabled providers, their configured models and the system prompt, so toggling
  a provider or switching a model no longer serves a stale report.
• Cache Results (hours) = 0 now truly disables caching. Previously the
  0 value was swallowed and silently treated as 24h.
• Provider list corrected in the CLI. Command description and the
  --provider option help now list all five providers
  (chatgpt|claude|perplexity|gemini|groq).

Tests

• BrandVisibilityServiceTest rewritten against the real service contract
  (Magento CacheInterface, real method names and constructor signature, real
  serializer) covering guard clauses, cache hits, force-refresh and save-failure
  resilience.
• GroqProviderTest updated for the new serializer-aware constructor.

[1.1.1] — 2026-05-28

Changed — documentation only (no code changes)

angeo/module-aeo-audit v3.0.0 final release ships with 15 built-in
signals, not the 16 referenced in this module's v1.1.0 README. The
ai_bot_traffic checker was removed from aeo-audit during pre-release
security review (it encouraged broad read access on /var/log/nginx/,
didn't work on Cloud/containerised hosting, and was dominated by false
positives behind edge caches — see aeo-audit CHANGELOG "Considered and
rejected" for the full rationale).

This patch release synchronises documentation with the published aeo-audit
v3.0.0 counts:

• README: "17th signal alongside the 16 built-in ones" →
  "16th signal alongside the 15 built-in ones"
• README CLI examples: "Full 17-signal audit" → "Full 16-signal audit";
  "16 built-in technical checks" → "15 built-in technical checks"
• README CLI examples: "Run only live signals (this checker + AI bot
  traffic)" → "Run only live signals (this checker — live_signal
  category is reserved for third-party live checks)"
• README Related modules: "16-signal CLI audit" → "15-signal CLI audit"
• README How-to-improve: "8-signal technical AEO audit" (stale since v2) →
  "15-signal technical AEO audit"

No behaviour change. BrandVisibilityChecker continues to register
under CheckerInterface::CATEGORY_LIVE_SIGNAL (still a valid constant
in aeo-audit v3.0.0), and aeo-audit's documentation explicitly reserves
that category for this module. Upgrading from 1.1.0 → 1.1.1 is risk-free.

[1.1.0] — 2026-05-22

Compatibility — required for angeo/module-aeo-audit v3.0+

This release adapts BrandVisibilityChecker to the v3 CheckerInterface
introduced in angeo/module-aeo-audit 3.0.0. Without this update, attempting
to use brand-visibility v1.0.x with aeo-audit v3.x produces a fatal at boot:

Fatal error: Declaration of
Angeo\AeoBrandVisibility\Model\Checker\BrandVisibilityChecker::check(string $baseUrl)
must be compatible with
Angeo\AeoAudit\Api\CheckerInterface::check(Magento\Store\Api\Data\StoreInterface $store)

Changed

• BrandVisibilityChecker::check() signature updated to accept
  \Magento\Store\Api\Data\StoreInterface $store (was string $baseUrl).
• BrandVisibilityChecker now extends \Angeo\AeoAudit\Model\Checker\AbstractChecker
  instead of implementing CheckerInterface directly — gets shared HttpCache,
  StoreUrlSampler, and result factory helpers automatically.
• Replaced direct new CheckResult(...) calls with the v3 named factories
  ($this->pass() / $this->warn() / $this->fail()) — these correctly
  propagate checkCode, weight, category and severity into the result.
• The disabled-module case now returns WARN instead of the removed
  STATUS_SKIP (the v3 status vocabulary is pass / warn / fail only).
• Weight clamped from 1.5 → 1.0 to fit the v3 normalised-weight contract
  (0.0–1.0). Brand visibility remains a top-tier signal because all
  technical checks at 1.0 share the same weight.
• The service-exception catch broadened from \RuntimeException to
  \Throwable — covers \Error and \LogicException from upstream
  provider client libraries.

Added

• getCategory(): string → returns CATEGORY_LIVE_SIGNAL (external API).
  Allows bin/magento angeo:aeo:audit --category=technical to skip the
  brand check for fast cron runs.
• getSeverity(): string → returns SEVERITY_CRITICAL. Plays with
  --fail-on-severity=critical for CI gates.
• details array now surfaces full breakdown: score, grade, queries
  run/ok, all four signal rates, cache flag, configured thresholds.
• New unit test suite Test/Unit/Model/Checker/BrandVisibilityCheckerTest
  with 13 test cases covering signature compatibility, short-circuits,
  threshold-driven outcomes, recommendation building.

Migration from 1.0.x

For typical users — composer update angeo/module-aeo-brand-visibility.
The DI wiring in etc/di.xml is unchanged (the AuditRunner argument
extension is identical between v2 and v3 of aeo-audit).

If you pinned angeo/module-aeo-audit to v2.x:

• Keep angeo/module-aeo-brand-visibility pinned to ^1.0, OR
• Update both to v3.0+ together.

[1.0.0] — 2026-04-15

Added

• Initial release.
• Live AI brand audit across ChatGPT, Claude, Perplexity, Gemini and Groq.
• Five-signal scoring (Mentioned / Recommended / URL Cited / First Result / Sentiment).
• Configurable prompts, models, max_tokens, temperature per provider.
• Admin UI: History grid, Detail view, Run-Audit form, Plan preview.
• CLI: bin/magento angeo:aeo:brand-visibility.
• Cron support with cache TTL.
• Auto-registers as the 9th checker in angeo/module-aeo-audit via DI.