UTM Manager exposes filters and actions for customizing tracking behavior. All hooks use the utmm_ prefix.
Filters
utmm_enable_tracking
Gate whether the front-end tracking script loads at all. Return false to fully disable tracking for the current request — no script, no cookie, no beacon.
/**
* @param bool $enabled Whether to load the tracker. Default true.
*/
add_filter( 'utmm_enable_tracking', function ( $enabled ) {
// Don't track logged-in administrators.
return current_user_can( 'manage_options' ) ? false : $enabled;
} );Typical uses: consent-manager integration, excluding staff, disabling on specific pages.
utmm_store_ip
Control whether a (salted, hashed) IP is stored with each lead and visit. IPs are never stored raw regardless; returning false stores nothing IP-derived at all.
/**
* @param bool $store Whether to store a hashed IP. Default true.
*/
add_filter( 'utmm_store_ip', '__return_false' );utmm_custom_param_keys
Register additional query-string parameters to capture alongside the standard UTM keys. Captured values are stored in the JSON custom_params columns — no schema change needed. This is the integration point the Pro custom-parameter engine uses, and you can hook it directly:
/**
* @param string[] $keys Custom parameter keys. Default empty array.
*/
add_filter( 'utmm_custom_param_keys', function ( $keys ) {
$keys[] = 'gclid'; // Google Ads click ID
$keys[] = 'fbclid'; // Facebook click ID
$keys[] = 'partner_id'; // your own affiliate key
return $keys;
} );Keys are sanitized with sanitize_key(), so use lowercase letters, numbers, and underscores.
utmm_leads_table_query_args
Filter the query arguments used by the admin Leads list table before they hit the database — force a default filter, change the default ordering, etc.
/**
* @param array $args Query args: search, orderby, order, per_page, paged,
* utm_source, utm_medium, utm_campaign, start_date, end_date.
*/
add_filter( 'utmm_leads_table_query_args', function ( $args ) {
$args['utm_source'] = 'google'; // pin the table to Google traffic
return $args;
} );utmm_exportable_fields
Add your own columns to the Tools → CSV File Export field list. Pair it with the per-field value filter below; this is exactly how the Pro add-on contributes its custom-parameter and enrichment columns.
/**
* @param array<string,string> $fields Field ID => label.
*/
add_filter( 'utmm_exportable_fields', function ( $fields ) {
$fields['plan'] = __( 'Subscription Plan', 'your-textdomain' );
return $fields;
} );utm_manager_export_csv_field_{$field}
Resolve the value of a registered export field for each exported lead. The {$field} suffix is the field ID you registered above.
/**
* @param string $value Default empty string.
* @param object $lead The lead row being exported.
*/
add_filter( 'utm_manager_export_csv_field_plan', function ( $value, $lead ) {
return get_user_meta( $lead->user_id, 'plan', true );
}, 10, 2 );Values are formula-escaped by the exporter after this filter runs, so return plain strings.
Admin shell filters
For add-ons that render their own screens inside the plugin’s admin shell:
| Hook | Purpose |
|---|---|
utmm_screen_ids (filter) | Add screen IDs so the shared header and admin.css load on your page |
utmm_admin_header_nav (filter) | Add an item to the header navigation |
utmm_settings_tabs (filter) | Add a tab to the Settings screen; render it on utmm_{tab}_settings |
utmm_admin_page_after_content (action) | Fires where the shared sidebar renders — call it at the end of your own page |
Actions
utmm_tracked
Fires after every successfully recorded hit — your entry point for reacting to campaign traffic in real time (notifications, CRM sync, custom logging).
/**
* @param int $lead_id Lead ID in the utmm_leads table.
* @param array $utm Standard UTM key => value pairs recorded on this hit.
* @param array $custom Custom parameter key => value pairs recorded on this hit.
*/
add_action( 'utmm_tracked', function ( $lead_id, $utm, $custom ) {
if ( ( $utm['utm_campaign'] ?? '' ) === 'black-friday-sale' ) {
// e.g. bump a counter, ping Slack, tag the lead in your CRM…
}
}, 10, 3 );utmm_init
Fires once UTM Manager has finished wiring itself up on WordPress init. Use it to safely bootstrap add-ons that depend on the plugin being loaded.
add_action( 'utmm_init', function () {
// UTM Manager is fully loaded here.
} );Template / helper functions
Public helpers available after utmm_init:
| Function | Returns |
|---|---|
utmm_get_lead( $id ) | Lead row object by ID, or false |
utmm_get_lead_by_uuid( $uuid ) | Lead row object by visitor UUID, or false |
utmm_get_leads( $args, $count ) | Lead rows (or count) using the same args as the list table |
utmm_get_lead_visits( $lead_id, $limit ) | Visit rows for a lead, newest first |
utmm_get_utm_keys() | The six standard UTM keys |
utmm_get_custom_param_keys() | Registered custom parameter keys |
utmm_lead_identity( $lead ) | Best display identity: email → user name → UUID |
Pro hooks
These exist only when UTM Manager Pro is active, and use the utmmp_ prefix.
utmmp_lead_identified (action)
Fires the first time a lead gains an email address — via a form submission, a WooCommerce order, or a login.
/**
* @param int $lead_id Lead ID.
* @param string $email The email just attached to the lead.
*/
add_action( 'utmmp_lead_identified', function ( $lead_id, $email ) {
// e.g. push the newly named lead to your CRM.
}, 10, 2 );utmmp_lead_converted (action)
Fires when a tracked visitor completes a form submission or an order.
/**
* @param int $lead_id Lead ID.
* @param array $context Conversion context: source ('contact-form-7',
* 'wpforms', 'woocommerce'), form_id/order_id,
* email, and for orders total + currency.
*/
add_action( 'utmmp_lead_converted', function ( $lead_id, $context ) {
if ( 'woocommerce' === $context['source'] ) {
// e.g. attribute $context['total'] in your own reporting.
}
}, 10, 2 );utmmp_lead_payload (filter)
Filter the lead payload sent to webhooks, the REST API, and form/order integrations — add your own fields or strip ones you’d rather not transmit.
/**
* @param array $payload The payload.
* @param object $lead The lead row.
*/
add_filter( 'utmmp_lead_payload', function ( $payload, $lead ) {
unset( $payload['email'] ); // don't send emails off-site
return $payload;
}, 10, 2 );utmmp_retention_purged (action)
Fires after each retention purge run, with the number of leads deleted and their IDs — useful for audit logging.
Pro helper functions
| Function | Returns |
|---|---|
utmmp_current_lead() | The current visitor’s lead row (resolved from the utmm_vid cookie), or false |
utmmp_identify_lead( $lead_id, $email ) | Attaches an email to a lead; no-op if it already has one |
utmmp_get_custom_params() | Configured custom parameters as key/label pairs |
utmmp_decode_custom_params( $lead, 'last' ) | A lead’s captured custom values, first or last touch |
utmmp_get_lead_meta( $lead_id, $key ) | Enrichment values: country, device, browser, os, revenue, currency |
utmmp_lead_payload( $lead ) | The full attribution payload used by webhooks and the API |
REST endpoints
POST /wp-json/utmm/v1/track — the beacon endpoint used by the bundled tracker. It is public by necessity (anonymous visitors must report), protected by a nonce with a same-origin fallback, and validates/sanitizes every field server-side. Third-party clients are not supported; use the PHP hooks instead.
Pro adds read-only routes in the same namespace — GET /wp-json/utmm/v1/leads and GET /wp-json/utmm/v1/leads/<id> — authenticated by an admin session or an API key. See Integrations.