Setting up Volument
The embed code
To install Volument, paste the following code on your HTML pages:
<!-- Analytics by volument.com --> <script async src="https://cdn.volument.com/v1/volument.js" onload="volument(your_token)"></script>
Imporant: Replace “your_token” with the actual token that you can get from your account.
After the code is in place, Volument starts measuring how your visitors engage with the site.
Tracking conversions
Volument collects engagement and retention data automatically without any configurations. However, all the key conversion events, like registrations and purchases, must be wired programmatically. This happens by calling the following methods on the right spot on your code:
volument.convertToLead()
Call this method when the visitor becomes a “lead.“ That is: they hand their email or phone number so you have a way to reach them.
volument.convertToCustomer()
Call this method when the visitor and converts to a customer by handing their payment information such as the credit card and no money is paid at the spot.
volument.pay(amount)
Call this method when the visitor hands their payment information and pays the given amount of money in the currency of your choice. The visitor is converted to a customer so no additional convertToCustomer call is needed.
volument.invite(peers)
Call this method when the visitor invites her friends or other associates to your product contributing to the viral growth. The visitor is converted to a “promoter”. The peers argument is the amount of people the promoter invited. Default is one peer.
Areas and topics
Volument extracts area and page information from your URLs. For example, in /blog/introducing-volument
the area is “blog” and the topic is “introducing-volument”. Volument is quite good at guessing these, but you should configure Volument to understand your exact website structure:
Custom areas
areas
configuration option specifies the areas on your website that you want to have a separate analysis. For example
<script src="https://cdn.volument.com/v1/volument.js"></script> <script> volument({ areas: ['blog', 'docs', 'partners'], token: your_token, }) </script>
Pathname parser
parser
option specifies a custom parser to extract areas and topics from your path names. Here's an example parser that would work nicely for Twitter.
<script> function twitterParser(path) { var main_areas = 'home explore notifications messages bookmarks'.split(' '), parts = path.split('/').slice(1) if (main_areas.includes(parts[0])) return { area: 'main', topic: parts[0] } return { area: parts[1] == 'status' ? 'status' : 'profile' } } volument({ token: your_token, parser: twitterParser }) </script>
Campaign configuration
Once you have created a campaign on the user interface you can either provide the campaign indicator on the query string or you can provide it with a campaign
configuration option. For example:
<script> volument({ token: '0049dc251', campaign: 'c1' }) </script>
By handing the campaign information on the client configuration you can keep the query string clean. Some developers are known to avoid links that contain tracking indicators.
Single-page applications
If your site is a single-page application (SPA) and routing is built around pushState
(PJAX, Turbolinks, or similar) you can use volument.route()
to emulate page switches, for example:
// turbolinks example document.addEventListener('turbolinks:load', function() { volument.route() })
route([path])
Call this method when the visitor is routed to a new page. After this Volument starts tracking how the new page is consumed. The path argument is optional and location.pathname
is used by default.
This website is actually a SPA, because we want to provide faster page loads for our visitors.
Cookie consent
We offer a specialized initialization method, volument.consent()
, to abstract all the complexities in the cookie consent dialogs. Please use the full version of the client volument-full.js (7.4K) in place of the default version volument.js (5.6K) as follows:
<!-- Analytics by volument.com --> <script async src="https://cdn.volument.com/v1/volument-full.js"></script> <script> volument.consent({ region: 'Europe', country: 'FI', token: your_token }) </script>
Consent configuration
token
The analytics token specific to your project. This is available on your account. Likewise all the configuration variables described above are passed described above are passed directly to volument.
Required
region
The region of the visitor. Setting this to “Europe” opens the consent dialog on the first page load of a session. The consent is not shown outside Europe.
Required
country
A two-letter country code of the visitor to see statistics about countries where the visitors wished not to be tracked.
Required
policy_url
Link to the privacy policy
Default: "https://volument.com/privacy"
link_target
Name of the target window where the privacy policy document is opened. Leaving this empty opens it in the same window.
Default: "policy"
consent_text
The content for countries, where opt-in is required. Any text inside brackets becomes a link to the privacy policy.
Default: "Allow [privacy-friendly analytics] to access your device?"
notice_text
The content for the European countries, where notice is enough. Any text inside brackets becomes a link to the privacy policy.
Default: "We use [privacy-friendly analytics] to improve the experience."
no_text
The label on the “no” button in consent dialog that disables tracking.
Default: "Not now"
yes_text
The label on the “yes” button in consent dialog that enables tracking.
Default: "Yes"
ok_text
The label on the “OK” button on a notice dialog.
Default: "OK"
use_css
Whether the default CSS styling should be applied on the popup. Setting this to false
allows you to style the dialog from scratch.
Default: true
dnt
Whether the navigator.doNotTrck
- setting should disable tracking. This also enables statistics for this setting.
Default: true
Detecting visitor's country
To show the banner to European visitors only, we must have away to detect where the visitor is coming from. One good way is to use a geo-location service. There are a lot of good services available and many of them are free up to a certain limit. We use ipgeolocation.io as follows:
// a geo-location function function geolocate(fn) { // return cached info var loc = localStorage.location if (loc) { loc = loc.split('/'); return fn(loc[0], loc[1]) } // use a location service $.get('https://api.ipgeolocation.io/ipgeo', { apiKey: 'your_key' }, function(loc) { var country = loc.country_code2, region = loc.continent_name // save to cache for later requests localStorage.location = country + '/' + region fn(country, region) }) } geolocate(function(country, region) { // start tracking, request consent if needed volument.consent({ token: '<our_token>', country: country, region: region, }, function(was_ok, reason) { // a callback function for custom stuff }) })