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

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