🎉 Launch Sale — 50% OFF your first Pro payment.  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+
WordPress Multisite is not officially supported in v1.1.1.

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 — behavioral events: basic click/form events (Free), full event suite (Pro)
  • wp_fpai_conversions — completed conversion goals
  • wp_fpai_ai_reports — AI conversation history (questions and answers from the AI Analysis page)

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)
  • Tracking mode — Standard (localStorage-based), Storage-less (nothing is ever stored on the visitor's device), or Auto (storage-less for EU visitors, detected by browser timezone — the recommended default for new installs). In storage-less operation, pseudonymous IDs are derived server-side from a daily-rotating salt, so visitors cannot be linked across days; unique-visitor and new-vs-returning figures are therefore estimates. Each record stores which method collected it (Standard / Storage-less), shown in the dashboard and exports (from v1.1.1).
  • Bot / bulk-submission filter (from v1.1.1) — Off / Standard (default) / Strong. Excludes submissions from automation and bots (not "fake-data injection" — abnormal bulk volume from automated clients). Flagged requests are discarded before anything is written. There is no site-wide daily cap; basic safety limits (payload size, event count, per-IP rate) stay enforced at every setting, including Off.

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

Basic click and form-submit events — the ones conversion goals use — are always collected, in Free and Pro alike. The toggles above control the Pro event suite.

IP exclusions

Enter IP addresses to exclude from tracking, one per line. 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 Analysis
  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

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). Available in Free and Pro.
  • Click — fires when a clicked button or link matches the configured text, link URL, ID, or class. Available in Free and Pro.

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 the button/link text to match (partial match; link URL, ID, or class also work)
  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

From v1.1.1: for the last 30 days, pick a date range; for older data, choose a whole calendar month. Click Download — exports stream directly, so any volume downloads without timing out. (The currently distributed v1.1.0 exports a single custom date range.)

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, source file and line number (useful for debugging)

Events are visible in the Event Summary card on the dashboard 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. Deactivate the FPAI Free plugin (Plugins → Installed Plugins). Your analytics data stays in the database — Free and Pro share the same tables
  4. Install and activate the FPAI Pro plugin (Plugins → Add New → Upload Plugin, using the zip from your purchase email)
  5. In WordPress admin, go to FPAI → Settings → License
  6. Enter your license key and click Activate
  7. Pro features enable immediately — your existing data carries over with no loss

The license is validated against the Lemon Squeezy API and cached for 12 hours. If the API is temporarily unreachable, a recently verified license keeps working for up to 7 days offline (lifetime licenses up to 180 days); an explicitly invalid or expired response takes effect immediately.

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.
Yes. The built-in chat supports 9 providers, and for anything else you can export your data as CSV or JSON from the AI Analysis page and paste it into any AI tool — the JSON format includes schema descriptions so any model can read it.
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 ~10KB raw (~4KB compressed) for the free version and ~18KB (~6KB) for Pro, and loads in the footer so it never blocks rendering. 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.
Note: deleting or deactivating the plugin does not stop billing. To stop being charged, you must cancel via the "Manage your subscription" link above.

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().