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.

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.

Supported AI providers

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
• 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.

[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.