Overview & Philosophy
F! Insights is a private, self-hosted intelligence engine for local business prospecting and GBP fulfillment. Unlike SaaS tools that charge per location, F! Insights runs on your server, your database, your rules.
The core strategy flips the dynamic of cold outreach: instead of interrupting with a claim, you provide a visitor with their own data and an AI-scored audit of exactly where they are losing ground to competitors. You aren't telling them they have a problem, Google's data is.
- Lead Gen Mode: Visitors use the scanner widget to see their own data, and you capture their contact info at peak engagement.
- Fulfillment Mode: Connect client GBPs to manage posts, service pages, profile optimization, and reviews from a single hub.
The Scan Report
Every scan produces an overall score out of 100 and individual scores across eight categories:
| Category | What it measures |
|---|---|
| Online Presence | Profile completeness, visibility signals, verified status |
| Customer Reviews | Rating, volume, recency, response patterns |
| Photos & Media | Photo count, recency, type coverage |
| Business Info | Hours, phone, address, website, attributes, amenities |
| Competitive Position | Comparison against 3 nearby active competitors |
| Website Performance | Core Web Vitals via PageSpeed Insights (Mobile/Desktop) |
| Local SEO Signals | Category specificity, NAP consistency, keyword positioning |
| Page Speed | FCP, LCP, TBT, CLS, Speed Index, TTI with AI interpretation |
Requirements
- WordPress 6.2+
- PHP 8.0+ (required for modern string functions and named arguments)
- Google Cloud Project with billing enabled (Places, Maps, and GBP APIs)
- Anthropic API Key (Claude AI-powered analysis)
Installation
Upload & Activate
Upload the plugin folder to /wp-content/plugins/ or install via the WordPress plugin screen. Activate the plugin.
API Configuration
Go to F! Insights → Settings → API Config. Enter your Google Places and Anthropic API keys.
Deploy Shortcode
Add to any page or post to begin capturing leads.
Technical Architecture
F! Insights is built for reliability and data sovereignty.
- Database: 19 tables managed via
dbDelta(). Idempotent runtime upgrades ensure schema consistency without data loss. - Uninstall: A "nuclear" uninstall option is provided, requiring explicit opt-in to wipe all tables, options, and logs.
- Rate Limiting: Fixed-window per IP with proxy and CDN detection to prevent API abuse.
- API Layer: All Claude calls route through
FI_Claude::request()with automatic 429/529 retry handling and token tracking. - Security: Stripe API keys are encrypted at rest with AES-256-CBC. All AJAX handlers use nonce verification and capability checks. Scan access tokens (short-lived transients) prevent cross-user report access.
API Configuration (Settings)
All core settings live under F! Insights → Settings → API Config.
Google API
Requires a Google Cloud project with the following APIs enabled:
- Places API (New): Core business data.
- Geocoding API: Lat/lng conversion.
- PageSpeed Insights API: Performance metrics.
- Maps JavaScript API: Geogrid ranking map.
- Google Business Profile API: Fulfillment features.
Claude API
Configure separate models for different tasks:
- Report Model: Claude Haiku 4.5 is recommended for scan-time analysis (fast, cost-effective, ~$0.01 per scan).
- Admin Intelligence Model: Claude Sonnet 4.5 or Opus 4 is recommended for Market Intel, Writing Campaign, and Near Me Visibility (higher quality).
Premium License
Enter your Polar.sh license key to activate premium features. The key is validated against the Polar API on save and stored locally. Features unlock immediately on validation.
GBP OAuth
Required for all fulfillment features (GBP Posts, Optimizer, Monitoring). Set up a Google Cloud OAuth 2.0 client ID and secret, then enter the redirect URI shown in the settings panel. Each client connects their own Google account via the connection widget in Client Workspace → Overview.
Stripe Billing
Connect your Stripe account to automate client billing. Enter your Stripe secret key (live or test). Map internal Client Plans to Stripe Price IDs. The plugin handles subscription lifecycle events (payment success, failure, cancellation) via webhooks.
Client Plans
Found under Settings → Stripe Billing → Client Plans. Define tiered service plans (e.g., Starter, Professional, Full Management) and map each to a Stripe Price ID. Plans gate feature access across the entire Client Workspace.
Each plan is a checklist of feature flags. When you enable a flag on a plan, all clients on that plan immediately gain access to the corresponding workspace tab or capability, with no page reload required. Disabling a flag removes it just as quickly.
| Feature flag | What it controls |
|---|---|
gbp_connect | Client can self-connect their Google Business Profile account |
gbp_insights | Live impressions, calls, and direction requests on the client dashboard |
gbp_audit | One-click profile audit surfacing gaps against Google quality signals |
gbp_suggestions | AI-drafted description, category, and attribute recommendations |
gbp_auto_update | Agency can push approved profile changes directly to Google |
gbp_monitoring | Daily check for unauthorised edits and profile changes with email alerts |
gbp_qr_gen | Printable QR codes for reviews, menu, booking, and custom links |
gbp_reporting | Automated monthly PDF performance report delivered to the client |
post_scheduler | Agency drafts and publishes GBP posts (updates, offers, events) |
post_cadence | AI-generated 4-week rolling post queue |
service_pages | AI-generated SEO service pages published to WordPress |
geo_tools | Map Pack ranking heatmap and Near Me Visibility action plan |
geogrid | Geogrid ranking scan visible in admin and client report |
ranking_dashboard | 6-panel performance dashboard with MoM score history |
profile_optimizer | 6-item GBP completeness checklist with push-to-GBP actions |
reviews_setup | Review snippet, QR code, email template, and tracking dashboard |
review_templates | AI-generated review response and outreach templates |
qr_reviews | Printable QR code for Google review collection |
competitor_gap | Competitor gap report with impact scores |
dashboard | Private shareable client dashboard link with score history |
Subscriptions & Billing
Client subscriptions are managed from Client Workspace → Overview → Subscription & Plan. The plugin supports two billing modes, giving you full flexibility regardless of how you invoice your clients.
Stripe Billing
When Stripe is connected and a Stripe Price ID is attached to the plan, activating a client via Stripe creates a subscription in your Stripe dashboard and charges the client automatically. Subscription state (active, past due, cancelled) is synced via webhooks: if a payment fails, feature access is automatically suspended until the issue is resolved.
External Billing
If you invoice clients directly (retainer, bank transfer, or any arrangement outside the plugin), use the External billing path. Feature access activates immediately, with no Stripe account required. Optionally set a renewal date and billing note (e.g., "Invoice #412, Net 30") for your own records.
When a renewal date is set, the plugin automatically expires the subscription when that date passes. A renewal action resets the date and re-activates access.
White Label
Found under F! Insights → Settings → White Label. Configure your agency name, logo, brand colors, and remove the F! Insights credit line from all client-facing reports. The report should feel like your proprietary software, not a third-party tool.
Notifications
Found under F! Insights → Settings → Notifications. Configure email alerts for new leads, follow-up reminders, and GBP monitoring events. Uses WordPress's native mail system (wp_mail). Pair with an SMTP plugin for reliable delivery.
Market Leads Page (fi-market-intel)
The primary operations hub for your agency. All prospecting, fulfillment, content, and planning tools live here across eight tabs.
Lead Form
Configure the public-facing scanner shortcode that visitors use to scan their Google Business Profile. Settings include the form headline, CTA button text, redirect URL after report delivery, and campaign-level overrides. Changes here affect every instance of unless a campaign slug overrides them.
can have a different headline, CTA, and redirect than the default scanner.
Leads & Prospects
Manage all contacts in your pipeline. Leads are visitors who scanned their own business via the shortcode. Prospects are businesses imported via Bulk Scan that have not yet engaged with you. Both types can be promoted to Client status, which makes them available in Client Workspace.
Actions available per row: view report, generate AI pitch, send email, promote to client, update status, and add notes. The Generate Prospect List widget at the top uses AI to find new businesses by category and location.
Bulk Scan
Run automated scans against a CSV list of businesses in the background via WP-Cron. Upload a file with business names and addresses, set a scan job running, and let it process asynchronously. The dashboard shows real-time progress, pass/fail counts, and token usage.
Supports pause, resume, per-item retry, and automatic recovery for items that get stuck in a scanning state. Completed results appear in the Leads & Prospects tab as Prospects.
Analytics
An interpretive briefing of your lead pipeline. Insight panels unlock progressively as your scan volume grows (10, 25, 50, 100, 250 scan thresholds). Includes score distribution, category gap patterns, and pipeline health metrics. Use this to identify which vertical or location has the most underperforming profiles, informing where to focus outreach.
Market Intel
AI-powered competitive and market analysis generated from your accumulated scan data. Produces industry-specific reports on profile quality gaps, common weaknesses, and optimization opportunities across your pipeline. Reports are cached and regenerated as your scan volume grows.
Includes a Pitch Generator that crafts outreach emails using the specific gaps from a lead's scan, replacing generic cold messages with data-backed observations the prospect can verify for themselves.
Viz Beta
A public-facing data visualization layer that publishes aggregated scan data as embeddable D3.js charts. The core SEO strategy: third-party sites that embed your charts link back to your hub page with a contextual attribution link, turning your scan database into a passive backlink engine.
/f-data/ on first Viz tab visit). Anyone can embed a chart on their own site using a one-line iframe — each embed links back to your hub page with your attribution text. Five chart types unlock as your scan volume grows.
Visualization modules
| Module | Chart type | Unlocks at | What it shows |
|---|---|---|---|
| Score Pulse | Radial / radar | 10 scans | Average GBP scores across all 8 audit categories in a radial area chart |
| Score Map | Voronoi / Delaunay | 25 scans | Each cell represents a business, colored by overall score — reveals geographic score clusters |
| Market Clusters | Force-directed | 50 scans | Businesses grouped by vertical, node size = score; high-density verticals visible at a glance |
| Category Breakdown | Sunburst partition | 100 scans | Layered breakdown by market → vertical → category; click to drill down |
| Co-Failure Map | Chord diagram | 250 scans | 8×8 matrix showing which audit categories tend to fail together across your scan population |
REST endpoints
| Endpoint | Purpose |
|---|---|
/wp-json/fi-insights/v1/viz/data | Returns aggregated chart data as JSON. Supports ?module=, ?vertical=, ?city= filters. CORS open (*). Rate-limited per IP. |
/wp-json/fi-insights/v1/viz/iframe | Returns a complete self-contained HTML page for embedding in an
|