Filter: wpd_ai_is_valid_reporting_utm_key_value_pair

Filter whether a UTM key-value pair is valid for reporting purposes. This allows custom validation logic for UTM parameters.

Description

Alpha Insights validates UTM parameters before using them in reports. This filter allows you to add custom validation logic to determine if a specific UTM key-value combination should be included in reporting data.

Location

File: includes/functions/wpd-report-functions.php

Function: wpd_is_valid_reporting_utm_key_value_pair()

Line: ~93

Parameters

Return

Type: bool

Description: True if valid, false to exclude from reporting

Example Usage

Exclude Internal Testing Campaigns

add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'exclude_test_campaigns', 10, 3 );
function exclude_test_campaigns( $valid, $key, $value ) {
    // Exclude test campaigns from reporting
    if ( $key === 'utm_campaign' && stripos( $value, 'test' ) !== false ) {
        return false;
    }
    return $valid;
}

Exclude Specific UTM Sources

add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'exclude_specific_sources', 10, 3 );
function exclude_specific_sources( $valid, $key, $value ) {
    // Exclude internal or development sources
    if ( $key === 'utm_source' ) {
        $excluded_sources = array( 'internal', 'dev', 'staging', 'localhost' );
        if ( in_array( strtolower( $value ), $excluded_sources ) ) {
            return false;
        }
    }
    return $valid;
}

Require Minimum Value Length

add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'require_minimum_length', 10, 3 );
function require_minimum_length( $valid, $key, $value ) {
    // Require campaign names to be at least 5 characters
    if ( $key === 'utm_campaign' && strlen( $value ) < 5 ) {
        return false;
    }
    return $valid;
}

Validate Against Allowed Values List

add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'validate_against_whitelist', 10, 3 );
function validate_against_whitelist( $valid, $key, $value ) {
    // Define allowed campaign values
    $allowed_campaigns = array( 'summer_sale', 'winter_sale', 'new_product_launch' );
    
    if ( $key === 'utm_campaign' && ! in_array( $value, $allowed_campaigns ) ) {
        return false;
    }
    return $valid;
}

Block Spam or Invalid Characters

add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'block_spam_characters', 10, 3 );
function block_spam_characters( $valid, $key, $value ) {
    // Block values with suspicious characters
    if ( preg_match( '/[<>"\']/', $value ) ) {
        return false;
    }
    return $valid;
}

Best Practices

• Return the original $valid value if your logic doesn't apply
• Use specific key checks rather than blanket validation
• Keep validation logic simple and fast
• Log excluded values for debugging if needed
• Consider performance impact on high-traffic sites

Important Notes

• This filter runs for every UTM parameter check
• Returning false excludes the key-value pair from reporting
• Default validation (key and value validity) runs before this filter
• This is the final validation step before data is stored
• Invalid pairs are silently excluded (not logged by default)

Related Filters

• wpd_ai_is_valid_reporting_utm_key - Validate UTM keys
• wpd_ai_is_valid_reporting_utm_value - Validate UTM values
• wpd_ai_valid_reporting_utm_keys - Filter valid UTM keys list

Related Functions

• wpd_is_valid_reporting_utm_key_value_pair() - Check if key-value pair is valid
• wpd_is_valid_reporting_utm_key() - Check if UTM key is valid
• wpd_is_valid_reporting_utm_value() - Check if UTM value is valid

Debugging

add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'debug_utm_validation', 999, 3 );
function debug_utm_validation( $valid, $key, $value ) {
    if ( ! $valid ) {
        error_log( sprintf( 
            'Alpha Insights: Excluded UTM pair - Key: %s, Value: %s', 
            $key, 
            $value 
        ) );
    }
    return $valid;
}