Apex Insights Documentation

Apex Insights is a first-party, privacy-focused analytics plugin for WordPress and WooCommerce. It collects visitor data server-side — no JavaScript tags, no cookies, no third-party data sharing — and stores everything in your own WordPress database.

The plugin includes an AI-powered query engine that lets you ask questions about your data in plain English and receive actionable, prioritized recommendations. It also provides automated content decay detection, keyword cannibalization alerts, and WooCommerce funnel analytics.

All data is owned by you and never leaves your infrastructure, making Apex Insights fully GDPR compliant without requiring cookie consent banners.

Component	Minimum	Recommended
WordPress	5.6+	6.4+
PHP	7.4+	8.2+
MySQL	5.7+ or MariaDB 10.3+	MySQL 8.0+ or MariaDB 10.6+
WooCommerce	6.0+ (for commerce features)	8.0+

1. Purchase a license at apexstack.cloud/pricing
2. Download the plugin ZIP from your account dashboard
3. In WordPress, go to Plugins → Add New → Upload Plugin
4. Upload the ZIP and click Install Now
5. Click Activate Plugin

# Or via WP-CLI
wp plugin install /path/to/apex-insights.zip --activate

After activation, Apex Insights begins tracking visitors immediately. Visit Insights → Dashboard to see your first data.

Navigate to Insights → Settings → License and enter your license key.

# WP-CLI activation
wp apex-insights license activate YOUR-LICENSE-KEY
wp apex-insights license status

Configure Apex Insights via the Insights → Settings panel or via wp-config.php constants.

// Dashboard menu location ('toplevel' or 'submenu')
define('APEX_INSIGHTS_MENU', 'toplevel');

// Data retention period in days (default: 365)
define('APEX_INSIGHTS_RETENTION_DAYS', 365);

// Exclude specific user roles from tracking
define('APEX_INSIGHTS_EXCLUDE_ROLES', ['administrator', 'editor']);

// Exclude specific IPs from tracking
define('APEX_INSIGHTS_EXCLUDE_IPS', ['192.168.1.1']);

// Enable bot filtering (default: true)
define('APEX_INSIGHTS_FILTER_BOTS', true);

Apex Insights uses server-side PHP tracking by default — no JavaScript tag is needed. Every page request is logged automatically via a WordPress action hook.

Tracking logged-in users

// Track logged-in users (default: false)
define('APEX_INSIGHTS_TRACK_LOGGED_IN', true);

// Track admin pages (default: false)
define('APEX_INSIGHTS_TRACK_ADMIN', false);

SPA / AJAX Page Views

For single-page applications or AJAX-driven navigation, include the optional JavaScript tracker:

// Enable the lightweight JS tracker for SPA page views
define('APEX_INSIGHTS_JS_TRACKER', true);

When WooCommerce is active, Apex Insights automatically hooks into the purchase funnel:

• Product impressions — tracked on shop and category pages
• Product views — tracked on single product pages
• Add to cart — tracked via WooCommerce hooks
• Checkout started — tracked when checkout page loads
• Purchase complete — tracked on the thank-you page

// Enable WooCommerce tracking (default: true when WC is active)
define('APEX_INSIGHTS_WOOCOMMERCE', true);

// Track product impressions (can be expensive on large catalogs)
define('APEX_INSIGHTS_WOO_IMPRESSIONS', true);

Apex Insights automatically prunes data older than the configured retention period. A WP-Cron job runs daily to clean up expired records.

// Keep data for 365 days (default)
define('APEX_INSIGHTS_RETENTION_DAYS', 365);

// Keep data for 90 days (to reduce DB size)
define('APEX_INSIGHTS_RETENTION_DAYS', 90);

Manual Purge

# Purge data older than 90 days
wp apex-insights prune --days=90

# Purge all data (destructive!)
wp apex-insights prune --days=0 --yes

The AI query engine lets you ask questions about your analytics data in plain English. Navigate to Insights → Ask AI or use WP-CLI.

Example Queries

• "Which pages lost the most traffic last month?"
• "What content is cannibalizing my rankings?"
• "Show me top revenue drivers this quarter"
• "Which traffic sources have the best conversion rate?"
• "What's my average session duration by device type?"

# Query via WP-CLI
wp apex-insights query "Which pages lost the most traffic last month?"

# Output as JSON for scripting
wp apex-insights query "top 10 pages by views" --format=json

Apex Insights automatically monitors all published content for signs of decay — declining traffic, engagement, or ranking position over time.

Detection Algorithm

The decay detector compares each page's metrics over a rolling 30-day window against its historical baseline (90-day average). A page is flagged as "decaying" when:

• Traffic drops more than 20% vs. baseline
• Average time-on-page drops more than 15%
• Bounce rate increases more than 10 percentage points

// Adjust decay detection thresholds
add_filter('apex_insights_decay_thresholds', function ($thresholds) {
    $thresholds['traffic_drop']    = 25; // percent
    $thresholds['engagement_drop'] = 20; // percent
    $thresholds['bounce_increase'] = 15; // percentage points
    return $thresholds;
});

