Sending hits programmatically from JavaScript

In this article we would like to give you some inspiration about how you can take over control and generate hits programmatically from JavaScript.

To be able to do this you need to get a reference to the KeytilesTrackingApi object which belongs to your Container.

Content of this page

• # Step 1 - basic bootstrapping
• # Step 2 - firing a hit programmatically
• # Step 3 - hit sending result callback

Step 1 - basic bootstrapping

The tracking script is loaded asynchronously into the page - so to do that we need is to define a callback function and let Keytiles tracking script know about this. The following code does the basics:

<script type="text/javascript">

	/**
	 * Our callback method
	 * 
	 * @param {KeytilesTrackingApi} keytilesTrackerApiObject- the Keytiles API object instance
	 */
	function onKeytilesTrackerAvailable(keytilesTrackerApiObject) {
		// we can work with the keytilesTrackerApiObject here
		console.log("tracking became available for containerId: "+keytilesTrackerApiObject.containerId;
	}

	/**
	 * We need the help of the keytilesTrackingConfig object Keytiles recognizes
	 */
	var keytilesTrackingConfig = {
		// let's switch off the auto-tracking mechanism
		autoTrackingEnabled: false,
		// and setup our callback function which will be called as soon as tracking script was initialized
		onTrackerAvailableCallbackFunc: onKeytilesTrackerAvailable
	};

	/**
	 * and now let's pull in the tracking script!
	 */
	(function () {
	  var kt = document.createElement('script');
	  kt.type = 'text/javascript';
	  kt.async = true;
	  kt.src = document.location.protocol+'//scripts.keytiles.com/tracking/<your-container-id>/stat.js';
	  var s = document.getElementsByTagName('script')[0];
	  s.parentNode.insertBefore(kt, s);
	})();
	
</script>

Step 2 - firing a hit programmatically

Cool! Now our onKeytilesTrackerAvailable() method is invoked and we get the reference to the KeytilesTrackingApi object. But we do not do too much with it right? Let's change this!

Now we will fire the hit using the Api object we have - just enhance the method a bit!

/**
 * Our callback method
 * 
 * @param {KeytilesTrackingApi} keytilesTrackerApiObject- the Keytiles API object instance
 */
function onKeytilesTrackerAvailable(keytilesTrackerApiObject) {
	// we can work with the keytilesTrackerApiObject here
	console.log("tracking became available for containerId: "+keytilesTrackerApiObject.containerId;
	
	// we build the hit object
	var hitOptions = KeytilesTrackingApi.buildHitOptions();
	// and now we send it
	keytilesTrackerApiObject.trackEvent(KeytilesTrackingApi.EVENTTYPE_PAGEVIEW, hitOptions);
}

 In the above example we have used

• The KeytilesTrackingApi.buildHitOptions() static method - which returns an object
• Then we passed that to the .trackEvent() instance method to send the hit into the default Container.

Step 3 - hit sending result callback

Let's make one more step! We add a callback so we will know when the hit sending was finished - and we will also know the result of it

Let's enhance our mechanism a bit further! We add the onKeytilesHitSent() method and wire that in.

/**
 * Our hit-finished callback method
 *
 * @param {boolean} wasSuccess - was sending successful?
 * @param {string} containerId - the target containerId the hit was sent to
 * @param {object} hitOptions - the hit attributes object
 */
function onKeytilesHitSent(wasSuccess, containerId, hitOptions) {
	console.log("hit for tile "+hitOptions.tileId+" was sent to container "+containerId+" with result: "+wasSuccess);
}

/**
 * Our callback method
 * 
 * @param {KeytilesTrackingApi} keytilesTrackerApiObject- the Keytiles API object instance
 */
function onKeytilesTrackerAvailable(keytilesTrackerApiObject) {
	// we can work with the keytilesTrackerApiObject here
	console.log("tracking became available for containerId: "+keytilesTrackerApiObject.containerId;
	
	// we build the hit object
	var hitOptions = KeytilesTrackingApi.buildHitOptions();
	// let's add our callback
	hitOptions.resultCallbackFunc = onKeytilesHitSent;
	// and now we send it
	keytilesTrackerApiObject.trackEvent(KeytilesTrackingApi.EVENTTYPE_PAGEVIEW, hitOptions);
}