## Filter: wpd_ai_valid_reporting_utm_keys

Filter the list of valid UTM keys that Alpha Insights recognizes for reporting. This allows you to add custom tracking parameters or modify the default list.

### Description

Alpha Insights maintains a list of valid UTM keys that are recognized for reporting. This filter allows you to add custom tracking parameters, remove default keys, or modify the entire list to match your tracking needs.

#### Location

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

Function: `wpd_get_valid_reporting_utm_keys()`

Line: ~181

### Parameters

Parameter | Type | Description
--- | --- | ---
$valid_utm_keys | array | Array of valid UTM key strings (default: standard UTM keys plus common alternatives)

#### Return

Type: array

Description: Modified array of valid UTM key strings

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

    add_filter( 'wpd_ai_valid_reporting_utm_keys', 'add_custom_tracking_keys' );
    function add_custom_tracking_keys( $valid_utm_keys ) {
        // Add custom tracking parameters
        $custom_keys = array( 'affiliate_id', 'partner_id', 'promo_code', 'referrer_id' );
        return array_merge( $valid_utm_keys, $custom_keys );
    }

### Remove Specific Keys

    add_filter( 'wpd_ai_valid_reporting_utm_keys', 'remove_specific_keys' );
    function remove_specific_keys( $valid_utm_keys ) {
        // Remove keys you don't want to track
        $keys_to_remove = array( 's', 'search' );
        return array_diff( $valid_utm_keys, $keys_to_remove );
    }

### Replace Entire List

    add_filter( 'wpd_ai_valid_reporting_utm_keys', 'replace_utm_keys_list' );
    function replace_utm_keys_list( $valid_utm_keys ) {
        // Use only standard UTM parameters
        return array(
            'utm_source',
            'utm_medium',
            'utm_campaign',
            'utm_content',
            'utm_term',
            'utm_id'
        );
    }

### Add Platform-Specific Keys

    add_filter( 'wpd_ai_valid_reporting_utm_keys', 'add_platform_keys' );
    function add_platform_keys( $valid_utm_keys ) {
        // Add keys for specific advertising platforms
        $platform_keys = array(
            'fbclid',      // Facebook Click ID
            'gclid',       // Google Click ID
            'msclkid',     // Microsoft Click ID
            'ttclid',      // TikTok Click ID
            'twclid'       // Twitter Click ID
        );
        return array_merge( $valid_utm_keys, $platform_keys );
    }

### Conditional Keys Based on Environment

    add_filter( 'wpd_ai_valid_reporting_utm_keys', 'conditional_utm_keys' );
    function conditional_utm_keys( $valid_utm_keys ) {
        // Add debug keys only in development
        if ( defined( 'WP_ENVIRONMENT_TYPE' ) && WP_ENVIRONMENT_TYPE === 'development' ) {
            $valid_utm_keys[] = 'debug_key';
            $valid_utm_keys[] = 'test_campaign';
        }
        return $valid_utm_keys;
    }

### Best Practices

- Use array_merge() to add keys without losing defaults
- Use array_diff() to remove specific keys
- Keep key names lowercase and use underscores
- Document custom keys for your team
- Test that your custom keys work in reports
- Consider performance impact with very large key lists

### Important Notes

- Keys are case-sensitive in the array, but validation is case-insensitive
- Adding a key here makes it available for all reports
- Keys must be valid URL parameter names (alphanumeric, underscores, hyphens)
- This affects all UTM validation, not just specific reports
- Changes apply immediately to new tracking data
- Historical data is not affected by changes

### Key Naming Conventions

Recommended key naming:

- Use lowercase letters
- Use underscores for word separation
- Keep names descriptive but concise
- Avoid special characters
- Examples: 'affiliate_id', 'partner_code', 'campaign_type'

### Related Filters

- wpd_ai_is_valid_reporting_utm_key - Validate individual UTM 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_get_valid_reporting_utm_keys()` - Get list of valid UTM keys
- `wpd_is_valid_reporting_utm_key()` - Check if a key is valid

### Debugging

    add_filter( 'wpd_ai_valid_reporting_utm_keys', 'debug_utm_keys_list', 999 );
    function debug_utm_keys_list( $valid_utm_keys ) {
        error_log( 'Alpha Insights Valid UTM Keys: ' . implode( ', ', $valid_utm_keys ) );
        return $valid_utm_keys;
    }