Filter: wpd_ai_is_valid_reporting_utm_key

Filter whether a UTM key is valid for reporting purposes. This allows custom validation logic for UTM parameter keys.

Description

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

Location

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

Function: wpd_is_valid_reporting_utm_key()

Line: ~147

Parameters

Return

Type: bool

Description: True if valid, false to exclude from reporting

Default Valid Keys

Alpha Insights recognizes these UTM keys by default:

• utm_source
• utm_medium
• utm_campaign
• utm_content
• utm_term
• utm_id
• ref
• coupon
• source
• campaign
• content
• medium
• term
• s
• search
• google_cid
• meta_cid

Example Usage

Add Custom UTM Keys

add_filter( 'wpd_ai_is_valid_reporting_utm_key', 'allow_custom_utm_keys', 10, 2 );
function allow_custom_utm_keys( $is_valid, $key ) {
    // Allow custom tracking keys
    $custom_keys = array( 'affiliate_id', 'partner_id', 'promo_code' );
    if ( in_array( $key, $custom_keys ) ) {
        return true;
    }
    return $is_valid;
}

Exclude Specific Keys

add_filter( 'wpd_ai_is_valid_reporting_utm_key', 'exclude_specific_keys', 10, 2 );
function exclude_specific_keys( $is_valid, $key ) {
    // Exclude certain keys from reporting
    $excluded_keys = array( 'internal_ref', 'debug_key' );
    if ( in_array( $key, $excluded_keys ) ) {
        return false;
    }
    return $is_valid;
}

Require UTM Prefix

add_filter( 'wpd_ai_is_valid_reporting_utm_key', 'require_utm_prefix', 10, 2 );
function require_utm_prefix( $is_valid, $key ) {
    // Only allow keys that start with 'utm_'
    if ( strpos( $key, 'utm_' ) !== 0 ) {
        return false;
    }
    return $is_valid;
}

Validate Key Format

add_filter( 'wpd_ai_is_valid_reporting_utm_key', 'validate_key_format', 10, 2 );
function validate_key_format( $is_valid, $key ) {
    // Only allow lowercase alphanumeric keys with underscores
    if ( ! preg_match( '/^[a-z0-9_]+$/', $key ) ) {
        return false;
    }
    return $is_valid;
}

Best Practices

• Return the original $is_valid value if your logic doesn’t apply
• Use wpd_ai_valid_reporting_utm_keys to add keys to the default list
• Keep validation logic simple and performant
• Consider using wpd_ai_valid_reporting_utm_keys filter instead for adding keys
• This filter is best for excluding keys, not adding them

Important Notes

• This filter runs for every UTM key check
• Returning false excludes the key from reporting
• Default validation (key in valid list) runs before this filter
• To add new keys, use wpd_ai_valid_reporting_utm_keys filter instead
• This filter is best for excluding or conditionally allowing keys
• Invalid keys are silently excluded (not logged by default)

Related Filters

• wpd_ai_valid_reporting_utm_keys – Add or modify the list of valid UTM keys (recommended for adding keys)
• wpd_ai_is_valid_reporting_utm_value – Validate UTM values
• wpd_ai_is_valid_reporting_utm_key_value_pair – Validate key-value pairs

Related Functions

• wpd_is_valid_reporting_utm_key() – Check if UTM key is valid
• wpd_get_valid_reporting_utm_keys() – Get list of valid UTM keys
• wpd_is_valid_reporting_utm_value() – Check if UTM value is valid

Debugging

add_filter( 'wpd_ai_is_valid_reporting_utm_key', 'debug_utm_key_validation', 999, 2 );
function debug_utm_key_validation( $is_valid, $key ) {
    if ( ! $is_valid ) {
        error_log( sprintf( 
            'Alpha Insights: Excluded UTM key: %s', 
            $key 
        ) );
    }
    return $is_valid;
}