## 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

Parameter | Type | Description
--- | --- | ---
$is_valid | bool | Whether the key is valid (default: true if key is in valid UTM keys list)
$key | string | The UTM key to validate (e.g., 'utm_source', 'utm_campaign')

#### 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;
    }