🎉 Launch Sale — Pro is 50% OFF for a limited time.  Get it now →

Documentation

FPAI Documentation

Everything you need to install, configure, and get the most out of FPAI.

Installation

FPAI is a standard WordPress plugin. There are two ways to install it:

Option A — WordPress Plugin Directory (recommended)

  1. In your WordPress admin, go to Plugins → Add New
  2. Search for FPAI
  3. Click Install Now, then Activate

Option B — Manual ZIP upload

  1. Download the zip from WordPress.org
  2. In your WordPress admin, go to Plugins → Add New → Upload Plugin
  3. Choose the ZIP file and click Install Now
  4. Click Activate Plugin
Requirements WordPress 6.0 or higher · PHP 7.4 or higher · MySQL 5.7+ or MariaDB 10.3+

Activation

When FPAI is activated, it automatically creates five database tables in your WordPress database:

  • wp_fpai_sessions — visitor sessions with device, browser, UTM data
  • wp_fpai_pageviews — individual page views with scroll depth and time on page
  • wp_fpai_events — click, scroll, form, and other behavioral events (Pro)
  • wp_fpai_conversions — completed conversion goals
  • wp_fpai_ai_reports — AI analysis history (reserved for future use)

Tracking begins immediately after activation. No additional configuration is required to start collecting data.

Viewing your first data

After activation, the FPAI menu item appears in the WordPress sidebar. Click it to open the analytics dashboard.

If you don't see data right away, visit your site's frontend in a non-admin browser (or private/incognito window). Admin sessions are excluded by default. Within a few seconds, a session should appear in the dashboard.

Note on admin exclusion By default, FPAI excludes logged-in administrators from tracking. Use a private/incognito window, or a device where you're not logged into WordPress, to test that tracking is working.

Settings overview

Go to FPAI → Settings to configure the plugin. The settings page is divided into sections:

General

  • Enable tracking — master on/off switch for all data collection
  • Exclude administrators — prevents admin sessions from being counted (recommended: on)
  • Session timeout — minutes of inactivity before a session is closed (default: 30 min)

Event tracking options (Pro)

  • Track clicks — captures all click events with element selector and text
  • Track scroll depth — fires at 25%, 50%, 75%, 90%, and 100% scroll milestones
  • Track form submissions — captures form ID and submission event
  • Track outbound links — detects clicks on links to external domains

IP exclusions

Enter a comma-separated list of IP addresses to exclude from tracking. Useful for filtering out office IPs, agency IPs, or your own development machine.

192.168.1.100, 203.0.113.42, 198.51.100.0

AI Analysis Setup

FPAI includes a built-in AI chat interface in your WP dashboard. AI analysis is available on all plans, including Free. You bring your own API key — FPAI never touches it beyond sending it to the AI provider.

Supported providers

  • Anthropic Claude
  • OpenAI ChatGPT
  • Google Gemini
  • xAI Grok
  • Perplexity
  • Mistral
  • DeepSeek
  • Cohere
  • Alibaba Qwen
  1. Go to FPAI → Settings → AI Settings
  2. Select your provider from the nine supported options
  3. Enter your API key (stored only in your WordPress database)
  4. Go to FPAI → AI Analysis and ask your first question
Pre-built prompts Six prompts are available in one click: Performance Summary, Page Analysis, Traffic Sources, Conversion Analysis, Behavior Patterns, Action Items. Select any to send a structured analysis request instantly.
Conversation history Conversation history is persistent — previous Q&A loads automatically each time you open the AI Analysis page.
API key privacy Your key is stored in your own WordPress database and sent directly to your chosen AI provider when you make a request. FPAI's servers never receive or log your key.

Using the AI chat interface

Once your API key is saved, go to FPAI → AI Analysis. Select a date range, choose a pre-built prompt or type your own question, and click Send. FPAI collects your analytics data, formats it, and sends it to your AI provider. The response appears directly in the dashboard.

Conversation history is stored in the wp_fpai_ai_reports table in your WordPress database — no data is retained on FPAI's servers.

Using CSV/JSON export with external AI tools

If you want to use your analytics data in a tool outside of WordPress — Claude.ai, ChatGPT, Gemini, or any other — export it as a file first.

  1. Go to FPAI → Export
  2. Select a date range and choose CSV or JSON
  3. Click Download
  4. Upload the file into your AI chat (ChatGPT, Gemini, Claude.ai, etc.)
  5. Ask your question — the AI will read the data from the file