Keyword cannibalization occurs when multiple pages on your site compete for the same search terms, diluting your ranking potential.

Apex Insights analyzes page titles, meta descriptions, headings, and content to identify keyword clusters where multiple pages overlap. Each cluster is assigned a severity level:

• High — 3+ pages targeting the same primary keyword
• Medium — 2 pages with significant content overlap
• Low — Minor overlap, likely not impacting rankings

Navigate to Insights → Content → Cannibalization to view detected clusters and resolution recommendations (consolidate, redirect, or differentiate).

Apex Insights surfaces AI-generated recommendations in the dashboard. These are categorized by type:

Type	Description	Example
Content Refresh	Pages showing decay signals	"Update /blog/wp-speed-guide — traffic down 42% in 30 days"
Consolidation	Pages cannibalizing each other	"Merge /blog/redis-caching and /blog/object-cache-guide"
Opportunity	Traffic or conversion opportunities	"/pricing converts at 4.8% — consider A/B testing the CTA"
Technical	Data quality or performance issues	"Bot traffic from 45.x.x.x inflating /api/ pageviews"

Recommendations can be dismissed, snoozed (7/30/90 days), or marked as resolved.

wp apex-insights report

# Default: last 30 days, table format
wp apex-insights report

# Custom period and format
wp apex-insights report --period=7d --format=json

# Content decay report
wp apex-insights report --type=decay --period=90d

wp apex-insights export

# Export page views as CSV
wp apex-insights export --format=csv --from=2024-01-01 --to=2024-03-31 > pageviews.csv

# Export all data as JSON
wp apex-insights export --format=json --type=all

wp apex-insights query

# Natural language query
wp apex-insights query "top 5 pages by bounce rate this month"

# Structured output
wp apex-insights query "revenue by source" --format=table

Hook	Fired When	Parameters
apex_insights_pageview	A page view is recorded	$page_data
apex_insights_event	A custom event is tracked	$event_name, $event_data
apex_insights_woo_purchase	WooCommerce purchase completes	$order_id, $order_data
apex_insights_decay_detected	Content decay is detected	$page_id, $metrics

// Example: Send Slack notification on content decay
add_action('apex_insights_decay_detected', function ($page_id, $metrics) {
    $title = get_the_title($page_id);
    $url   = get_permalink($page_id);
    $drop  = $metrics['traffic_change'];
    
    wp_remote_post(SLACK_WEBHOOK_URL, [
        'body' => json_encode([
            'text' => "⚠️ Content decay: {$title} ({$drop}%) — {$url}",
        ]),
    ]);
}, 10, 2);

Filter	Description	Parameters
apex_insights_should_track	Whether to record this page view	$should, $request
apex_insights_exclude_paths	URL paths to exclude from tracking	$paths
apex_insights_visitor_data	Modify visitor data before storage	$data
apex_insights_ai_context	Add context to AI queries	$context, $query

// Exclude specific paths from tracking
add_filter('apex_insights_exclude_paths', function ($paths) {
    $paths[] = '/wp-json/';
    $paths[] = '/wp-cron.php';
    $paths[] = '/xmlrpc.php';
    return $paths;
});

Apex Insights provides a REST API at /wp-json/apex-insights/v1/. All endpoints require authentication via WordPress application passwords or nonce-based authentication.

# Example: Authenticate with application password
curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  https://example.com/wp-json/apex-insights/v1/visitors

All responses use JSON format with consistent pagination:

{
  "data": [...],
  "meta": {
    "total": 1234,
    "page": 1,
    "per_page": 50,
    "total_pages": 25
  }
}

Method	Endpoint	Description
GET	/visitors	Visitor data with date range filters
GET	/pages	Page performance metrics
GET	/sources	Traffic source breakdown
GET	/commerce/funnel	WooCommerce conversion funnel
POST	/query	AI natural language query

GET /visitors

curl -u "admin:app_password" \
  "https://example.com/wp-json/apex-insights/v1/visitors?from=2024-01-01&to=2024-01-31&per_page=10"

Parameters: from, to (date), page, per_page, order (asc/desc).

POST /query

curl -X POST -u "admin:app_password" \
  -H "Content-Type: application/json" \
  -d '{"question": "Which pages lost the most traffic last month?"}' \
  "https://example.com/wp-json/apex-insights/v1/query"

For high-traffic sites (100k+ daily page views), consider these optimizations:

// Reduce retention to 90 days
define('APEX_INSIGHTS_RETENTION_DAYS', 90);

// Disable product impression tracking (expensive on large catalogs)
define('APEX_INSIGHTS_WOO_IMPRESSIONS', false);

// Batch database writes (reduces INSERT frequency)
define('APEX_INSIGHTS_BATCH_SIZE', 50);
define('APEX_INSIGHTS_BATCH_INTERVAL', 60); // seconds

Database Indexing

Apex Insights creates optimized indexes on its tables during installation. If you encounter slow queries, verify indexes exist:

wp db query "SHOW INDEX FROM wp_apex_insights_pageviews"