View Categories

Installation Guide

7 min read

This guide covers the complete installation process for TrustLens, including system requirements, installation methods, post-activation setup, and troubleshooting common issues.

System Requirements #

Before installing, verify your hosting environment meets these requirements:

Component Minimum Recommended Notes
WordPress 6.4 6.8+ Tested up to WordPress 6.9
WooCommerce 8.0 9.5+ Required dependency; HPOS supported
PHP 7.4 8.1+ PHP 8.x provides better performance
MySQL 5.6 8.0+ Or MariaDB 10.1+ (10.6+ recommended)
PHP Memory Limit 128 MB 256 MB+ Higher recommended for large historical syncs
Action Scheduler Bundled — Provided by WooCommerce; required for background scoring

Checking Your Environment #

To verify your current versions:

  1. Go to Tools → Site Health in your WordPress admin
  2. Click the Info tab
  3. Check the Server section for PHP and MySQL versions
  4. Check WordPress and Active Plugins sections for WordPress and WooCommerce versions

Installation Methods #

Method 1: Install from WordPress.org (Recommended) #

The simplest installation method for most users:

  1. Log in to your WordPress admin dashboard
  2. Navigate to Plugins → Add New
  3. In the search box, type “TrustLens”
  4. Locate the plugin by Webstepper and click Install Now
  5. Wait for installation to complete
  6. Click Activate

WooCommerce must already be installed and active; the plugin checks for it on activation and will not load if WooCommerce is missing.

Method 2: Upload via WordPress Admin #

Use this method if you downloaded the plugin as a ZIP file:

  1. Download the plugin ZIP from WordPress.org or your purchase receipt
  2. Log in to your WordPress admin dashboard
  3. Navigate to Plugins → Add New
  4. Click the Upload Plugin button at the top
  5. Click Choose File and select the downloaded ZIP
  6. Click Install Now
  7. After installation completes, click Activate Plugin

Method 3: Manual FTP/SFTP Upload #

For advanced users or when other methods fail:

  1. Download the plugin ZIP and extract it on your computer
  2. Connect to your server using an FTP client (FileZilla, Cyberduck, etc.)
  3. Navigate to your WordPress installation’s /wp-content/plugins/ directory
  4. Upload the entire trustlens folder
  5. Log in to your WordPress admin dashboard
  6. Navigate to Plugins → Installed Plugins
  7. Find “TrustLens” in the list and click Activate

What Happens on Activation #

TrustLens performs several setup tasks the first time it’s activated:

  1. Database tables created — {prefix}trustlens_customers, {prefix}trustlens_events, {prefix}trustlens_signals, and supporting tables for linked accounts, fingerprints, automation logs, and velocity tracking
  2. Default options written — sensible defaults for scoring thresholds, card-testing velocity windows, and module toggles
  3. All eight detection modules enabled — including Card-Testing Defense, which starts protecting checkout immediately with no configuration
  4. HMAC keys generated — keyed-hash secrets are created and stored so customer identifiers and linked-account fingerprints are pseudonymized from the first request
  5. Activation summary email queued — sent to the admin email shortly after activation
  6. HPOS compatibility declared — TrustLens registers as HPOS-compatible so WooCommerce’s HPOS check passes cleanly

No customer data is collected or sent externally during activation. All scoring and detection runs inside your install.

Verifying Installation #

After activation, confirm the plugin is working correctly:

  1. Look for the new TrustLens menu item in your WordPress admin sidebar (positioned just after WooCommerce)
  2. Click TrustLens → Dashboard
  3. You should see the Command Center with:
    • Trust score health card
    • Segment distribution row (VIP / Trusted / Normal / Caution / Risk / Critical)
    • Chargeback Ratio Speedometer
    • Module status pills
    • High-risk customer list (will be empty until you run Historical Sync)
    • Historical Sync banner with a Run Historical Sync button

Admin Menu Structure #

Menu Item Description Availability
Dashboard Command Center — scores, segments, KPIs, high-risk list All users with manage_woocommerce
Customers Searchable customer list with trust scores, segments, and bulk actions All users
Notifications Email notification settings and history All users
Automation Trigger-based automation rules Pro only (Free shows upsell screen)
Chargeback Monitor Per-brand ratio breakdown, trend chart, dispute feed, evidence reports Pro only
Card Testing Velocity events, attack history, allowlists, panic button All users; Pro tabs gated by license
Settings General, modules, chargebacks, payment controls, data, API, reports All users

First-Run Configuration #

TrustLens ships with production-ready defaults, so the only mandatory first-run step is running Historical Sync. Optional configuration can be done later.

Step 1: Run Historical Sync #

