Must-Have Analytics Documentation

Current Version: 0.1.2
Text Domain: mhanalytics

Must‑Have Analytics is a privacy‑focused, performance‑optimized analytics solution for WordPress.

Unlike cloud‑based services, your data stays on your server. No data sharing with third parties, and full GDPR compliance out of the box.

Track visitors, analyze behavior, measure conversions, and export audiences—all while respecting user privacy.

Installation & Licensing

Installation

Must‑Have Analytics is a WordPress plugin that can be installed like any other plugin.

Via WordPress Admin:

  1. Download the plugin ZIP file from your purchase email or account
  2. Go to WordPress Admin → Plugins → Add New → Upload Plugin
  3. Choose the ZIP file and click Install Now
  4. After installation, click Activate Plugin

Via FTP:

  1. Extract the plugin ZIP file
  2. Upload the must-have-analytics folder to /wp-content/plugins/
  3. Go to WordPress Admin → Plugins and activate Must‑Have Analytics

License Activation

After installation, the plugin automatically redirects you to musthaveplugins.com for authentication.

You authenticate with your Must‑Have Plugins account, and the system automatically activates your license and redirects you back to your WordPress dashboard.

No license key needed—just log in to your account and your site is activated.

You can also manually access license management via Must‑Have Analytics → Settings → License if you need to reactivate later.

Your license allows installation on the number of sites specified in your plan (Single: 1 site, Multi: 5 sites, Must-Have Pack: unlimited sites).

System Requirements

  • Minimum: WordPress 5.8+, PHP 7.4+, MySQL 5.7+ / MariaDB 10.2+, 128MB memory
  • Recommended: WordPress 6.0+, PHP 8.0+, MySQL 8.0+ / MariaDB 10.5+, 256MB memory

How It Works

Must‑Have Analytics tracks visitor behavior using a lightweight JavaScript tracker that runs on every page of your site.

When a visitor loads a page, the tracker collects information about the visit and sends it to your WordPress site via a REST API endpoint.

When cookie tracking is enabled (Settings → General → Tracking Cookie), the plugin sets a first-party cookie named _mhanalytics.

This cookie contains a unique visitor identifier that persists across sessions. This allows the plugin to recognize returning visitors and stitch together their journey over time.

The cookie is set with a 365‑day (1 year) expiration by default. It's a first‑party cookie (set by your domain), so it's not affected by third‑party cookie blocking.

If cookie tracking is disabled, the plugin uses device fingerprinting to identify returning visitors.

The fingerprint is created from: IP address (anonymized if profiling is off) and other device identifiers.

This method is less accurate than cookies but still provides useful insights. Sessions are linked by device fingerprint within a 20‑minute window (without cookie).

Entity Profiling (Optional)

When enabled, the plugin collects personally identifiable information to build rich visitor profiles.

Profile data includes: email addresses, phone numbers, first names, last names, full IP addresses (not anonymized), complete browsing history.

This data is collected from user‑provided data such as forms, checkout processes, user registrations, and any other input where visitors share their information.

When profiling is disabled, all IP addresses are anonymized (last octet removed) and no personal data is stored.

GDPR Compliance: Although not visible to site visitors, profiling should only be enabled after obtaining user consent. If your site operates under GDPR, you can conditionally disable profiling based on user consent using a filter::

add_filter('mhanalytics_option_profiling', function($result) {
    if (!isset($_COOKIE['your_custom_profiling_consent_cookie'])) {
        return '';
    }
    return $result;
});

Data Retention

Raw analytics data (visits, events, sessions) is retained for the period specified in Settings → General → Raw Data Retention (default: 24 months).

After this period, data is automatically deleted. This helps comply with GDPR requirements for data minimization.

Profiling data has its own expiration set via the valid_until field. You can export or delete data at any time via Settings → System.

How Goals Work

Goals are conversion events you define using conditions. When a visitor performs an action that matches all conditions, the goal is achieved.

Goals are evaluated in real time for every event. The plugin loads active goals, checks each condition, applies the logic, and records achievements.

Goal achievements can trigger: server‑side conversions to Meta or TikTok, monetary value tracking, remarketing list inclusion.

Data Flow

Here's how data flows through the system:

  1. Visitor loads the page → tracker script is initialized.
  2. After a certain time (depending on the browser and other conditions), the script sends an event to the REST API.
  3. When the visitor navigates away or closes the tab, the tracker sends all event data to the REST API (/wp-json/mh-analytics/v1/event).
  4. The event processor validates and enriches the data (geolocation, device detection).
  5. Entity Resolution (if profiling is enabled). It identifies or creates a visitor entity based on available identifiers (cookies, user ID, profiling data).
  6. A session is created or extended based on timeframe rules.
  7. The goal evaluator checks whether any goals have been achieved.
  8. If a goal has been achieved, conversion APIs are triggered (Meta/TikTok).
  9. Data is stored in normalized database tables.

Dashboard

The Dashboard is your central hub for monitoring site performance at a glance.

Access it via WordPress Admin → Must‑Have Analytics. The dashboard displays key metrics and visualizations in customizable widgets.

Available Widgets

  • Active Sessions Timeline: Real‑time count of currently active visitors on your site with a timeline chart showing visitor activity over time
  • Visitors Chart: Visualizes pageviews and unique visitors for the selected date range with interactive trend charts. Toggle between different time periods and view daily, weekly, or monthly trends
  • Top Pages: Lists the most visited pages with pageview counts. Click on any page to view detailed analytics for that specific URL
  • Top Landing Pages: Shows which pages visitors land on when first arriving at your site. Helps identify your most effective entry points
  • Top Exit Pages: Displays which pages visitors leave from. Useful for identifying potential issues or natural exit points in your user journey
  • Top Referrals: Shows where your traffic comes from—direct visits, search engines, referral sites, or social media. Each traffic source is categorized and counted
  • Device Breakdown: Breakdown by device type (desktop, mobile, tablet, wearable, TV, console). Visualized as a pie chart with detailed percentages
  • Top Countries: Geographic distribution of your visitors with country names and visit counts. Shows which regions generate the most traffic
  • Latest Goals: Recent goal achievements with timestamps and associated values. Shows the most recent conversions across all your defined goals
  • Bot Traffic: Lists detected bot traffic by user agent with hit counts. Helps identify crawler activity and distinguish it from human visitors
  • Speed Metrics: Displays Core Web Vitals and performance metrics including LCP (Largest Contentful Paint), FCP (First Contentful Paint), FID (First Input Delay), CLS (Cumulative Layout Shift), TTFB (Time to First Byte), and Cache Hit Rate. Visual indicators show whether your site meets performance thresholds

