Enhance Your Dynamic URLs with UTM Parameters in Voxel

Inspired by the great work of the voxelguides.com site, I’ve been exploring ways to expand the capabilities of the Voxel platform. As a fellow Voxel user, I’m excited to share this new UTM parameters modifier that I’ve built to help track the performance of your marketing links.

The new UTM parameters modifier is here to help! This powerful addition to dynamic tags allows you to easily append UTM (Urchin Tracking Module) parameters to your URLs, making it simple to track the source, medium, and campaign of your links.

You can find the working version for Voxel 1.5 at the bottom of this post.

I’m providing this modifier as a free contribution to the Voxel community, as this is not an official Voxel feature.

I hope you find it useful in enhancing your website’s analytics and marketing efforts 🙂

What Are UTM Parameters?

UTM parameters are specific tags added to a URL that help you track the effectiveness of your marketing campaigns. They provide valuable insights into:

– Where your traffic is coming from (source)
– What type of link or marketing channel was used (medium)
– The specific campaign associated with the link (campaign)

How to Use the New UTM Parameters Modifier

You can add this modifier to your Voxel site using two methods:

Method 1: Functions.php in Child Theme

add_filter( 'voxel/dynamic-tags/modifiers', function( $modifiers ) {
class Add_UTM_Parameters extends \Voxel\Dynamic_Tags\Base_Modifier {
public function get_label(): string {
return 'Add UTM Parameters';
}

public function get_key(): string {
return 'add_utm_parameters';
}

public function get_arguments(): array {
return [
'utm_source' => [
'type' => \Voxel\Form_Models\Text_Model::class,
'label' => _x( 'UTM Source', 'modifiers', 'voxel-backend' ),
'classes' => 'x-col-12',
],
'utm_medium' => [
'type' => \Voxel\Form_Models\Text_Model::class,
'label' => _x( 'UTM Medium', 'modifiers', 'voxel-backend' ),
'classes' => 'x-col-12',
],
'utm_campaign' => [
'type' => \Voxel\Form_Models\Text_Model::class,
'label' => _x( 'UTM Campaign', 'modifiers', 'voxel-backend' ),
'classes' => 'x-col-12',
],
];
}

public function apply( $value, $args, $group ) {
// URL validation and UTM parameter handling
if ( filter_var( $value, FILTER_VALIDATE_URL ) === false ) {
return $value;
}

$utm_source = isset( $args[0] ) ? urlencode( $args[0] ) : '';
$utm_medium = isset( $args[1] ) ? urlencode( $args[1] ) : '';
$utm_campaign = isset( $args[2] ) ? urlencode( $args[2] ) : '';

$utm_query = [];
if ( $utm_source ) {
$utm_query[] = 'utm_source=' . $utm_source;
}
if ( $utm_medium ) {
$utm_query[] = 'utm_medium=' . $utm_medium;
}
if ( $utm_campaign ) {
$utm_query[] = 'utm_campaign=' . $utm_campaign;
}

if ( empty( $utm_query ) ) {
return $value;
}

$delimiter = strpos( $value, '?' ) === false ? '?' : '&';
$modified_url = $value . $delimiter . implode( '&', $utm_query );

return htmlspecialchars( $modified_url );
}
}

$modifiers['add_utm_parameters'] = \Add_UTM_Parameters::class;
return $modifiers;
} );

---

A nice additional comment from the group:

• For my fellow Matomo users you can simply replace “utm” with “mtm”

Method 2: Custom Code Snippet

If you prefer not to modify your theme’s functions file, you can add this as a custom code snippet through a site-specific plugin.

How to Use the Modifier in Voxel

1. When creating a dynamic tag that outputs a URL
2. Select the new “Add UTM Parameters” modifier
3. Fill in the UTM Source, Medium, and Campaign fields

Example Use Cases

Tracking social media links:

• Source: `facebook`
• Medium: `social_post`
• Campaign: `summer_sale_2024`

Tracking email marketing:

• Source: `newsletter`
• Medium: `email`
• Campaign: `may_promo`

Example of the Modified URL

Suppose the original link was:

`https://example.com/products/widget`

After applying the UTM parameters with the values provided in the image (thesource, somemedium, mycampaign), the modified link would be:

`https://example.com/products/widget?utm_source=thesource&utm_medium=somemedium&utm_campaign=mycampaign`

This modified link would include the UTM parameters as query string parameters appended to the original URL. The resulting link can then be used to track the performance of this specific marketing campaign, allowing you to analyze the source, medium, and campaign associated with any traffic or conversions from this link.

Pro Tips

• Always use lowercase and avoid spaces in your UTM parameters
• Be consistent with your naming conventions
• Use UTM parameters to gain insights into your marketing efforts

By implementing this modifier, you’ll have a powerful tool to track your link performance directly from within Voxel!

VERSION FOR VOXEL 1.5+ :

// ADD UTM parameters to a URL modifier - VOXEL 1.5
add_action('voxel/dynamic-data/modifiers', function( $modifiers ) {
class Add_UTM_Parameters extends \Voxel\Dynamic_Data\Modifiers\Base_Modifier {
public function get_label(): string {
return _x('Add UTM Parameters', 'modifiers', 'voxel-backend');
}
public function get_key(): string {
return 'add_utm_parameters';
}
public function expects(): array {
return [ static::TYPE_STRING ];
}
protected function define_args(): void {
$this->define_arg([
'type' => 'text',
'label' => _x('UTM Source', 'modifiers', 'voxel-backend'),
]);
$this->define_arg([
'type' => 'text',
'label' => _x('UTM Medium', 'modifiers', 'voxel-backend'),
]);
$this->define_arg([
'type' => 'text',
'label' => _x('UTM Campaign', 'modifiers', 'voxel-backend'),
]);
}
public function apply( string $value ) {
// Validate the input value as a valid URL
if ( filter_var( $value, FILTER_VALIDATE_URL ) === false ) {
return esc_url( $value );
}
// Get UTM parameters from arguments
$utm_source = $this->get_arg(0) ? urlencode($this->get_arg(0)) : '';
$utm_medium = $this->get_arg(1) ? urlencode($this->get_arg(1)) : '';
$utm_campaign = $this->get_arg(2) ? urlencode($this->get_arg(2)) : '';
// Build the UTM query string
$utm_query = [];
if ( $utm_source ) {
$utm_query[] = 'utm_source=' . $utm_source;
}
if ( $utm_medium ) {
$utm_query[] = 'utm_medium=' . $utm_medium;
}
if ( $utm_campaign ) {
$utm_query[] = 'utm_campaign=' . $utm_campaign;
}
// If no UTM parameters are provided, return the original URL
if ( empty( $utm_query ) ) {
return esc_url( $value );
}
// Append UTM parameters to the URL
$delimiter = strpos( $value, '?' ) === false ? '?' : '&';
$modified_url = $value . $delimiter . implode( '&', $utm_query );
// Return the modified URL
return esc_url( $modified_url );
}
}
$modifiers['add_utm_parameters'] = Add_UTM_Parameters::class;
return $modifiers;
});