Developer Guide

WP Insights Pro is designed with extensibility in mind. While the built-in “no-code” tools cover most use cases, you can also integrate analytics directly into custom themes or plugins when needed.

This guide covers our public-facing JavaScript API and the PHP hooks and filters available for advanced customization.

JavaScript API: Tracking Custom Events

The primary way to interact with WP Insights Pro on the front-end is through a global JavaScript function. This allows you to track any custom interaction that our “no-code” selectors can’t cover, such as interactions with complex JavaScript widgets, video players, or third-party libraries.

The wpipTrackEvent() Function

To track an event from your theme or another script, simply call the global window.wpipTrackEvent() function. The function signature and parameters are as follows:

/**
 * @param {string} category - Required. The group for your event (e.g., 'CTA', 'Form').
 * @param {string} action - Required. The specific action (e.g., 'Click', 'Submit').
 * @param {string} [label] - Optional. Extra context (e.g., 'Header Buy Button').
 * @param {number} [value] - Optional. A numeric value for the event.
 */
wpipTrackEvent(category, action, label, value);

Practical Examples

Tracking a simple link click:
You can add the function call directly to an element’s onclick attribute.

<a href="/brochure.pdf" 
   onclick="wpipTrackEvent('Download', 'PDF', 'Company Brochure');">
   Download Brochure
</a>

Tracking a form submission with JavaScript:
For more complex interactions, like a form submitted via AJAX, you can call the function from your own JavaScript event listeners. This is the most robust method for tracking forms.

document.addEventListener('DOMContentLoaded', () => {
    const myForm = document.getElementById('my-ajax-form');
    if (myForm) {
        myForm.addEventListener('submit', (event) => {
            // Your form submission logic here...
            
            // Track the event with WP Insights Pro
            wpipTrackEvent('Form', 'Submit', 'Request a Quote Form');
        });
    }
});

Tracking a video play event:
If you’re using a video player library that provides a JavaScript API, you can hook into its events.

// Example using a hypothetical video player API
myVideoPlayer.on('play', () => {
    wpipTrackEvent('Video', 'Play', 'Product Demo Video');
});

myVideoPlayer.on('ended', () => {
    wpipTrackEvent('Video', 'Complete', 'Product Demo Video', myVideoPlayer.duration);
});

PHP Hooks & Filters

We provide several PHP filters to allow for advanced customization of the plugin’s behavior. You can add these to your theme’s functions.php file or a custom plugin.

Action Hooks

These hooks allow you to add your own custom HTML or execute functions on our admin pages.

wpip_before_admin_page_content

This action fires on every WP Insights Pro admin page, right after the main page title (<h1>) and before any of our page content is rendered. It’s the perfect place to add a custom notice, a dashboard widget, or other content at the top of a page.

Signature:
do_action( ‘wpip_before_admin_page_content’, string $page_slug );

• $page_slug (string): The slug of the current admin page (e.g., wp-insights-pro, wpip-settings).

add_action( 'wpip_before_admin_page_content', function( $page_slug ) {
    if ( 'wp-insights-pro' === $page_slug ) {
        echo '<div class="notice notice-info inline"><p>Welcome back, Admin! Here is your latest site overview.</p></div>';
    }
} );

wpip_after_admin_page_content

This action fires at the very end of every WP Insights Pro admin page, just before the closing </div> of the main page wrapper.

Signature:
do_action( ‘wpip_after_admin_page_content’, string $page_slug );

• $page_slug (string): The slug of the current admin page.

add_action( 'wpip_after_admin_page_content', function( $page_slug ) {
    echo '<p style="text-align: center; font-style: italic;">Custom content added via hook.</p>';
} );

Filter Hooks

These filters allow you to modify data or change the plugin’s behavior.

wpip_do_tracking

This boolean filter allows you to programmatically enable or disable tracking for any given page load. It runs after all the plugin’s internal checks (like logged-in user role exclusions) have passed. Return false from your function to prevent the tracking script from being loaded on the current page.

Signature:
apply_filters( ‘wpip_do_tracking’, bool $do_tracking );

add_filter( 'wpip_do_tracking', function( $do_track ) {
    // If tracking is already disabled by another rule, don't change anything.
    if ( ! $do_track ) {
        return $do_track;
    }
    
    // Disable tracking if the 'template-landing-page.php' template is being used.
    if ( is_page_template( 'templates/template-landing-page.php' ) ) {
        return false;
    }
    
    return $do_track;
} );

wpip_is_other_builder_preview

While we automatically disable tracking in the preview modes for most major page builders, this filter allows you to add compatibility for other or custom builders. Return true to disable tracking if your builder’s preview mode is detected.

Signature:
apply_filters( ‘wpip_is_other_builder_preview’, bool $is_preview );

add_filter( 'wpip_is_other_builder_preview', function( $is_preview ) {
    if ( isset( $_GET['mcb_preview'] ) ) {
        return true;
    }
    return $is_preview;
} );

wpip_bot_keywords

While WP Insights Pro uses a sophisticated library for bot detection, we also include a fallback check based on keywords in the User-Agent string. This filter allows you to add your own custom strings to this keyword list. It’s perfect for excluding traffic from internal monitoring tools or specific bots not on the main list.

Signature:
apply_filters( ‘wpip_bot_keywords’, array $keywords );

add_filter( 'wpip_bot_keywords', function( $keywords ) {
    // Add our custom User-Agent string to the list.
    $keywords[] = 'My-Internal-HealthChecker/2.0';
    
    return $keywords;
} );

wp_insights_pro_geoip_language

This filter allows you to change the language used for fetching country and city names from the MaxMind database during report generation. The default is ‘en’ (English). You can change this to any valid language code supported by the database (e.g., ‘de’, ‘fr’, ‘es’).

Signature:
apply_filters( ‘wp_insights_pro_geoip_language’, string $language_code );

add_filter( 'wp_insights_pro_geoip_language', function( $language_code ) {
    return 'de';
} );

wpip_archived_months_scan_limit

For performance, the “Archived Months” dropdown in the date range picker is limited to a number of past months. By default, this limit matches the Report Retention setting, but will fall back to a maximum of 60 months (5 years) if your retention is set to unlimited. This filter allows you to change that scan limit.

Signature:
apply_filters( ‘wpip_archived_months_scan_limit’, int $limit );

add_filter( 'wpip_archived_months_scan_limit', function( $limit ) {
    return 60;
} );