Installation Guide

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 7.1
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 the refund ledger, category and product stats, fingerprints (linked accounts), disputes, velocity tracking, automation and webhook logs, refund cases and the Store Trust Network
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. Pseudonymization ready — no separate keys are generated: customer identifiers and linked-account fingerprints are hashed with keyed HMAC-SHA256 using your site’s existing WordPress auth secret key, from the first request
5. Welcome summary email scheduled — sent to the notification email 24 hours after activation (once TrustLens has customers to report on)
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. On a new install you should see the Quick start card and a Get Started with TrustLens screen with a Start Historical Sync button (and a Skip and analyze new orders only link)
4. Once customers exist, the Dashboard shows the Command Center with:
   • Trust Index (average trust score) with a 30-day trend
   • Customer Segments distribution (VIP / Trusted / Normal / Caution / Risk / Critical)
   • Live telemetry and Card-Testing Defense tiles
   • Detection Modules status (8 modules on/off)
   • Priority Targets high-risk customer list
   • Chargeback Ratio Monitor (Pro; Free shows an upgrade card, plus an alert band if your ratio crosses a card-network line)
   • A Historical Data Sync card showing whether past orders have been imported

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, bulk actions, and CSV export	All users
Refund Cases	Refund Defense case inbox	Pro only (hidden on Free)
Chargeback Monitor	Per-network ratio breakdown, trend chart, open-disputes worklist, dispute feed, evidence reports	Pro only (Free shows upsell screen)
Card-Testing Defense	Velocity thresholds, Panic Freeze, browser challenge; Pro allowlists and 24-hour attack intelligence	All users; Pro sections gated by license
Automation	Trigger-based automation rules	Pro only (Free shows upsell screen)
Settings	General, Detection, Refunds, Payments (Pro), Alerts & Reports (notifications and scheduled reports), Integrations (webhooks, REST API, Store Network), Data	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 coupon use in small batches and builds trust profiles for every past customer. (Past disputes aren’t imported; record any you need with the manual chargeback form on the order screen.)

1. Open TrustLens → Dashboard
2. Click Start Historical Sync
3. The sync starts processing immediately, a small batch of orders at a time
4. Keep a TrustLens page open while it runs — the batches are sent from your browser. If you navigate away, the sync pauses and picks up again the next time you open the Dashboard or Settings → Data
5. Progress is shown on the Dashboard. For stores with thousands of orders, full sync may take several hours; your storefront is not affected.

If you’d rather not import history, click Skip and analyze new orders only instead; you can import past orders later.

Step 2: Review Scoring Settings (Optional) #

Defaults work for most stores. To adjust:

1. Go to TrustLens → Settings → General
2. Adjust the Full-confidence Order Threshold (default 3) — below this, most detection modules wait for more history and return risk is confidence-weighted
3. Toggle Enable Blocking — off by default; you decide when to enable
4. Save
5. To change the return-rate levels, open Settings → Refunds and adjust High risk (default 40%) and Critical risk (default 60%)

Step 3: Module Toggles (Optional) #

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

1. Go to TrustLens → Settings → Detection
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:

• Sync page closed: Historical Sync started from the admin runs in small batches sent by your browser. If progress has stopped, open TrustLens → Dashboard or Settings → Data and leave it open — the sync resumes from where it stopped. If it still won’t move, check that a security plugin or firewall isn’t blocking admin-ajax.php requests.
• 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 Defense for recent decline events
• VIP customer bypass is on by default and covers established customers (at least 3 orders by default, not in Risk or Critical) — if a regular customer is still blocked, confirm their order count and segment, and check that Panic Freeze isn’t active (a freeze blocks everyone)
• Release a held device from the Card-Testing Defense page to clear its lockout
• Pro users: add the customer’s fingerprint or IP to the allowlist
• Lower velocity sensitivity in TrustLens → Card-Testing Defense 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. Under Uninstall Behavior, turn on “Remove all TrustLens data when plugin is deleted”
3. Save settings
4. Go to Plugins → Installed Plugins, deactivate, then click Delete

Warning: This permanently removes every TrustLens table — trust profiles, signal and event history, the refund ledger, linked-account fingerprints, dispute records and automation logs — plus all TrustLens settings. This action cannot be undone. (The small TrustLens markers stored on WooCommerce orders themselves are left in place.)