Ai Visibility Checker

Measure how visible a brand is inside AI-generated answers across ChatGPT, Gemini, Claude, and Perplexity.

Overview

For every question you provide, this Actor asks each selected AI answer engine, waits for the response to finish streaming, and extracts a structured record: whether your brand is mentioned, its position, the sentiment, the competitors named alongside it, and the citations/URLs used. It then computes a Visibility Score and a Recommendation Score and produces per-answer dataset rows plus aggregate JSON / Markdown / CSV reports.

Key capabilities

• Multi-engine querying via pluggable Playwright adapters (ChatGPT, Gemini, Claude, Perplexity)
• Deterministic, fully-tested parser (brand mention, position, sentiment, competitors)
• Citation extraction with domain normalization and categorization
• Scores: composite Visibility Score (0-100) and Recommendation Score (0-100)
• Proxy rotation, stealth, cookies, captcha/login-wall handling, screenshots on failure
• Strict TypeScript, ESLint, Prettier, and a comprehensive Jest test suite

Architecture

src/
├── main.ts                 # Actor.main() entry point (pipeline orchestration)
├── types.ts                # Actor-specific input/record/summary types
├── config/index.ts         # Input validation → strict config
├── analysis/index.ts       # RawAnswer → record, scores, summary
├── report/index.ts         # Markdown report builder
└── shared/                 # Reusable library (identical across all 3 actors)
    ├── types.ts            # Provider-agnostic domain types
    ├── logging/            # Structured logger over Apify log
    ├── retry/              # Exponential backoff with jitter
    ├── validation/         # Input validators
    ├── prompt/             # Prompt builder (context-aware)
    ├── parser/             # Answer parsing (pure, fixture-tested)
    ├── citations/          # URL/domain extraction + categorization
    ├── statistics/         # Small stat helpers
    ├── export/             # Dataset writer, CSV, Markdown, KV reports
    ├── browser/            # Playwright launcher, stealth, screenshots
    ├── adapters/           # AI platform adapters (base + 4 providers + registry)
    └── engine/             # Cross-platform answer collection (DI-friendly)

The pipeline: validate → build tasks → collect answers (Playwright adapters) → parse → analyze → persist.

Configuration / Input

Field	Type	Default	Description
brand	string (required)	—	Brand to measure
questions	string[] (required)	—	Questions asked on every platform
industry	string	—	Category context (e.g. "CRM software")
country	string	—	Market context (e.g. "United States")
platforms	string[]	all four	ChatGPT, Gemini, Claude, Perplexity
knownCompetitors	string[]	[]	Improves position/competitor accuracy
headless	boolean	true	Headless browser
screenshotOnFailure	boolean	true	Save screenshots to KV store on failure
maxRetries	integer	2	Retries per (platform, question)
askTimeoutMs	integer	90000	Max wait per answer
useApifyProxy	boolean	true	Route through Apify Proxy (residential)
cookies	array	[]	Session cookies for authenticated platforms

Input example

{
  "brand": "HubSpot",
  "industry": "CRM software",
  "country": "United States",
  "questions": ["best CRM for startups", "best CRM for small business", "HubSpot alternatives"],
  "platforms": ["ChatGPT", "Gemini", "Claude", "Perplexity"]
}

Output

Dataset record (one per question × platform)

{
  "question": "best CRM for startups",
  "platform": "ChatGPT",
  "brand": "HubSpot",
  "brandMentioned": true,
  "position": 1,
  "sentiment": "positive",
  "competitors": ["Salesforce", "Pipedrive", "Zoho CRM"],
  "citations": [{ "url": "https://www.g2.com/products/hubspot/reviews", "domain": "g2.com", "category": "review" }],
  "urls": ["https://www.g2.com/products/hubspot/reviews"],
  "answer": "…",
  "answeredAt": "2026-01-01T00:00:00.000Z",
  "error": null
}

Key-Value Store artifacts

• SUMMARY — aggregate JSON (scores, per-platform stats, top competitors)
• REPORT — human-readable Markdown report
• EXPORT_CSV — flat CSV export of all records

Scores

• Visibility Score = 100 × (0.5·mentionRate + 0.3·positionQuality + 0.2·sentiment)
• Recommendation Score = share of answers where the brand is in the top 3 and not negative

Rate limits & known limitations

• AI answer engines frequently require authentication (ChatGPT, Claude, Gemini). Supply session cookies for reliable results. Perplexity generally works anonymously.
• UI selectors change often; selectors live in src/shared/adapters/* and are easily updated.
• Captchas/login walls are detected; the Actor waits, then records a graceful error for that answer.
• Sentiment/position are heuristic (lexicon + structure), not a hosted LLM, keeping runs cheap & deterministic.

Deployment

npm install            # install dependencies
npm run build          # compile TypeScript → dist/
npm test               # run the Jest suite
npm run lint           # ESLint
npx playwright install chromium   # local browser (Docker image already has it)
apify push             # deploy to Apify
apify run --purge      # run locally

The Docker image is apify/actor-node-playwright-chrome:22 (Chromium preinstalled); npm run build runs during the image build.

Testing guide

npm test runs unit, parser (fixture-based), retry, validation, statistics, adapter (mock page), engine integration, and full end-to-end (browserless) tests. Fixtures live in tests/fixtures/.

Troubleshooting

Symptom	Cause	Fix
All answers error: login wall	Not authenticated	Provide cookies
error: captcha …	Bot check triggered	Enable Apify residential proxy; retry
Empty answers	Selectors changed	Update src/shared/adapters/<platform>.ts

Version history

• 1.0.0 — Initial production release: four adapters, parser, scoring, reports, full test suite.