medius / utm_form

Add UTM, referrer, landing page and other information to any lead generation form

What does it do?

It adds UTM, referrer, landing page and other information to any lead generation form. It adds this extra information as hidden fields on a form.

Here's a blog post discussing it in detail: http://bit.ly/1z0r3dN

Why do I need it?

If you want to know where each email list subscriber or lead is coming from, use this script to help with that. This is different from analytics tools where you know this information in aggregate.

e.g. You'll know that [email protected] originally came from Twitter, landed on page www.yoursite.com/promotion and visited your website 3 times before giving you his email address.

Information it adds to your forms:

• 5 UTM parameters - Any UTM parameters in the URL that a visitor used to come to your website will be added to the form
• 5 Initial UTM parameters (optional) - The UTM parameters in the very first URL that the visitor used
• Initial Referrer - The webpage where the visitor came from for the first time
• Last Referrer - The webpage where the visitor came from most recently
• Initial Landing page - URL of the page on your website where the visitor landed the very first time
• Number of visits - The number of times the visitor came to your website before filling your form
• Additional parameters defined in additional_params_map
• Additional initial parameters defined in additional_initial_params_map

How do I use it?

1. Just add this before the closing </body> tag at the bottom of your page. Make sure to change the domain.

<script type="text/javascript" charset="utf-8">
  var _uf = _uf || {};
  _uf.domain = ".example.com";
</script>

<script src="https://d12ue6f2329cfl.cloudfront.net/resources/utm_form-1.2.0.min.js" async></script>

There might be newer versions available in dest folder that are not yet available via CDN. Feel free to download the latest files in that case.

2. You need to make your forms accept the new fields. Based on the information available for a visitor, the fields added to your form will be,

• USOURCE - Value of utm_source if present
• UMEDIUM - Value of utm_medium if present
• UCAMPAIGN - Value of utm_campaign if present
• UCONTENT - Value of utm_content if present
• UTERM - Value of utm_term if present
• IREFERRER - URL of the initial referrer
• LREFERRER - URL of the last referrer
• ILANDPAGE - Initial landing page
• VISITS - Number of visits

Note: A new visit happens when the visitor comes to your website after more than an hour (can be customized as shown below).

How will my form look like?

Let's say your lead generation form looks like this before the script is added.

<form action="//terminusapp.us6.list-manage.com/subscribe/" method="post">
  <label for="mce-email">Email Address</label>
  <input type="email" value="" name="email" id="mce-email">
  <input type="submit" value="Subscribe" name="subscribe">
</form>

Once the script is added, your form will look like this after the page is loaded.

<form action="//terminusapp.us6.list-manage.com/subscribe/" method="post">
  <input type="hidden" name="VISITS" value="5">
  <input type="hidden" name="IREFERRER" value="http%3A//google.com">
  <input type="hidden" name="LREFERRER" value="http%3A//twitter.com">
  <input type="hidden" name="ILANDPAGE" value="http%3A//www.terminusapp.com/blog/">
  <input type="hidden" name="USOURCE" value="twitter">
  <input type="hidden" name="UMEDIUM" value="social">
  <input type="hidden" name="UCAMPAIGN" value="awareness">

  <label for="mce-email">Email Address</label>
  <input type="email" value="" name="email" id="mce-email">
  <input type="submit" value="Subscribe" name="subscribe">
</form>

When someone submits the form, all the extra information is also sent along with the email address.

You'll need to make sure that your form can accept these values. If it is a Mailchimp form, configure it to accept these fields. Same for ConstantContact, CampaignMonitor, Hubspot, ActiveCampaign or any other service.

Customize your forms

If you would like to customize how fields get added to your form, following options are available:

