Cave Tracker

Cave Tracker is a privacy-first hybrid browser + server-side tracking plugin for WordPress and WooCommerce. It is built for teams that want a high-performance, first-party alternative to pixel-heavy tracking stacks while keeping event data cleaner, safer, and more controllable.

It supports:

• Meta CAPI (Facebook / Instagram Conversions API)
• GA4 Measurement Protocol
• TikTok Events API
• First-party browser cookie management for _fbp, _fbc, and _ct_uid
• WooCommerce lifecycle events
• Disposable email and fake-order protection
• Admin-side monitoring for recent event logs

Why Cave Tracker?

Cave Tracker is designed to help store owners and marketers send tracking events in a way that is more resilient, privacy-aware, and operationally controlled than relying only on frontend pixels.

It focuses on:

• first-party data handling
• server-side event forwarding
• reduced reliance on third-party browser-only tracking
• consent-aware privacy controls
• clean event delivery to ad platforms and analytics tools

Features

Tracking & ad networks

• Meta CAPI event dispatch
• Google Analytics 4 Measurement Protocol delivery
• TikTok Events API delivery
• Event deduplication-friendly event_id support
• Server-side queueing with Action Scheduler when available

WooCommerce integration

• Product view tracking
• Add-to-cart tracking
• Checkout initiation tracking
• Purchase tracking
• Product IDs, quantities, currency, and value support

Fraud prevention

• Disposable email domain detection
• Suspicious field detection for checkout values
• Risk scoring and flagged orders
• Optional order hold or pending state changes for risky purchases
• Purchase event suppression for flagged orders

Admin experience

• Tabbed settings page in WordPress admin
• API credential fields for Meta, GA4, and TikTok
• WooCommerce event toggles
• Fraud controls and threshold configuration
• Recent event log view for status and errors

Installation

1. Download or clone this repository.
2. Copy the plugin folder into your WordPress installation: wp-content/plugins/cave-tracker
3. Activate the plugin from the WordPress admin plugins screen.
4. Open the Cave Tracker menu item in the admin sidebar.
5. Configure your API credentials and tracking options.
6. Review your site’s consent and privacy policies before enabling conversion tracking in production.

Configuration

The plugin exposes a dedicated admin menu with these tabs:

• General & APIs

  • Meta Pixel ID
  • Meta CAPI access token
  • GA4 Measurement ID
  • GA4 API secret
  • TikTok token

• WooCommerce & Events

  • ViewContent
  • AddToCart
  • InitiateCheckout
  • Purchase

• Fraud & Fake Orders

  • Disposable email blocking
  • Fraud threshold
  • Flagged order action

• Event Logs

  • Recent network response records for debugging and review

Privacy and compliance

Cave Tracker is designed for privacy-aware measurement. Before event payloads are sent to ad networks, PII fields are normalized and hashed with SHA-256 for the fields typically considered sensitive, such as:

• email
• phone
• first name
• last name
• city
• state
• postal code
• country

The following are intentionally kept in a usable form for platform-level analysis when permitted:

• client IP address
• user agent

This plugin is not a substitute for legal review, consent management, or regional compliance implementation. You should confirm your configuration aligns with your privacy policy, consent flow, and data processing obligations.

Developer hooks

The plugin exposes hooks for customizing flow control and pre-send behavior.

Action hook

add_action(
    'cave_tracker_before_send_event',
    function (string $event_name, array $event_data, array $user_data): void {
        // Custom logic before network dispatch.
    },
    10,
    3
);

Filter hook

add_filter(
    'cave_tracker_should_send_event',
    function (bool $should_send, string $event_name, array $event_data, array $user_data): bool {
        if ('Purchase' === $event_name) {
            return false;
        }

        return $should_send;
    },
    10,
    4
);

Client IP customization

add_filter(
    'cave_tracker_client_ip',
    function (string $ip): string {
        if (!empty($_SERVER['HTTP_CF_CONNECTING_IP'])) {
            return sanitize_text_field(wp_unslash((string) $_SERVER['HTTP_CF_CONNECTING_IP']));
        }

        return $ip;
    }
);

Fraud engine customization

The fraud system is intentionally modular. You can extend or replace the default logic for your own risk model.

Example: block a custom event during fraud review:

add_filter(
    'cave_tracker_should_send_event',
    function (bool $should_send, string $event_name, array $event_data, array $user_data): bool {
        if ('Purchase' === $event_name && isset($_GET['fraud_review'])) {
            return false;
        }

        return $should_send;
    },
    10,
    4
);

Browser tracking notes

The browser script creates and maintains first-party cookie values used in tracking flows:

• _fbp
• _fbc
• _ct_uid

These are stored with standard browser cookie behavior and are designed for first-party measurement without relying solely on third-party scripts.

Contributing

Contributions are welcome. Please keep code changes well-documented, backward-compatible where possible, and aligned with WordPress coding standards.

If you are contributing:

• keep patches focused
• document new hooks or options
• validate against WooCommerce flows when touching commerce logic
• avoid shipping secrets or API credentials in code

License

This project is released under the GNU General Public License v2 or later.

See the LICENSE file for the full text.

Support and maintenance

This repository is intended as an open-source plugin foundation. For production deployments, validate all platform credentials, tracking rules, and conversions in a staging environment before enabling live campaign data flow.