Recently I had to implement KISSmetrics with Gravity Forms for a client. Now as both of these are quite popular services, one would have thought there would be extensive documentation on how to best combine the two. Well, you’d be wrong…until now. Let me present my quick guide to integrating KISSmetrics and Gravity Forms!

Please note that while KISSmetrics does have default form tracking, it does not work well with Gravity Forms since you need to be able to specify field names. Unfortunately, one of the limitations of Gravity Forms is that field names are dynamically generated and cannot be specified. Using the KISSmetrics default form tracking only gives you field names like Input 1, Input 2, etc. (not very useful). And, as you cannot tag an email field as “email” KISSmetrics is unable to identify and track the user as anything but their standard anonymous ID.

So, that leaves us with having to set up the KISSmetrics API and the documentation on this is a bit lacking. Initially I tried to set it up with only the JavaScript API, but quickly ran into some limitations. It became apparent that using the PHP API was the way to go. Here are the steps to do that:

1. Install the KISSmetrics Javascript Tracking Code

Using the default Javascript tracking code for your site will create the anonymized identities that you need to track new users. I recommend using Google Tag Manager for this. Be sure to test this in the KISSmetrics Live tracking section of the admin to make sure it is properly installed.

2. Install the KISSmetrics PHP API code

At this time, KISSmetrics seems to be between two versions of their PHP API code. Their website documentation refers to the old API interface while their Github page refers to the new API. It’s a bit confusing. I’m going to use the old km.php file for these examples.

First, create a directory called “KISSmetrics” under your active theme and copy the km.php file to that folder. Make sure that the directory and file have read permissions.

3. Modify WordPress to call the KISSmetrics API on Gravity Form submission

The main file you will be changing is functions.php under your active theme. You’ll need to use the Gravity Forms hook “gform_after_submission” to call the KISSmetrics API after the form is submitted.

First, add your KISSmetrics API key to the end of your wp-config.php file. You’ll find your API key in the KISSmetrics admin for your account.

define('ENV_KS_APIKEY','XXXXYYYYXYXXYXYYXYXYXYXYXY');

Next, edit the functions.php file under the active theme. First, you’ll want to include the KISSmetrics API, so add this line near the top of the file:

require_once 'KISSmetrics/km.php';

Now, you’ll need to add both a call to the function as well as the function itself to the bottom of the functions.php file:

// Member Signup Form (Form ID 3)
add_action( 'gform_after_submission_3', 'form3_handler', 10, 1);

function form3_handler($entry){
	KM::init(ENV_KS_APIKEY);	
	$email = $entry['2'];
	
	$data  = array('First Name'=>$entry['6'],'Last Name'=>$entry['7'],'Email'=>$email,'Phone'=>$entry['3'],'Heard About'=>$entry['5']);
		
	if (isset($_COOKIE['km_ai'])) {
		KM::alias($_COOKIE['km_ai'], $email);
		KM::identify($email);
		KM::record('Member Signup Form Completed',$data);
	}
}

Some notes on this code:

1. You’ll need to look up the form id under Gravity Forms. Use this ID for the add_action call as well as the handler (gform_after_submission_#, form#_handler). If you have multiple forms, you’ll need to duplicate this code using the different form IDs.
2. You can access the form fields with the $entry[‘#’] where the # is the ID of that form field. Use a code inspector to find the form field ids for each form.
3. The $data variable builds a list of all the form fields you want to submit to KISSmetrics. Edit as appropriate for your forms.
4. You want to both alias and identify the user by email in KISSmetrics. You can read more about this in “Understanding Identities.”
5. KM::record will record an event (name it what you want) and pass all  the data from the form to KISSmetrics.
6. You can test that this is working in the KISSmetrics admin under the “Live” section. Please note that if using the “My Activity” tracking section, once you identify yourself, your activity no longer appears there due to a bug on their site. This can lead to hours of wasted debugging (personal experience). Use the main Live tracking feature for all people. It will make results much clearer.

That’s it. Hopefully these examples save you a few days of trial and error, but hey someone had to do it!