<script type="text/javascript" charset="utf-8">
  var _uf = _uf || {};
  _uf.domain                     = ".example.com";

  _uf.utm_source_field           = "YOUR_SOURCE_FIELD"; // Default 'USOURCE'
  _uf.utm_medium_field           = "YOUR_MEDIUM_FIELD"; // Default 'UMEDIUM'
  _uf.utm_campaign_field         = "YOUR_CAMPAIGN_FIELD"; // Default 'UCAMPAIGN'
  _uf.utm_content_field          = "YOUR_CONTENT_FIELD"; // Default 'UCONTENT'
  _uf.utm_term_field             = "YOUR_TERM_FIELD"; // Default 'UTERM'

  _uf.initial_utm_params         = true; // Enable the tracking of initial UTM Parameters
  _uf.initial_utm_source_field   = "YOUR_INITIAL_SOURCE_FIELD"; // Default 'IUSOURCE'
  _uf.initial_utm_medium_field   = "YOUR_INITIAL_MEDIUM_FIELD"; // Default 'IUMEDIUM'
  _uf.initial_utm_campaign_field = "YOUR_INITIAL_CAMPAIGN_FIELD"; // Default 'IUCAMPAIGN'
  _uf.initial_utm_content_field  = "YOUR_INITIAL_CONTENT_FIELD"; // Default 'IUCONTENT'
  _uf.initial_utm_term_field     = "YOUR_INITIAL_TERM_FIELD"; // Default 'IUTERM'

  _uf.initial_referrer_field     = "YOUR_INITIAL_REFERRER_FIELD"; // Default 'IREFERRER'
  _uf.last_referrer_field        = "YOUR_LAST_REFERRER_FIELD"; // Default 'LREFERRER'
  _uf.initial_landing_page_field = "YOUR_INITIAL_LANDING_PAGE_FIELD"; // Default 'ILANDPAGE'
  _uf.visits_field               = "YOUR_VISITS_FIELD"; // Default 'VISITS'
  
  _uf.additional_params_map      = {
    affiliate: "AFFILIATE"
  }; // Maps affiliate parameter to AFFILIATE form field
  _uf.additional_initial_params_map      = {
    affiliate: "IAFFILIATE"
  }; // Maps the initial affiliate parameter to IAFFILIATE form field

  _uf.secure                     = true; // Enable secure cookies
  _uf.sessionLength              = 2; // In hours. Default is 1 hour
  _uf.add_to_form                = "first"; // 'none', 'all', 'first'. Default is 'all'
  _uf.form_query_selector        = 'form[action="/sign_up"]'; // custom form selector. Default is 'form', to select any form.
  _uf.decode_uris                = true; // Decode URLs before populating the form. e.g. use "https://" instead of "https%3A//".
                                         // NOTE: This will decode the entire URL and, in rare cases, may have side effects.
</script>

<script src="https://d12ue6f2329cfl.cloudfront.net/resources/utm_form-1.2.0.min.js" async></script>

More Questions?

What happens if someone visits a bunch of pages on my website/blog before filling the form?

It doesn't matter. As soon as they land on your website, the script saves the information in a cookie. This cookie is valid for 365 days. It adds this information to your form from the saved cookie.

What's the session length for?

It's used to count the number of visits. If someone comes to your website after the session has expired, it will be counted as a new visit.

Can I look at the code?

You are on Github and all the code is available above. Knock yourself out. Even better, send a pull request and we can make it better together.

Development

Utm Form is written in CoffeeScript and compiles to Javascript.

Setup

1. Clone the repository
2. Make sure you have node and npm installed: brew install node.
3. Install the required packages: npm install.

Compiling

Run gulp build

This will compile the CoffeeScript and also minify it. The generated files can be found in dest folder.

utm_form's Issues

Setting to use secure cookies

I would suggest you provide a setting to enable secure flags on all utm_form cookies.

Can't get script to work - cookie not set

Hi - this is a great idea and actually (should) perfectly solve a problem i've been facing recently. However, after installing it I can't get it to work!
I'm not 100% what the cookie is called that it should be setting, but I can't see one i don't recognise in developer tools. Also, the forms fields I've added to my lead capture form don't appear to be getting populated either.
A couple questions:

1. What is the cookie called that should get set?
2. Does the script add the new fields to the form itself, or do they need to be there in the first place?
3. If you already have the fields in the form and you're using custom field names (because their generated by a CMS for example) and in the script code the custom form field names are set, does the script handle a situation where not all the fields are present (i'm only really interested in campaign, source and medium at present, so they're the only ones i've added to my form)

Thanks in advance for you help!

P.S. There is a missing closing quote from the script source attribute in the last code example in your readme.md file. I'd change it and issue a pull request but I've no idea how this stuff works! sorry.

