Passing Campaign Data Into Feed URLs

This article concerns versions lower than 2.0.0 of the Matador Jobs Pro – Jobs Syndication Feeds add-on. If you’re using a lower version than 2.0.0, please update.

To help our users understand where inbound traffic to their Matador Jobs website is coming from, the XML Feeds extension appends Campaign Data into the query strings for each job url provided in the feed.

When you provide a third-party aggregator a feed, it gets a list of your jobs with a job url. This URL can have Campaign Data added to it

It is up to the third-party feed aggregator to honor the URL’s with Campaign Data, but when they do, they provide the Matador Campaign Tracking feature important information about the traffic originating from an aggregator consuming your feed.

Default Campaign Data in Feed URLs

Provided you do not customize your campaign data, the following campaign data will be provided for each job:

• Source (utm_source): the Feed Name, ie: ZipRecruiter, Monster, etc.
• Medium (utm_medium): “Feed”
• Campaign (utm_campaign): “Aggregator”

Customize Campaign Data in Feed URLs

You can customize the campaign data in Feed by providing a Feed with utm_* parameters. UTM parameters are used by several tools, including Google Analytics and Matador Jobs Campaign Tracking feature, to note characteristics of inbound traffic to your site. The UTM parameters are:

• Source (utm_source)
• Medium (utm_medium)
• Campaign (utm_campaign)
• Term (utm_term)
• Content (utm_content)

If you plan to provide a feed to an external aggregator for consumption and rebroadcasting, you can append the UTM parameters by adding a question mark ? after the feed URL and then each of the UTM parameters with an equal sign and a value in camel case or with spaces replaced by underscores or dashes, eg: utm_source=My_Source, separated by ampersands (“and” signs) &. The following is a valid URL with UTM parameters:

https://your-site.com/jobs/xml?utm_source=XYZJobs&utm_medium=Aggregator

Customize Campaign Data in Feed URLs (Alternate Method)

If your web hosting provider’s caching layer filters utm_* variables from the PHP layer, as several webhosts are known to do, you can omit the utm_ prefix from the feed URL and Matador will treat the query string variables as if they were utm_* variables. The above example URL, edited in this way, would look like this:

https://your-site.com/jobs/xml?source=XYZJobs&medium=Aggregator

We feel it is a best practice to use the utm_* when available, even though this solution will work for more web host configurations.

Customize Campaign Data via Developer Filter

Another method a developer can use to customize campaign data is via a developer filter. This will override any items passed via a Feed URL method (main or alternate) but ensures results even when the URL methods aren’t working.

The filter is matador_extension_feeds_url_query_args and was added in version 1.5.0 of the Extension plugin.

/**
 * Filter: Matador - Feeds Extension - URL Query Args
 *
 * @since 1.5.0
 *
 * @param array  $query_args
 * @param string $feed_name
 *
 * @return array
 */
$query_args = apply_filters( 'matador_extension_feeds_url_query_args', $query_args, $feed_name );/**
		 * Filter: Matador - Feeds Extension - URL Query Args
		 *
		 * @since 1.5.0
		 *
		 * @param array  $query_args
		 * @param string $feed_name
		 *
		 * @return array
		 */
		apply_filters( 'matador_extension_feeds_url_query_args', $query_args, $feed_name );

If you want to narrow the adjustments to a specific feed, you can use the second argument in the past filter, or use the dynamic filter added in 1.8.0:

/**
 * Filter: Matador - Feeds Extension - URL Query Args for [Feed]
 *
 * @since 1.8.0
 *
 * @param array  $query_args
 *
 * @return array
 */
apply_filters( "matador_extension_feeds_{$feed_name}_url_query_args", $query_args );