# 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. Extends angeo/module-aeo-audit v3 via CheckerInterface as the 16th signal, alongside the 15 built-in technical checks.

`composer require angeo/module-aeo-brand-visibility`

Canonical URL: https://packagento.com/angeo/module-aeo-brand-visibility

## At a glance

- **Vendor**: angeo (https://packagento.com/angeo.md)
- **Latest version**: 1.2.0 — released 2026-06-14
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/angeo/module-aeo-brand-visibility and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

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

## What it does

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. Extends angeo/module-aeo-audit v3 via CheckerInterface as the 16th signal, alongside the 15 built-in technical checks.

## README

[![Packagist Version](https://img.shields.io/packagist/v/angeo/module-aeo-brand-visibility.svg)](https://packagist.org/packages/angeo/module-aeo-brand-visibility)
[![Packagist Downloads](https://img.shields.io/packagist/dt/angeo/module-aeo-brand-visibility.svg)](https://packagist.org/packages/angeo/module-aeo-brand-visibility)
[![PHP](https://img.shields.io/badge/PHP-%3E%3D8.2-blue.svg)](https://php.net)
[![Magento](https://img.shields.io/badge/Magento-2.4.x-orange.svg)](https://magento.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**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](#what-it-measures)
- [Supported AI providers](#supported-ai-providers)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Admin Panel](#admin-panel)
- [CLI usage](#cli-usage)
- [Full configuration reference](#full-configuration-reference)
    - [General](#general)
    - [AI Providers](#ai-providers)
    - [Query Prompts](#query-prompts)
    - [Scoring](#scoring)
    - [Cron](#cron)
- [Setup guides](#setup-guides)
    - [Groq API key (free)](#groq-api-key-free)
    - [OpenAI API key](#openai-api-key)
    - [Anthropic Claude API key](#anthropic-claude-api-key)
    - [Google Gemini API key](#google-gemini-api-key)
    - [Perplexity API key](#perplexity-api-key)
- [Scoring explained](#scoring-explained)
- [How to improve your score](#how-to-improve-your-score)
- [Integration with angeo/module-aeo-audit](#integration-with-angeomodule-aeo-audit)
- [Related modules](#related-modules)

---

### What it measures

Each AI query result is analysed for five signals:

| Signal | Description |
|---|---|
| **Mentioned** | Your brand name appears in the AI response |
| **Recommended** | AI actively suggests your store as a destination |
| **URL Cited** | Your domain is included in the answer |
| **1st Position** | Your store is the first recommendation |
| **Positive Sentiment** | Response tone about your brand is positive |

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

| Provider | Models | Cost | Notes |
|---|---|---|---|
| **Groq** | llama-3.3-70b-versatile, mixtral-8x7b | **Free** | Best starting point — 14,400 req/day, no card |
| **Perplexity** | sonar, sonar-pro, sonar-deep-research | Paid | Live web search — most realistic signal |
| **OpenAI** | gpt-4.1, gpt-4.1-mini, gpt-4o | Paid | |
| **Anthropic Claude** | claude-sonnet-4-6, claude-haiku-4-5 | Paid | |
| **Google Gemini** | gemini-2.5-flash-preview, gemini-2.0-flash | Free tier + paid | |

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

```bash
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](https://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**

```bash
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

```bash
## 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

_(README truncated for .md surface. Full README on https://packagento.com/angeo/module-aeo-brand-visibility.)_

## Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### [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:

_(Changelog truncated for .md surface. Full history on https://packagento.com/angeo/module-aeo-brand-visibility.)_

## Recent Versions

| Version | Released |
|---|---|
| 1.2.0 | 2026-06-14 |
| 1.1.1 | 2026-05-28 |
| 1.1.0 | 2026-05-28 |
| 1.0.0 | 2026-05-16 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| angeo/module-aeo-audit | ^3.0 |
| ext-curl | * |
| magento/framework | ^103.0 |
| magento/module-backend | ^102.0 |
| magento/module-config | ^101.2 |
| magento/module-store | ^101.1 |
| php | ~8.2.0\|\|~8.3.0\|\|~8.4.0 |

### Require (dev)

| Package | Constraint |
|---|---|
| phpstan/phpstan | ^1.10 |
| phpunit/phpunit | ^10.0 |

### Suggest

| Package | Constraint |
|---|---|
| angeo/module-llms-txt | Publish llms.txt to improve brand recall in AI training pipelines. |
| angeo/module-openai-description-updater | Improve product content quality to increase AI citation rate. |
| angeo/module-rich-data | Improve Organization + Product schema to strengthen entity recognition. |

## Quality

Latest release (1.2.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | not tested |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 353 | 12 errors, 341 warnings (ruleset: Magento2) — 181 auto-fixable with phpcbf |
| PHPMD | Warning | 31 | 31 rule violations (MissingImport:21, NPathComplexity:2, TooManyPublicMethods:2, IfStatementAssignment:1, UnusedFormalParameter:1) |
| Cpd | Pass | 0 |  |
| Composer validate | Pass | 0 |  |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 16 | 16 | – | – |
| 2.4.8 | – | 16 | 16 | – |
| 2.4.9 | – | – | 16 | N/A |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 1 | 1 | – | – |
| 2.4.8 | – | 1 | not tested | – |
| 2.4.9 | – | – | Error | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["angeo/module-aeo-brand-visibility"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

angeo is a Magento 2 vendor on Packagento. See https://packagento.com/angeo.md for their full catalogue.