Customizing Your Dashboard

You can fully customize the dashboard layout to match your workflow.

Reordering Widgets: Click and drag any widget by its title bar to move it to a new position. The layout is saved automatically and persists across sessions.

Show/Hide Widgets: Click the Screen Options button in the top‑right corner. Check or uncheck widgets to show or hide them. Hidden widgets can be re‑enabled at any time.

Your dashboard preferences are saved per user, so each admin can have their own personalized view.

Features

Must‑Have Analytics provides a comprehensive suite of analytics and marketing tools.

Real‑Time Tracking

See who's on your site right now. The Active Sessions widget updates automatically to show current visitors and what pages they're viewing.

Click on any active session to see the full visitor journey in real time.

Advanced Reporting

Generate detailed reports on pageviews, sessions, entities, traffic sources, devices, countries, and more. See Reports section for complete list.

Every report includes: sortable/filterable tables, date range selection, search functionality, pagination, export to CSV/Excel/PDF.

Selected columns show sum or average at the top for quick insights. All charts can be saved as PNG images for presentations.

Trend Charts

Visualize data over time with line charts for time‑series analysis.

Charts display metrics over time with date grouping options (day, week, month). Multiple data series can be displayed on the same chart for comparison.

All charts are interactive with tooltips showing exact values. Charts can be downloaded as high‑resolution PNG images.

Export Capabilities

Export any report to CSV, Excel (XLSX), or PDF formats.