The AI Summary format (Pro) produces a compact plain-text export with schema descriptions included — optimized for pasting directly into any AI chat without file upload.

Conversion goals

Conversion goals let you define specific user actions to track and measure. Go to FPAI → Settings → Conversion Goals to manage them.

Goal types

  • URL (pageview) — fires when a visitor reaches a specific URL or URL pattern (e.g. /thank-you/). Available in Free and Pro.
  • Form submission — fires when a specific form is submitted, identified by form ID (e.g. #contact-form-7). Pro only.
  • Click — fires when a visitor clicks a specific element, identified by CSS selector. Pro only.

Creating a goal

  1. Click Add Goal
  2. Enter a name (e.g. "Trial Signup")
  3. Select the goal type
  4. Enter the URL, form ID, or CSS selector to match
  5. Optionally enter a monetary value per conversion
  6. Save — the goal becomes active immediately

Data export

Go to FPAI → Export to download your analytics data.

  • CSV — multi-section file with separate tables for sessions, pageviews, events, and conversions
  • JSON — full structured export with all fields and values
  • AI Summary (Pro) — compact plain-text format with schema descriptions, optimized for AI analysis

Select a date range using the date pickers, then click Download. Large date ranges may take a few seconds to generate.

Event tracking (Pro)

When a Pro license is active and event tracking is enabled in Settings, the FPAI tracker automatically captures:

  • Clicks — element tag, CSS selector, visible text, and target URL
  • Scroll depth — 25%, 50%, 75%, 90%, 100% milestones per page per session
  • Form submissions — form element ID and method
  • Outbound links — the full destination URL
  • Copy events — when a visitor selects and copies text from the page
  • JS errors — error message and stack trace (useful for debugging)

Events are visible in the dashboard under the Events tab and included in CSV/JSON exports.

Activating a Pro license

  1. Purchase Pro at fpai.orora.co.jp/pricing via Lemon Squeezy
  2. You'll receive a license key by email
  3. In WordPress admin, go to FPAI → Settings → License
  4. Enter your license key and click Activate
  5. Pro features enable immediately — no reinstall, no data loss

The license is validated against the Lemon Squeezy API and cached for 12 hours. If the API is temporarily unreachable, FPAI falls back to the locally stored status.

Transferring your license

  1. On the old site, go to FPAI → Settings → License and click Deactivate
  2. This frees the license instance in Lemon Squeezy
  3. On the new site, enter the same license key and activate

FAQ

First check in a non-admin browser or incognito window — admin sessions are excluded by default. Also verify that tracking is enabled in FPAI → Settings → General. If you're on a caching plugin, make sure the FPAI tracker script isn't being cached incorrectly.
Most shared hosting environments block remote MySQL connections. Check with your hosting provider whether remote MySQL access is allowed and whether you need to whitelist the IP address of your AI tool. If remote access isn't available, use the CSV/JSON export method instead.
Ensure you're copying the full key without leading or trailing spaces. If the license was previously activated on another site, deactivate it there first. If the problem persists, contact support with your order number.
The tracker script is ~3KB and loads asynchronously. It uses the sendBeacon API to send data in the background after the page has loaded, so it never blocks rendering or affects Core Web Vitals scores.
Click the "Manage your subscription" link in the purchase confirmation email sent by Lemon Squeezy. After cancellation, Pro features remain active until the end of your current billing period.

Troubleshooting

Plugin conflicts

If you experience unexpected behavior, temporarily deactivate other plugins to identify conflicts. Security plugins (Wordfence, Sucuri) sometimes block REST API endpoints — add /wp-json/fpai/ to your security plugin's whitelist.

Caching plugins

FPAI's tracker script is loaded dynamically and should not be minified or cached by caching plugins. Exclude fpai-tracker.js from your caching plugin's script optimization rules.

REST API blocked

FPAI uses the WordPress REST API (POST /wp-json/fpai/v1/collect) to receive tracking events. If your server or a security plugin blocks unauthenticated REST API access, tracking will not work. The collect endpoint is intentionally public (rate-limited and validated server-side).

Database tables missing

If the FPAI dashboard shows no data and tables appear to be missing, try deactivating and reactivating the plugin. The activation hook re-creates missing tables using dbDelta().