Last parameters are inherited

Noticed just now that the utm and additional last parameters are not true but inherited. E.g.:

Visit 1: utm_parameter=1
cookie value = 1
form value = 1

Visit 2: utm_parameter=2
cookie value = 2
form value = 2

Visit 3: utm_parameter missing
cookie value = 2 (inherited)
form value = 2 (inherited)

This is caused by the check if (this.utmPresentInUrl()) inside the UtmCookie class constructor. Same applies to additional parameters because of if (this.additionalParamsPresentInUrl()).

Should the condition be removed? So the utm and additional last parameters will be null if not present and the resulting data will be more consistent. Otherwise an option to track last values can be added and if true it will write utm and additional last parameters with null values if not present inside the URL.

@medius what do you think about that?

Cookies store url-encoded column character in URLs

There seems to be a bug causing the values for initial landing page, initial referrer and last referrer to be stored as https%3A//www.domain.com instead of https://www.domain.com.

Support hash-mode routers

React and Vue routers by default use hash-mode which generate URLs like http://example.com/#/signup?utm_medium=sample

window.location.search is used here to find the search params which is empty string in case of these kind of URLs. Hence passing params in such URLs does not set them in forms.

Can we please support the hash URLs as well?

Support for Mailchimp's subscriber pop-up?

Hi! I've been trying hard to add UTM information about subscribers to my list, but without luck so far. Your script was a great lead, but the problem is be that we are using Mailchimp's popup generator, which works via iframes. Is there any way to track the parameters with the subscriber pop-up?

Additional setting "campaign cookie expiry days"

Another expiry time could be set for the campaign-related cookies ('utm_source', 'utm_medium', 'utm_campaign', 'utm_term' and 'utm_content') as Google Analytics handles these separately, too.

It could default to the Google Analytics default of 6 months, but be adjustable like the others.

What do you think?

UTM

Case sensitive to UTM names in URL

I noticed that when I try from a URL with "UTM_SOURCE=foo", the form does not populate with the UTM Source parameter. However, when the URL has a lowercase property – "utm_source=foo" – then it does.

Feature Request: Specify form(s) to add / omit [class or data-attribute]

@medius this is the business, thanks for sharing 👊

One question (and I will dig a little to figure out but maybe you have a quick answer): is there a way to specify which form(s) they should / not be applied to if there are multiple on the page? e.g. I have a page that has four forms: a search form, product add to cart, inventory alerts list, and a newsletter signup – I really only want these additional fields applied to the latter.

string' of 'escape' is deprecated.ts(6387) lib.es5.d.ts(88, 4):

should we replace the:

 document.cookie = this._cookieNamePrefix + name + '=' + escape(value) + cookieExpire + cookiePath + cookieDomain + cookieSecure;

with:

document.cookie = `${this._cookieNamePrefix}${name}=${encodeURIComponent(value)}${cookieExpire}${cookiePath}${cookieDomain}${cookieSecure}`;

Feature request: Add ability to populate forms if they are generated after page load

On some webpages, forms aren't exposed until a user click. Or it's possible some site generates forms after page load, after the script gets run. Feature request is to be able to populate these forms.

I created a proof-of-concept but am unable to create a PR at the moment because:

1. I've never used CoffeeScript so the POC is modifying vanilla JS
2. You may want this designed slightly differently. Current approach runs every second, and makes sure not to populate the same form more than once.

Use of while loop for condition evaluation

utm_form/lib/utm_cookie.coffee

Lines 56 to 57 in d7165cb

	while c.charAt(0) == ' '
	c = c.substring(1, c.length)

Should we use if instead?

Default session length and cookie expiry to match Google Analytics

Shouldn't the default session length and cookie expiry match the defaults in Google Analytics (30 min and 2 years)?

utm_form defaults to 1 hour and 1 year.

What do you think?

HTTP_REFERRER contains utm_* parameters, but added form fields is empty

In my case I check HTTP_REFERRER server globals and USOURCE...UCONTENT parameters in post function. And although HTTP_REFERRER contains url with utm tags, in the corresponding form fields these values are empty (value="null") . How does this happen?