README.md

This is a helper function to customize KISSmetrics form tracking.

The original trackSubmit function automatically captures every single form field of a tracked form as a property in KISSmetrics. It also automatically identifies a user, if it detects that they filled out a form field with a name containing "email" or "username".

There are ways of forcing the function to ignore or include certain form fields, but for anything beyond that, you'd have to write custom JavaScript. The goal of this helper is to provide more configuration options when setting up form tracking in KISSmetrics, to prevent custom code from being required.

Usage

(Please see attached usage file for code sample)

The function takes an element ID/class name, and the name of the event to be fired as arguments, just like the original trackSubmit. However, the super function also takes an object containing configuration options as a third argument.

The options object can include two keys: identify, and properties. The value for the identify key should be the name of the input element you want to identify your users with (if you decide not to include the identify key, then the user will remain anonymous). The value for the properties key, should be another object containing a mapping showing what KISSmetrics property to save each input value to. Only fields specified in the properties object will be tracked.

If a user filled out the example form below with values of "foo", "bar", and "baz" for each of the inputs, this is what would happen:

An event titled "form submitted" is triggered, property name 2 is assigned a value of "bar", and property name 3 is assigned a value of "baz". (this is because we specified that we want whatever the user fills into input with name "fieldname2", to be saved to a property titled "property name 2"). Additionally, the user will now have an identity of "foo", because we specified that was the form field to identify with.

example_usage.html

<form id="sampleID">
  <input type="text" name="fieldname1">
  <input type="text" name="fieldname2">
  <input type="text" name="fieldname3">
  
  <input type="submit" value="Submit">
</form>


<script>
  superTrackSubmit("#sampleID", "form submitted", {
    identify: "fieldname1",
    properties: {
      "fieldname2":"property name 2",
      "fieldname3":"property name 3"
    }
  });
</script>

superTrackSubmit.js

function superTrackSubmit(selector, eventname, opts){
  var selectorObj = {
    prefix: selector.substring(0,1),
    selector: selector.substring(1)
  }, elem, fields = [], KMObj = {}, newAlias;
  if (selectorObj.prefix == "#"){
    elem = document.getElementById(selectorObj.selector);
  } else if (selectorObj.prefix == "."){
    elem = document.getElementsByClassName(selectorObj.selector)[0];
  }

  elem.addEventListener('submit', function(e){
    for (var i=0;i<e.target.elements.length;i++){
      if (e.target.elements[i].nodeName == "INPUT"){
        fields.push(e.target.elements[i]);
      }
    }

    for (var k in opts.properties){
      for (var x=0;x<fields.length;x++){
        if (k == fields[x].name){
          KMObj[opts.properties[k]] = fields[x].value;
        }
        if (opts.identify && fields[x].name == opts.identify){
          newAlias = fields[x].value
        }
      }
    }

    if (newAlias){
      _kmq.push(['alias', KM.i(), newAlias]);
      _kmq.push(['identify', newAlias]);
    }

    _kmq.push(['record', eventname, KMObj]);
  });
}