Volument.js

Client API documentation

Installation

To install Volument, paste the following code snippet anywhere before your website's closing </body> tag:

<script src="https://volument.com/v1/volument.js"></script>
<a href="https://volument.com">Free A/B testing from Volument</a>
<script>volument('your_token')</script>

Please replace your-token with your token that you'll get after signing up for the service.

After the snippet is in place, Volument automatically tracks visitor activity and how they consume your content.

Tracking conversions

Volument tracks pageview- and visiting automatically. However, all the key conversion events, like registrations and purchases, must be wired programmatically. This happens with JavaScript as follows:

// visitor gave their contact info (email or phone)
volument.convertToLead()

// visitor subscribed to a paid plan
volument.convertToCustomer()

convertToCustomer()

Call this method when the vistor and converts to a customer by handing their payment information such as the credit card and no money is paid at the spot. This method is an alias to volument.pay(0) .

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.

identify(userId)

Call this method when you can uniquely identify the visitor. We use the supplied ID for two purposes:

  1. When the visitor uses different devices to browse your website, Volument uses this identity to merge those devices into a single account.
  2. We use the ID to track when the invited peers accept the invitation.

The required userId parameter is a case-sensitive string and must be fewer than 48 characters. No two users in your environment may share the same ID.

Do not identify users based on an anonymous ID, random ID, session ID, or any value that might change. Volument explicitly denies all attempts to use an email address as an identifier since we don't store such sensitive information on our system.

invite(userId)

Call this method when the visitor invites her friends or other associates to your product contributing to the viral growth of your product. The required userId parameter is the ID of the invited person.

pay(amount)

Call this method when the visitor hands their payment information and pays the given amount in your local currency. The visitor is converted to a customer.

Dynamically generated pages

Sometimes your paths takes the following form: /products/d03b83ec1e5, where the last part is an ID that identifies the page's content. It is adviseable to merge these paths together. Here's why:

  1. The goal is to optimize the layout for all similar pages, and not just for the individual ones.
  2. Data sampling is significantly faster because the page view data is collected from all the pages. You can make frequent optimizations because the statistical significance is reached sooner.
  3. Page listings on the Volument UI are not bloated with hundreds or thousands of individual pages.

You can truncate paths with a shorten parameter as follows:

<script src="https://volument.com/v1/volument.js"></script>
<a href="https://volument.com">Free A/B testing from Volument</a>
<script>
  volument({ token: 'your_token', shorten: '/products' })
</script>

You can provide multiple paths by separating them with a space character. For example:

shorten: '/products /categories /profile'

Or you can provide an array:

shorten: ['/tutorials', '/products']

Single-page applications

If your site is a single-page application (SPA) and routing is built around pushState (PJAX, Turbolinks, or similar) you can setup Volument as follows:

<script src="https://volument.com/v1/volument.js"></script>
<a href="https://volument.com">Free A/B testing from Volument</a>
<script>volument({ token: 'your_token', spa: true })</script>

After this you must track all page switches with volument.route() method, for example:

// turbolinks example
document.addEventListener('turbolinks:load', function() {
  volument.route()
})

In fact, the Volument website is actually build as a single-page application so we can provide faster page loads for our visitors.

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 optional path argument identifies the page, and it is displayed on all the analytical views. location.pathname is used by default.

Disable tracking

You can disable tracking with disabled option as follows:

<script>
  volument({ token: 'your_token', disabled: true })
</script>

For example it makes sense to disable tracking completely in a development environment. When tracking is disabled no data is sent to our servers.

Do not track- option

You can disable tracking for indiviual visitors too. One scenario is to look for navigator.doNotTrack configuration option on the browser. On this case the user has explicitly requested not to be tracked by web sites. For example:

<script>
  volument({ token: 'your_token', disabled: navigator.doNotTrack })
</script>

Learn Volument

{"title":"Volument.js / The client API documentation","style":"/learn/syntax","desc":"","url":"/learn/client-api","key":"client-api","created":"2019-01-17T06:05:43.539Z","modified":"2020-03-14T05:54:09.993Z","createdISO":"2019-01-17","modifiedISO":"2020-03-14"}