Without Historical Sync, TrustLens only sees customer behavior from activation onward. Sync reads your existing WooCommerce orders, refunds, and disputes in small background batches and builds trust profiles for every past customer.

  1. Open TrustLens → Dashboard
  2. Click Run Historical Sync in the banner at the top
  3. Confirm. The sync queues a series of Action Scheduler jobs and starts processing immediately.
  4. You can leave the page — the sync runs in the background
  5. Progress is shown on the Dashboard. For stores with thousands of orders, full sync may take several hours; nothing else is blocked.

Step 2: Review Scoring Settings (Optional) #

Defaults work for most stores. To adjust:

  1. Go to TrustLens → Settings → General
  2. Adjust Minimum orders for scoring (default 3) — customers below this stay in Normal regardless of signals
  3. Adjust Return-risk thresholds for elevated / high / very-high tiers
  4. Toggle Checkout blocking — off by default in Free; you decide when to enable
  5. Save

Step 3: Module Toggles (Optional) #

All eight detection modules are enabled by default. To disable a module:

  1. Go to TrustLens → Settings → Modules
  2. Toggle off any module you don’t want contributing signals
  3. Save

Card-Testing Defense ships enabled with sensible thresholds. You don’t need to configure anything to start blocking stolen-card attacks at checkout.

Upgrading to Pro #

Unlock Pro features without reinstalling:

  1. Click the Upgrade link in the TrustLens admin header, or visit the Pricing page in your admin
  2. Select your preferred license plan
  3. Complete the purchase
  4. Your license activates automatically via Freemius — Pro features unlock immediately

Pro unlocks: Chargeback Monitor page, Automation Rules engine, Card-Testing Pro (auto-escalation, geo-diversity, allowlists, attack history), Payment Method Controls, Scheduled Reports, 10 advanced notification types, and Slack alerts. See Free vs Pro Features for the full breakdown.

Troubleshooting Installation Issues #

“TrustLens requires WooCommerce” Notice #

Cause: WooCommerce is not installed or not active.

Fix: Install and activate WooCommerce from Plugins → Add New, then reactivate TrustLens. The plugin will not load without WooCommerce.

TrustLens Menu Not Appearing #

Possible causes:

  • Insufficient permissions: The menu requires the manage_woocommerce capability. Administrator and Shop Manager roles have this by default.
  • WooCommerce inactive: The plugin self-disables if WooCommerce is missing.
  • Cache: Clear caching plugins and hard-refresh (Ctrl+Shift+R / Cmd+Shift+R).

Historical Sync Not Starting #

Possible causes:

  • Action Scheduler not processing: Visit WooCommerce → Status → Scheduled Actions. If the queue is stalled, run pending actions manually or check that WP-Cron is firing (some hosts disable it; you may need a real cron job hitting wp-cron.php).
  • Memory limit too low: Stores with many orders need at least 256 MB. Add to wp-config.php: define('WP_MEMORY_LIMIT', '256M');
  • HPOS migration in progress: If WooCommerce is mid-HPOS-migration, wait for it to finish before syncing.

White Screen After Activation #

Possible causes:

  • PHP version too low: Verify PHP 7.4+ is running. Update through your hosting control panel.
  • Memory limit exhausted: Add to wp-config.php: define('WP_MEMORY_LIMIT', '256M');
  • PHP fatal error: Enable WP_DEBUG to see the specific error: 
    define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

    Check /wp-content/debug.log for details.

Plugin Conflict #

Diagnosis steps:

  1. Deactivate other fraud/security plugins temporarily
  2. Switch to a default theme (Twenty Twenty-Four)
  3. Test whether the issue persists
  4. Reactivate plugins one at a time to identify the conflict
  5. Report conflicts to support with specific plugin names

Card-Testing Defense Blocking Legitimate Customers #

If real customers report checkout errors after activation:

  • Check TrustLens → Card Testing for recent decline events
  • VIP customer bypass is on by default — if a VIP is still blocked, confirm their trust score and segment
  • Pro users: add the customer’s fingerprint or IP to the allowlist
  • Lower velocity sensitivity in Settings → Modules → Card Testing if your store has unusually bursty legitimate traffic

Uninstalling the Plugin #

Deactivation (Preserves Data) #

  1. Navigate to Plugins → Installed Plugins
  2. Find “TrustLens”
  3. Click Deactivate

All customer trust data, signals, automation logs, and settings remain in the database. Reactivating restores everything.

Complete Removal (Deletes Data) #

To remove all plugin data on uninstall:

  1. Navigate to TrustLens → Settings → Data
  2. Enable “Delete all data on uninstall”
  3. Save settings
  4. Go to Plugins → Installed Plugins, deactivate, then click Delete

Warning: This permanently removes all trust profiles, signal history, automation logs, and chargeback records. This action cannot be undone. Linked-account fingerprints and HMAC secrets are also wiped.

Updated on June 4, 2026

What are your Feelings

  • Happy
  • Normal
  • Sad