Click the Export button on any report to choose your format. The export includes all filtered data (respecting any search or date range filters you've applied).

Charts can be saved as high‑resolution PNG images. Right‑click any chart and select Save Chart as Image.

Remarketing List Export

Build custom audiences for your ad campaigns on Meta (Facebook), TikTok, or Google Ads.

Define segments based on: pages visited, goals achieved, traffic source, device type, country, date range.

Export audience lists with properly hashed emails and phone numbers (as required by each platform).

Email List Export

Export visitor contact information for email marketing campaigns.

Generate CSV files with email addresses, first names, and last names. Perfect for importing into Mailchimp, ConvertKit, or any email service provider.

Correlation Analysis

Discover which attributes drive conversions using statistical analysis. See Correlation Analysis section for detailed metrics explanation.

The correlation analyzer compares conversion rates across 8 dimensions (traffic sources, countries, devices, landing pages, time of day, day of week, day of month, month) to find statistically significant differences.

Results show Δ percentage points, lift multipliers, z‑scores, p‑values, and significance indicators. For example: visitors from Google convert 2.3pp higher (82% lift) with p = 0.0001 (highly significant).

Sankey Flow Visualization

Visualize the complete visitor journey from traffic source through pages to goal conversion. See Sankey Flow section for detailed usage.

The Sankey diagram shows: where visitors come from, which pages they visit (in sequence), where they drop off, which paths lead to conversions.

Use this to identify bottlenecks in your funnel and optimize the user experience.

Goals & Conversions

Define conversion goals with custom conditions using drag‑and‑drop components. See Goals section for all 26 condition types.

Goals support 26 condition types from 4 categories: Content (URL, referrer, landing page, element visible, media play), User (returning visitor, logged‑in user, country, device, OS, user agent), Engagement (scroll, click, form, time on page/site, visited pages), Advanced (WordPress actions), plus 8 WooCommerce‑specific conditions when WooCommerce is active.

Goals can trigger server‑side conversion events to Meta/TikTok, track monetary value, count unique achievements, and be used for segmentation.

Server‑Side Conversion Tracking

Send conversion events directly from your server to Meta and TikTok, bypassing ad blockers and iOS privacy restrictions. See Conversion APIs section for setup guides.

This ensures accurate attribution for your ad campaigns even when client‑side tracking is blocked or limited.

Entities

Entities are unique visitor profiles that persist across sessions and devices.

Think of an entity like a shipping address. Multiple people in the same household can share one shipping address, and one person can have multiple addresses (home, work, etc).

Similarly, an entity typically represents one person, but it's not always a perfect 1:1 relationship.

Why Entities Aren't Always 1 Person

The entity tracking system aims to identify unique individuals, but it's not always a perfect 1:1 relationship.

One person can have multiple entities: The system cannot always link a user's different devices together. If someone doesn't log in on both their phone and laptop, these may be tracked as separate entities.

One entity can represent multiple people: If users don't accept cookies, device fingerprinting is used as a fallback. In offices or households, two devices with very similar configurations (same browser, OS, IP address) can be mistakenly identified as the same entity.

Despite these edge cases, entity tracking provides significantly more accurate insights than session‑based analytics alone.

Entity Profiles

When profiling is enabled, entities can accumulate rich profile data over time.

Profile data includes: email address, phone number, first name, last name, full IP address history, all sessions and visits, all achieved goals, total conversion value.

This data is collected from: user registrations, WooCommerce checkouts, contact form submissions, newsletter signups, any form with email/phone/name fields.

Viewing Entities

Navigate to Must‑Have Analytics → Entities to see all tracked entities.

The entity list shows: unique identifier, first seen date, last seen date, total sessions, total pageviews, email (if known), location (country/city), device type, and more detailed information.

Click any entity to view complete details including: session history, all visited pages, achieved goals, profile information (multiple emails, names, phone numbers, addresses can be associated with one entity), device information, and timeline of activity.

Sessions

A session represents a single visit to your site. It starts when a visitor arrives and ends after a period of inactivity.

When cookie tracking is enabled, sessions are managed using the _mhanalytics cookie.

Session timeout is 60 minutes. A new session starts when the visitor doesn't have the cookie yet, or when the last activity was more than 60 minutes ago.

Every pageview extends the session timeout by another 60 minutes. So a visitor actively browsing your site stays in the same session.

Without cookies, the plugin uses device fingerprinting to identify returning visitors. The fingerprint combines: IP address (anonymized if profiling is disabled), User Agent string, and HTTP headers (Accept‑Language, Accept‑Encoding).

Session timeframes without cookies: 20 minutes using device fingerprint only. With profiling enabled and an entity identified, sessions can be extended up to 60 minutes.

This method is less accurate than cookies because fingerprints can collide (multiple users with similar configurations) or change based on browser settings.

Session Timeframes

Different identification methods have different timeout windows:

  • Cookie (_mhanalytics): 60 minutes
  • Device fingerprint (without profiling): 20 minutes
  • Device fingerprint (with profiling): 20‑60 minutes

These timeframes can be customized with WordPress filters (mhanalytics/session_cookie_timeframe, mhanalytics/session_device_timeframe, mhanalytics/session_profile_timeframe).

Viewing Sessions

Navigate to Must‑Have Analytics → Sessions to see all recorded sessions.

The session list shows: session ID, entity (if identified), start time, duration, pageviews, entry page, exit page, traffic source, device, location.

Click any session to see: complete pageview timeline with timestamps, events (form submissions, clicks, etc), achieved goals, referrer information.

Active Sessions

The plugin tracks real‑time sessions. A session is considered active if there was activity within the last 15 minutes.

View active sessions on the Dashboard widget or via Must‑Have Analytics → Sessions → Active Sessions tab.

Reports

Reports provide detailed insights into your site's performance and visitor behavior.

Access reports via Must‑Have Analytics → Reports. All reports support filtering by date range, searching, sorting, and exporting.

Available Reports

  • Pageviews: Most visited pages with unique visitors and bounce rates
  • Traffic Sources: Where visitors come from (direct, organic, referral, social, campaign)
  • Devices: Desktop vs mobile vs tablet traffic with metrics
  • Countries: Geographic distribution with conversion rates
  • Browsers: Browser and version breakdown
  • Operating Systems: OS distribution across your visitors
  • Screen Resolutions: Common screen sizes for design optimization
  • Landing Pages: First pages visitors see when arriving
  • Exit Pages: Last pages before visitors leave
  • UTM Campaigns: Campaign performance tracking
  • Bot Traffic: Bot activity analysis and patterns
  • Bounce Rate: Pages with high bounce rates requiring optimization
  • Speed Metrics: Page load performance analysis

WooCommerce Reports (if WooCommerce is active)

  • Purchase Trends: Revenue and order trends over time
  • Top Products: Best‑selling products by revenue and units
  • Product View to Purchase: Conversion rates from product views to purchases
  • Abandoned Carts: Cart abandonment analysis with cart values
  • Coupon Usage: Coupon performance and discount analysis
  • Failed Orders: Failed payment attempts and lost revenue
  • Refunds: Refund rates and amounts by product or period

Using Reports

Select a date range using the date picker. Choose from presets (Today, Yesterday, Last 7 days, Last 30 days, etc) or pick a custom range.

Use the search box to filter results. For example, search for specific page URLs or traffic source names.

Click any column header to sort by that column. Click again to reverse the sort order.

Reports are paginated to 20 rows per page by default. Use Previous/Next buttons to navigate, or adjust the rows per page in the dropdown selector.

Column Aggregation: For selected columns, the sum or average is displayed at the top of the column. This provides quick insights into totals (e.g., total revenue, total pageviews) and averages (e.g., average order value, average time on page).

Charts: Certain reports include visual charts above the table data to help you quickly identify trends and patterns. For example, Purchase Trends shows a line chart of revenue over time.

Exporting Reports

Every report can be exported in three formats:

  • CSV: Universal format for Excel, Google Sheets, or any spreadsheet tool
  • Excel (XLSX): Native Excel format with formatting and proper column types
  • PDF: Professional reports with charts and tables for sharing

Click the Export button, choose your format, and the file downloads immediately. The export includes all filtered data (respecting search and date filters).

Goals

Goals allow you to define and track conversions automatically. Set up goals for purchases, sign-ups, downloads, or any other valuable action on your site.

Creating a Goal

Navigate to Must‑Have Analytics → Goals and click Add New Goal.

Goal Name: Give your goal a descriptive name (e.g., "Purchase Complete", "Newsletter Signup", "Free Trial Started").

Goal Value: Optional monetary value representing the conversion worth (e.g., $99.99 for product purchase, $50 for estimated lead value). Leave blank if no specific value.

Unique Goal: Toggle this option to count each goal only once per visitor. If enabled, a visitor can only achieve this goal once in their lifetime. Use for one‑time events like account registration.

Status: Toggle between Active (tracking), Inactive (paused), or Archived (hidden from main list). Only Active goals are evaluated.

Adding Conditions

Conditions define when a goal is achieved. The Goal Editor shows available condition components in the sidebar, organized by category.

Adding a Condition: Either drag a component from the sidebar into the condition area, or double‑click a component to add it instantly.

Available Condition Types

Content Conditions:

  • URL Visited: Match page URLs with operators (is, contains, starts with, ends with, regex)
  • Referrer: Match referrer URLs to track traffic sources
  • Landing Page: Specific entry page URL
  • Element Visible: CSS selector for visible element detection
  • Media Play: Track video/audio playback events

User Conditions:

  • Returning Visitor: New vs returning visitor
  • Logged‑in User: WordPress user login status or specific roles
  • Country: Geographic targeting (select countries from list)
  • Device Type: Desktop, mobile, or tablet
  • OS: Operating system (Windows, macOS, iOS, Android, Linux, etc)
  • User Agent: Browser user agent string matching

Engagement Conditions:

  • Scroll Percent: Percentage scrolled on a page
  • Click Element: CSS selector for clicked element
  • Form Interaction: Form submission or field interaction
  • Time on Page: Minimum seconds spent on current page
  • Time on Site: Total session duration in seconds
  • Visited Pages: Number of pages viewed in session

Advanced Conditions:

  • WordPress Action: Custom WordPress hook/action trigger

WooCommerce Conditions (if WooCommerce is active):

  • Add to Cart: Product added to cart. Can filter by specific products or minimum/maximum value. Within one condition: OR relationship for products (any selected product triggers), AND relationship for value constraints (must meet min/max if specified).
  • Initiate Checkout: Checkout process started
  • Checkout: Purchase completed. Can filter by products or order value. Same OR/AND logic as Add to Cart.
  • Abandoned Cart: Cart abandoned without purchase
  • Coupon Added: Coupon code applied to cart
  • Coupon Used: Order completed with coupon
  • Failed Order: Payment failed
  • Add Payment Info: Payment method entered

Condition Logic (AND Only)

Important: Conditions are ALWAYS evaluated with AND logic. All conditions must be true for the goal to be achieved.

If you add 3 conditions (e.g., URL contains "/thank-you" + Country is "United States" + Device is "Mobile"), the visitor must meet ALL THREE conditions.

OR Logic Within Conditions: Some individual conditions support multiple values with OR logic. For example:

  • Country condition with multiple countries: Visitor from USA OR Canada OR UK (any of the selected countries)
  • WooCommerce Checkout with products: Product A OR Product B OR Product C (any of the selected products)

AND Logic Within Conditions: Some conditions combine multiple criteria types with AND logic. For example:

  • WooCommerce Checkout with products AND minimum value: (Product A OR Product B) AND (Order Value >= $50)

Deleting and Deactivating Goals

Deactivate: Set goal status to Inactive to pause tracking without losing data. Achievements stop being recorded but historical data remains.

Archive: Set status to Archived to remove from main list while preserving data for reports.

Delete: Click the Delete button to permanently remove the goal. This cannot be undone and all historical achievement data is lost.

Conversion API Integration

Link goals to ad platform conversion events for server‑side tracking. When a goal is achieved, the plugin automatically sends the event to Meta, TikTok, or Google Ads.

Meta (Facebook) Event: Select a Facebook event (Purchase, Lead, CompleteRegistration, AddToCart, InitiateCheckout, etc).

TikTok Event: Select a TikTok event (CompletePayment, SubmitForm, Subscribe, AddToCart, ViewContent, etc).

Google Ads Conversion: Enter the exact conversion action name from Google Ads. The name must match exactly (case‑sensitive) with your Google Ads conversion action name.

Important: Conversion Name Matching Rules:

  • Facebook & TikTok: Select from predefined event list. Event names are standardized by each platform.
  • Google Ads: Enter exact conversion action name as it appears in Google Ads. The name is case‑sensitive and must match precisely for tracking to work.

See the Conversion APIs section below for detailed setup instructions for Meta, TikTok, and Google Ads API credentials. You can also configure API keys in Settings → Conversions Tab.

This enables server‑side conversion tracking that bypasses ad blockers and iOS restrictions, providing accurate attribution for your paid campaigns.

Viewing Goal Performance

The Goals page shows all goals with achievement counts and status indicators. Click any goal to see detailed performance:

  • Achievement timeline (daily/weekly/monthly trends)
  • Conversion rate (% of sessions that achieved the goal)
  • Total value generated
  • Breakdown by traffic source, device type, and country
  • Recent achievements with visitor details

Correlation Analysis

Correlation analysis helps you discover which visitor attributes correlate with higher conversion rates by analyzing segments statistically.

It uses two‑proportion z‑tests to identify segments that convert significantly better or worse than average, helping you optimize marketing spend and targeting.

Running Correlation Analysis

Navigate to Must‑Have Analytics → Tools → Correlation Analysis.

Select the date range you want to analyze. Longer periods (30+ days) provide more statistically reliable results.

Choose the goal you want to optimize for (e.g., "Purchase Complete", "Newsletter Signup"). The analysis shows which segments achieve this goal more frequently.

Click Run Analysis. The plugin calculates conversion rates for each segment across multiple dimensions and compares them to the overall baseline.

Analyzed Dimensions

The analysis examines 8 dimensions simultaneously:

  • Traffic Source: Direct, organic, referral, social, campaign
  • Country: Geographic distribution
  • Device: Desktop vs mobile vs tablet
  • Landing Page: Entry points to your site
  • Time of Day: Hourly breakdown (0-23)
  • Day of Week: Monday through Sunday
  • Day of Month: 1st through 31st
  • Month: January through December

Understanding Results & Metrics

Results are displayed as horizontal bar charts for each dimension, showing Δ percentage points (difference from baseline).

Metrics Displayed:

  • Δpp (Delta Percentage Points): Difference between segment conversion rate and overall average. Example: if segment converts at 5% and average is 3%, Δpp = +2.0
  • Lift: Multiplier showing relative performance. Example: 1.67 means 67% better than average; 0.50 means 50% worse
  • All: Percentage and count of total sessions in this segment
  • Converted: Percentage and count of goal achievements in this segment
  • z (z‑score): Statistical significance measure. Higher absolute values indicate stronger evidence
  • p (p‑value): Probability that difference is due to chance. Lower values indicate stronger evidence (p < 0.05 is typically significant)
  • FDR (False Discovery Rate): Adjusted p‑value accounting for multiple comparisons. More conservative than raw p‑value

Significance Indicators:

  • Significant: The difference is statistically significant (typically p < 0.05 or FDR < 0.05). High confidence that this is a real pattern, not random noise
  • Approximate: Sample size is small, so results are less reliable. Use with caution; collect more data for confidence

Color Coding:

  • Green bars: Segment converts better than average (Δpp > 0)
  • Red bars: Segment converts worse than average (Δpp < 0)

Example Interpretation: "Traffic from Google shows Δpp = +2.3, Lift = 1.82, z = 4.5, p = 0.0001, Significant"

This means: Google traffic converts 2.3 percentage points higher than average (82% better performance), with very high statistical confidence (p = 0.0001).

Using Correlation Insights

Allocate Budget: Increase spend on traffic sources and countries with significant positive lift.

Optimize Timing: Schedule campaigns during high‑converting times of day or days of week.

Improve Landing Pages: Optimize or remove landing pages with significant negative correlation.

Device Targeting: Adjust bids or creative for better‑performing device types.

Avoid Over‑Optimization: Ignore segments marked "approximate" unless you can increase sample size. Focus on significant results with adequate data.

Sankey Flow Visualization

The Sankey diagram visualizes the complete visitor journey from traffic source through pages to goal conversion.

It shows: how visitors arrive (traffic sources), which pages they visit (in order), where they drop off, which paths lead to conversions.

Generating a Sankey Diagram

Navigate to Must‑Have Analytics → Tools → Sankey Flow.

Select your date range (last 7 days, 30 days, or custom range).

Choose the goal you want to track conversions for.

Configure URL grouping options. By default, similar URLs are grouped together (e.g., all product pages grouped as "Product").

You can customize grouping rules: group by URL pattern (regex), group by page type, keep full URLs for specific pages.

Click Generate Diagram. The visualization appears with interactive flows.

Reading the Diagram

The diagram flows from left to right: Traffic Source → First Page → Second Page → ... → Goal Conversion.

Flow thickness represents volume. Wider flows mean more visitors took that path.

Hover over any node (page or source) to see: total visitors, conversion rate, drop‑off rate, most common next steps.

Click any flow to filter the diagram to paths that include that flow.

Using Sankey Insights

Identify drop‑off points where visitors commonly exit without converting. Optimize those pages to reduce friction.

Discover unexpected conversion paths. Sometimes visitors convert through non‑obvious routes you can optimize.

Compare traffic source performance. See which sources bring visitors who navigate effectively vs those who bounce quickly.

UTM Parameters & URL Builder

UTM parameters are tags you add to URLs to track the source, medium, and campaign of your traffic.

They help you measure the effectiveness of specific marketing campaigns and channels.

What Are UTM Parameters?

UTM parameters are query string additions to URLs. For example: https://yoursite.com/?utm_source=facebook&utm_medium=social&utm_campaign=spring_sale

The five standard UTM parameters are:

  • utm_source: Where the traffic comes from (e.g., google, facebook, newsletter)
  • utm_medium: Marketing medium (e.g., cpc, social, email, referral)
  • utm_campaign: Specific campaign name (e.g., spring_sale, product_launch)
  • utm_term: Paid search keywords (optional, for PPC campaigns)
  • utm_content: Differentiate similar content (e.g., banner_ad, text_link)

Using the URL Builder

Navigate to Must‑Have Analytics → Tools → URL Builder.

Enter your website URL (the page you want to link to).

Fill in the UTM parameters: Campaign Source (required), Campaign Medium (required), Campaign Name (required), Campaign Term (optional), Campaign Content (optional).

The builder automatically generates the tagged URL. Copy it and use it in your marketing materials (emails, ads, social posts, etc).

Tracking Campaign Performance

View UTM campaign performance at Must‑Have Analytics → Reports → UTM Campaigns.

The report shows: campaign name, total visits, unique visitors, pageviews per visit, conversion rate, total conversion value.

Compare campaigns to see which marketing efforts drive the best results.

Conversion APIs

Server‑side conversion tracking sends conversion events directly from your WordPress server to Meta (Facebook) and TikTok.

This bypasses ad blockers, iOS privacy restrictions, and browser tracking prevention to ensure accurate attribution for your ad campaigns.

Meta (Facebook) Conversions API

Step 1: Get Your Pixel ID

  1. Go to Facebook Events Manager
  2. Select your pixel or create a new one
  3. Copy the Pixel ID (numeric, usually 15-16 digits)

Step 2: Generate Access Token

  1. In Events Manager, go to Settings → Conversions API
  2. Click Generate Access Token
  3. Copy the token (starts with "EAA...")
  4. Store it securely - you'll only see it once

Step 3: Configure in Plugin

  1. Navigate to Must‑Have Analytics → Settings → Conversions
  2. Paste your Pixel ID in the Meta Pixel ID field
  3. Paste your Access Token in the Meta API Token field
  4. Select which events to track (PageView, Purchase, etc)
  5. Click Save Changes

Step 4: Test Your Integration

Click the Test Event button. The plugin sends a test conversion to Meta. Check Events Manager → Test Events tab to verify it was received.

TikTok Events API

Step 1: Get Your Pixel ID

  1. Go to TikTok Ads Manager (ads.tiktok.com)
  2. Navigate to Assets → Events → Web Events
  3. Select your pixel or create a new one
  4. Copy the Pixel ID

Step 2: Generate Access Token

  1. In the same pixel settings, go to Events API tab
  2. Click Generate Access Token
  3. Copy the token

Step 3: Configure in Plugin

  1. Navigate to Must‑Have Analytics → Settings → Conversions
  2. Paste your Pixel ID in the TikTok Pixel ID field
  3. Paste your Access Token in the TikTok API Token field
  4. Select which events to track
  5. Click Save Changes

Step 4: Test Your Integration

Click the Test Event button. Check TikTok Events Manager → Test Events to verify the event was received.

Google Offline Conversions

Google Ads uses a different approach. You export conversion data from Must‑Have Analytics and upload it to Google Ads manually or via API.

Step 1: Map Your Conversions

  1. Navigate to Must‑Have Analytics → Settings → Conversions → Google Ads
  2. Map your goals to Google conversion actions by entering the exact conversion action name from Google Ads
  3. Important: The conversion action name must match exactly (case‑sensitive) with the name in your Google Ads account
  4. Save your mapping

Step 2: Export Conversion Data

  1. Go to Must‑Have Analytics → Reports → Goal Conversions
  2. Select your date range
  3. Click Export → Google Offline Conversions
  4. Download the CSV file

Step 3: Upload to Google Ads

  1. Go to Google Ads → Tools → Conversions → Uploads
  2. Click the + button and select Import file
  3. Choose your conversion action
  4. Upload the CSV file from Must‑Have Analytics
  5. Review and apply the upload

Google will match conversions using GCLID (Google Click ID) captured by the plugin.

Exports

Must‑Have Analytics provides flexible export options directly within reports for both report data and audience lists.

Report Exports (CSV, Excel, PDF)

Every report includes an Export button in the report controls. Click it to download the current report data in your chosen format:

  • CSV: Universal format compatible with Excel, Google Sheets, or any spreadsheet tool
  • Excel (XLSX): Native Excel format with proper formatting, column types, and styling
  • PDF: Professional document format for presentations and sharing

The export respects your current filters: date range, search terms, and any applied filters are included in the export.

Remarketing & Email List Exports

Reports that track entities (visitor profiles with email/phone data) include additional export options for remarketing and email marketing.

Reports with Entity Export Capability:

  • Sessions Report
  • Goals Report
  • WooCommerce Purchase Trends
  • WooCommerce Abandoned Carts
  • WooCommerce Failed Orders
  • WooCommerce Refunds

These reports display additional export buttons:

Remarketing Export: Generates properly formatted audience files for Meta (Facebook/Instagram), TikTok, or Google Ads. Emails and phone numbers are automatically SHA‑256 hashed as required by ad platforms. Upload the exported file to your ad platform's audience manager to create custom or lookalike audiences.

Email List Export: Exports plain contact information (email address, first name, last name) for use in email marketing platforms like Mailchimp, ConvertKit, or ActiveCampaign.

Both export types respect your current report filters, allowing you to segment audiences based on date range, goals achieved, purchase behavior, or any other criteria available in the report.

Settings

Configure Must‑Have Analytics to match your privacy requirements, tracking preferences, and integration needs.

Access settings via Must‑Have Analytics → Settings. Most settings auto‑save when changed. Tabs: General, Exclusions, Conversions, System.

The license status and activation controls are displayed at the top of the Settings tab, above all other settings.

General Tab

Tracking Cookie: Enable or disable the _mhanalytics first‑party cookie. When enabled, the plugin can accurately track returning visitors across sessions.

When disabled, device fingerprinting is used instead (less accurate but more privacy‑friendly). Most sites should keep this enabled for accurate analytics.

Profiling: Controls whether the plugin collects personally identifiable information (email, phone, names). When enabled, you get detailed visitor profiles from forms and checkouts.

When disabled, only anonymous analytics data is collected and all IP addresses are anonymized.

GDPR Compliance: While the profiling toggle is visible in the UI, enabling it should only be done after obtaining user consent. If your site operates under GDPR, you should conditionally disable profiling based on user consent. See the How It Works section for a code example using the mhanalytics_option_profiling filter.

Conversion Tracking: Enables the Conversions tab in settings where you can configure Meta and TikTok server‑side conversion APIs.

Keep this disabled if you don't use paid advertising. Enable it to unlock conversion API integrations.

Currency: Select your site's currency from the dropdown for monetary value display in reports and goals.

Choose from common currencies (USD, EUR, GBP, CAD, AUD, etc). This doesn't convert currencies, just formats the display.

Email Summary: Automated email reports sent to specified addresses. Choose frequency: Disabled (no emails), Daily, Weekly, or Monthly.

Summaries include: total pageviews, unique visitors, top pages, top traffic sources, goal achievements. Sent at midnight server time.

Email Addresses: Comma‑separated list of recipients for email summaries. Only valid email addresses are used; invalid ones are silently ignored.

Example: [email protected], [email protected], [email protected]

Raw Data Retention: How long to keep detailed analytics data (visits, events, sessions). Default is 24 months (2 years).

Options: Forever (keep all data), 1 month, 3 months, 6 months, 12 months, 24 months, 36 months, or 48 months. After this period, data is automatically deleted to comply with GDPR data minimization requirements.

Exclusions Tab

Exclude Users: Select WordPress users whose visits should not be tracked. Useful for excluding admin activity from analytics.

Common practice: exclude all admin users to get clean visitor data. You can select multiple users from the dropdown.

Exclude Roles: Exclude entire WordPress user roles. More convenient than selecting individual users if you have many admins.

Common roles to exclude: Administrator, Editor. Subscribers and Customers are typically tracked.

Exclude User Agents: Block tracking for specific browsers or bots based on User Agent string. Enter patterns one per line or comma‑separated.

Partial matches work. Example: entering "bot" excludes Googlebot, Bingbot, etc. Use this to filter out unwanted bot traffic.

Aggregate Bot Data: When enabled, known bot traffic is stored in a separate table instead of being counted as regular visitors.

This keeps your visitor metrics clean while still allowing you to analyze bot activity separately if needed.

Conversions Tab

Configure server‑side conversion tracking for Meta (Facebook), TikTok, and Google Ads. See the Conversion APIs section below for detailed step‑by‑step setup guides on how to generate API keys and tokens.

Meta Pixel ID: Your Facebook Pixel ID (15‑16 digit number). Find this in Facebook Events Manager.

Meta API Token: Conversions API access token from Facebook. Starts with "EAA". Keep this secret.

Meta Tracked Events: Select which events to send to Facebook. Common events: PageView, ViewContent, AddToCart, InitiateCheckout, AddPaymentInfo, Purchase.

Use the quickselect button to apply Facebook's standard event set.

TikTok Pixel ID: Your TikTok Pixel ID from TikTok Ads Manager.

TikTok API Token: Events API access token from TikTok. Keep this secret.

TikTok Tracked Events: Select which events to send to TikTok. Common events: ViewContent, AddToCart, Purchase, InitiateCheckout, CompletePayment.

Google Conversion Map: Map your goals to Google Ads conversion actions. Enter the exact conversion action name from Google Ads (case‑sensitive). The name must match precisely for tracking to work. This is used when exporting offline conversions to Google Ads.

System Tab

Manage your analytics database, check storage usage, and export or delete data.

Storage Usage: View how much disk space analytics data occupies. Select a date range and click Apply to see storage for that period.

The table shows storage used by each database table (sessions, visits, events, etc). Total storage is displayed at the bottom.

Storage Benchmarks: With profiling enabled, 1,000 pageviews occupy approximately 2‑2.5 MB of disk space.

With profiling disabled (anonymized IPs, no personal data), 1,000 pageviews occupy approximately 1‑1.5 MB.

For example: 100,000 monthly pageviews = ~200 MB/month with profiling, ~125 MB/month without profiling.

Export Data: Download analytics data as SQL file for backup or migration. Select date range and click Export.

The exported file contains all visits, events, sessions, and profiling data for the selected period. Import it on another WordPress site or keep as backup.

Import Data: Upload a previously exported SQL file. Click Import, select the .sql file, and confirm.

The plugin validates and executes SQL statements. Duplicate data is skipped automatically.

Delete Data: Permanently remove analytics data for a specific date range. Select range and click Delete.

You'll be asked to confirm before deletion. This cannot be undone, so export important data first if needed.

GDPR & Privacy Compliance

Must‑Have Analytics is designed with privacy as a core principle, offering flexible data collection modes and full GDPR compliance out of the box.

With Tracking Cookies (Requires Consent):

  • Accurate session identification across multiple visits
  • Ability to link sessions belonging to the same visitor
  • Long‑term visitor tracking and behavioral analysis
  • Complete visitor journey tracking
  • GDPR Requirement: Explicit user consent required before setting tracking cookies

Without Tracking Cookies (Default Mode):

  • Collects anonymous, aggregated analytics data
  • Uses device fingerprinting for temporary session identification
  • Shorter session timeout windows
  • Privacy‑first approach with no persistent identifiers
  • GDPR Compliance: Aggregated, anonymous data collection without cookies typically does not require explicit consent

Key Benefit: The plugin continues to collect valuable analytics data even when users decline cookies, ensuring you never lose complete visibility into your site's performance.

Visitor Profiling & Consent Requirements

When profiling is enabled, Must‑Have Analytics automatically collects identifying information from forms, user registrations, e‑commerce orders, and integrations.

Session Linking Without Cookies: Even without tracking cookies, profiling can link sessions of the same visitor by matching email addresses, WordPress user IDs, WooCommerce sessions, or other identifiers from Must‑Have plugins.

GDPR Requirements for Profiling:

  • Legal basis: Legitimate interest or explicit consent
  • Transparency: Clear privacy policy disclosure
  • User rights: Access, rectification, erasure, portability
  • Data minimization: Only collect necessary data
  • Purpose limitation: Use data only for stated purposes

Important: Profiling constitutes processing of personal data under GDPR Article 4(4). Only enable profiling if you have a comprehensive privacy policy, cookie/consent management solution, and procedures for handling data subject requests.

WordPress Personal Data Export

Must‑Have Analytics integrates seamlessly with WordPress's built‑in GDPR tools.

When a user requests their personal data through Tools → Export Personal Data, the plugin automatically includes:

Entity Information: Email addresses, phone numbers, names, WordPress user ID, first/last seen dates, total sessions and pageviews, countries, devices, goal achievements, conversion value.

Session Data: Session IDs, timestamps, IP addresses (if retained), location, device info, browser details, referrers, pages visited, goals achieved.

The export is provided in WordPress's standard JSON format, making it machine‑readable and human‑friendly.

No configuration needed — this feature works automatically through WordPress's native export tool.

WordPress Personal Data Erasure

When a user requests data deletion through Tools → Erase Personal Data, the plugin automatically handles the request through two erasure handlers:

Entity Data Erasure: Deletes email addresses, phone numbers, names, and all profiling data. The entity record is anonymized with a new anonymous ID, and session associations are maintained but linked to the anonymized entity.

Session Data Anonymization: IP addresses are anonymized (last octet removed, e.g., 192.168.1.123 becomes 192.168.1.0), referrer URLs are cleared, query strings are removed, and user agent strings are cleared.

What's Preserved: Aggregated statistics (pageviews, sessions), device type statistics, country‑level data, and anonymous goal completions are kept to maintain analytics accuracy.

Important: The plugin uses anonymization instead of complete deletion to preserve aggregated statistics while complying with GDPR's "right to be forgotten" (Article 17). Anonymization is considered equivalent to erasure when data can no longer identify an individual.

Data Storage & Third‑Party Sharing

All analytics data is stored on your WordPress server:

  • Database tables in your WordPress database
  • No external data collection servers
  • Complete control over your data
  • No dependency on third‑party services
  • GDPR‑compliant data residency

Third‑Party Data Sharing:

  • Must‑Have Plugins: Only license key and site URL sent for license validation (no personal data)
  • Meta (Facebook/Instagram): Hashed email/phone and conversion events — only if you explicitly enable and configure conversion tracking
  • TikTok: Hashed email/phone and conversion events — only if you explicitly enable and configure conversion tracking

Important: Conversion tracking to Meta or TikTok ONLY occurs when you enable it in Settings, configure API credentials, select specific conversions to track, and a tracked conversion occurs. No other third parties receive any data from Must‑Have Analytics.

Data Retention Policies

Configure data retention period in Settings → General → Raw Data Retention:

  • Forever (keep all data indefinitely)
  • 1 month, 3 months, 6 months, 12 months, 24 months, 36 months, or 48 months

Automatic cleanup removes sessions, visits, events older than the retention period, plus unreferenced URLs, user agents, and query strings.

GDPR Compliance Checklist

General Requirements:

  • ☑ Privacy policy published and accessible
  • ☑ Privacy policy includes Must‑Have Analytics disclosure
  • ☑ Data retention policy defined and configured
  • ☑ WordPress Personal Data tools tested and working
  • ☑ Admin users trained on GDPR procedures

If Using Tracking Cookies:

  • ☑ Cookie consent banner implemented
  • ☑ Cookie notice in privacy policy
  • ☑ Opt‑out mechanism available
  • ☑ Cookies not set before consent
  • ☑ Consent recorded and auditable

If Using Profiling:

  • ☑ Legal basis identified (consent or legitimate interest)
  • ☑ Privacy policy includes profiling disclosure
  • ☑ Data minimization implemented
  • ☑ User rights procedures documented
  • ☑ Data retention configured

If Using Conversion APIs:

  • ☑ Privacy policy mentions Meta/TikTok data sharing
  • ☑ User consent obtained before tracking
  • ☑ Data processing agreement with Meta/TikTok
  • ☑ API credentials secured
  • ☑ Test events working properly

Remember: GDPR compliance is not just about the tools you use, but how you use them. Always consult with legal counsel to ensure your specific implementation meets all applicable regulations.

Developer Reference

Must‑Have Analytics provides extensive hooks and filters for developers to extend functionality and customize behavior.

Core Actions

mhanalytics/init — Fires after plugin initialization. Use to load custom integrations.

mhanalytics/load_integrations — Fires when integrations are loaded. Add custom integration classes here.

mhanalytics_option_{key}_updated — Fires when a specific option is updated. Replace {key} with option name (e.g., mhanalytics_option_profiling_updated).

Event Processing Actions

mhanalytics/process_event/visit — Fires after a visit event is processed. Parameters: $visit_data, $sid.

mhanalytics/process_event/bot — Fires when bot traffic is detected. Parameters: $bot_data.

mhanalytics/login_event — Fires when a user logs in. Parameters: $user_id, $sid.

mhanalytics/logout_event — Fires when a user logs out. Parameters: $user_id, $sid.

mhanalytics/register_event — Fires when a new user registers. Parameters: $user_id, $sid.

mhanalytics/search_event — Fires when a search is performed. Parameters: $search_term, $sid.

WooCommerce Actions

mhanalytics/event/view_content — Product viewed. Parameters: $product_id, $sid, $data.

mhanalytics/event/add_to_cart — Product added to cart. Parameters: $product_id, $sid, $cart_data.

mhanalytics/event/initiate_checkout — Checkout started. Parameters: $sid, $cart_data.

mhanalytics/event/add_payment_info — Payment info entered. Parameters: $sid, $payment_data.

mhanalytics/event/checkout — Order completed. Parameters: $order_id, $sid, $order_data.

mhanalytics/event/failed_order — Order failed. Parameters: $order_id, $sid.

mhanalytics/event/refund — Order refunded. Parameters: $order_id, $sid, $refund_data.

mhanalytics/event/coupon_added — Coupon applied. Parameters: $coupon_code, $sid.

mhanalytics/event/coupon_used — Coupon used in order. Parameters: $coupon_code, $order_id, $sid.

mhanalytics/event/abandoned_cart — Cart abandoned. Parameters: $sid, $cart_data.

mhanalytics/event/achieve_goal — Goal achieved. Parameters: $goal, $sid.

Goals & Customization Filters

mhanalytics/goal_components — Add custom goal condition types. Return array with section and conditions.

mhanalytics/get_goals — Modify or filter available goals. Parameters: $goals array.

Option Filters

mhanalytics_option_{key} — Filter option value when retrieved. Replace {key} with option name.

mhanalytics_option_not_set_{key} — Return default value when option doesn't exist.

mhanalytics_update_option_{key} — Validate/transform value before saving.

mhanalytics_check_option_{key} — Return boolean check for option existence.

mhanalytics/frontend_options — Add custom options to frontend tracker. Parameters: $options array.

Reports & Tools Filters

mhanalytics/report_types — Register custom report types. Parameters: $types array.

mhanalytics/report_tiles — Add custom report tiles to Reports page. Parameters: $tiles array.

mhanalytics/tool_tiles — Add custom tool tiles to Tools page. Parameters: $tiles array.

mhanalytics/report_filters/filters — Add filter controls to reports. Parameters: $filters, $report_type.

mhanalytics/report_sql/options — Modify SQL generation options. Parameters: $options array.

mhanalytics/report/data — Transform report data before display. Parameters: $data, $sql, $report_type.

mhanalytics/report/data/response — Modify final REST API response. Parameters: $response array.

mhanalytics/report_display_names — Custom column labels. Parameters: $names array.

Session & Formatting Filters

mhanalytics/session_device_timeframe — Device fingerprint timeout in seconds. Default: 1200 (20 min) without cookie, 300 (5 min) with cookie.

mhanalytics/session_cookie_timeframe — Cookie session timeout in seconds. Default: 3600 (1 hour).

mhanalytics/session_profile_timeframe — Profile data timeout in seconds. Default: 3600 (1 hour).

mhanalytics/bounce_threshold — Bounce threshold in seconds. Default: 30.

mhanalytics/date_format — Date format for display. Default: WordPress setting.

mhanalytics/decimal_separator — Decimal separator for numbers. Default: '.'

mhanalytics/thousands_separator — Thousands separator. Default: ','

mhanalytics/currencies — Available currencies array. Add custom currencies.

mhanalytics/traffic_source — Normalize/override detected traffic source. Parameters: $source, $referrer.

WooCommerce Data Filters

mhanalytics/woocommerce/add_to_cart/product_data — Modify product data for add to cart event.

mhanalytics/woocommerce/add_to_cart/product_id — Override product ID.

mhanalytics/woocommerce/add_to_cart/cart_data — Modify cart data.

mhanalytics/woocommerce/cart_data — Modify cart data for checkout events.

mhanalytics/woocommerce/order_data — Modify order data before tracking.

mhanalytics/woocommerce/failed_order_data — Modify failed order data.

mhanalytics/woocommerce/refund_data — Modify refund data.

mhanalytics/woocommerce/payment_data — Modify payment method data.

mhanalytics/woocommerce/view_content/product_id — Override viewed product ID.

mhanalytics/woocommerce/report_tiles — Add custom WooCommerce report tiles.

Conversion API Filters

mhanalytics/meta_pixel_body — Enrich Meta CAPI request body. Parameters: $body, $event_name, $sid.

mhanalytics/tiktok_body — Enrich TikTok Events API body. Parameters: $body, $event_name, $sid.

Template & Asset Filters

mhanalytics/get_template — Modify template HTML before output. Parameters: $html, $template_name.

mhanalytics/get_svg — Modify SVG output. Parameters: $svg, $icon_name.

mhanalytics/session/print_event_data — Modify event HTML output in session details. Parameters: $output, $event.

mhanalytics/client_ip — Override or filter detected client IP address. Parameters: $ip.

Practical Examples

Example 1: Add Custom Goal Condition

add_filter('mhanalytics/goal_components', function($components) {
    $components[] = [
        'section' => 'Membership',
        'conditions' => [
            'membership_level' => [
                'name' => 'Membership Level',
                'type' => 'select',
                'options' => ['free', 'premium', 'vip'],
                'operators' => ['is', 'is_not']
            ]
        ]
    ];
    return $components;
});

Example 2: Enrich Meta Conversion Data

add_filter('mhanalytics/meta_pixel_body', function($body, $event, $sid) {
    $eid = MH_Analytics_Profiling::get_eid_by_sid($sid);
    if ($eid) {
        $customer_ltv = calculate_customer_ltv($eid);
        $body['data'][0]['custom_data']['predicted_ltv'] = $customer_ltv;
    }
    return $body;
}, 10, 3);

Example 3: Add Custom Report Tile

add_filter('mhanalytics/report_tiles', function($tiles) {
    $tiles[] = [
        'slug' => 'customer-segments',
        'title' => 'Customer Segments',
        'desc' => 'RFM segmentation analysis',
        'icon' => 'chart-bar' // Use custom icon name
    ];
    return $tiles;
});

Example 4: Custom Session Timeout

// Extend session timeout to 2 hours
add_filter('mhanalytics/session_cookie_timeframe', function($seconds) {
    return 7200; // 2 hours (120 minutes)
});

Example 5: Modify Frontend Tracking Options

add_filter('mhanalytics/frontend_options', function($opts) {
    // Force disable tracking cookie
    $opts['cookie'] = false;
    return $opts;
});

Changelog

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only