Install Guide

We're not monetizing Zirality right now, so we decided to release the code open source – that means you get it for free! However of course that means a little bit more configuration to get it set up. Don't worry, even if you're not a developer you should be able to follow this step-by-step guide and get it working in less than ten minutes.

For this guide you're going to need access to Google Tag Manager and Google Analytics.

If you use a different tag manager (Segment, Adobe, Tealium) or analytics tool (Amplitude, Mixpanel, Heap) you should still be able to follow along.

Note: Zirality only works on the web, not within mobile apps.

The Code

This is the open-source code that you'll need to copy and paste across into your Tag Manager.

<script>
// # Zirality #
// Measure virality by tracking when users share links to your website.
// Available FREE (MIT license) at www.zirality.com

var ziralityID = localStorage['zirality:ID'];
var urlHash = window.location.hash;
window.dataLayer = window.dataLayer || [];if (!ziralityID){
   var ziralityID = new Date().getTime().toString(36).substring(0,5)+Math.random().toString(36).substring(2,7)+'-';
   localStorage['zirality:ID'] = ziralityID;
}if (urlHash.search(/#\w{10}-$/) == 0) {
   var referralID = urlHash.substring(1);    if (referralID == ziralityID) {
       // bookmarked link
       window.dataLayer.push({
           'ziralityLabel': 'bookmarked',
           'ziralityID': ziralityID,
           'event': 'zirality'
       });    } else {
       // viral referral
       window.dataLayer.push({
           'ziralityLabel': 'referral',
           'referralID': referralID,
           'ziralityID': ziralityID,
           'event': 'zirality'
       });
   }
} else {
   // normal pageview
   window.dataLayer.push({
       'ziralityLabel': 'pageview',
       'ziralityID': ziralityID,
       'event': 'zirality'
   });
}
window.location.hash = ziralityID;
</script>

This code generates a unique ID for every visitor to your website, and adds it to the URL in what's called a 'hash'. This doesn't interfere with any of your tracking parameters, and isn't normally even registered in your analytics platform as a separate URL, so it won't mess with any of your tracking or website functionality.

Note: one exception is SPAs, or Single Page Applications, which use the URL hash for navigation.

Because every visitor has a unique ID in the URL of every page they visit, when we see someone visiting the website using a link with one of these IDs in them, we know they came from someone sharing that URL. This let's us track the virality of our website content by tracking how many of our visits came via link sharing.

Installing this code is easy – simply copy and paste into Google Tag Manager as a tag that fires on every page.

Note: make sure to follow your company's policy on tracking and user privacy. Under GPDR and CCPA legislation you need explicit permission before tracking users with a unique ID.

Tracking Events

Once we see a user visiting the website with one of our IDs, we know they fall into one of two buckets – either they came via a viral referral, or they are visiting the site again after bookmarking a link. We can tell which of these events are happening because the code stores the unique ID for the user in local storage (like a browser cookie), and we can check if their stored ID matches the hash in the URL.

The code automatically fires one of three events into the dataLayer of the website, which is what Google Tag Manager reads to pickup the data it needs to fire events for your analytics tools and other vendors. If the user ID matches what was stored, we fire a 'bookmarked' event, if it doesn't we fire a'referral' event, and if it's just a normal visit without an ID, we fire a 'pageview' event.

Now that this data is being read by Google Tag Manager, we need to tell it what to do with the data.

First set up three variables, one each for ziralityID, referralID and ziralityLabel. In each case go to Variables > User Defined Variables > New > Variable Configuration > Data Layer Variable, and add the name. Make sure the name exactly matches each time "ziralityID", "referralID" and "ziralityLabel".

Now let's set up triggers. We need one for a bookmarked user visit, and another for a referral user visit, as these are the two interesting pieces of information we want to track. In both cases the process is the same: go to Triggers > New > Trigger Configuration > Custom Event. Enter "zirality" in the Event name field. Click on "Some Custom Events" then select ziralityLabel from the dropdown. Make sure you enter here the name exactly, "bookmarked" or "referral".

Now it's time to set up our tags. You could really fire this data into any platform you want now that you have your variables and triggers, but we're going to use Google Analytics to showcase how this works. For this stage we want to go to Tags > New > Tag Configuration > Google Analytics: Universal Analytics > Track Type 'Event'. You can name your event what you like, but I put 'zirality' as the Category, 'referral' as the Action and the {{referralID}} variable as the Label. That way I can not only track my viral visitors, but also who sent them!

Finally make sure you select your Google Analytics settings and add the correct trigger for the action, in this case 'zirality referral'. I recommend you make 'Non-interation Hit' equal 'True', as this will mean the event doesn't mess with your bounce rate stats. That's it – all you need to do now is publish and it'll work!

Pro tip: if you want to check it's working, go to Google Analytics > Realtime > Events, then visit your site with a made up code on the end of the URL to see the referral event in action. For example on my website I visit https://www.saxifrage.xyz/#12345abcde- (don't forget the trailing dash '-' on the end) and see the following in my Google Analytics account.

*Apple ITP*

If you aren't aware, Apple limits tracking on the Safari browser (on desktop and in mobile apps) using their Intelligent Tracking Prevention (ITP) software. This may limit the use of 1st-party cookies to any visit that looks to come from a URL with tracking parameters down from 7 days to 1 day. As of yet (Oct 6, 2020) I'm not seeing evidence this is impacting links with the ZIrality tracking ids in them, but you should do your own investigation.