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

Conversion events must be programmatically tracked 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.

Pages with dynamic content

Sometimes your paths can look like this: /products/d0819be03b83ec1e5, where the last part is an ID that fetches the page content dynamically from the server. All pages under /products use a similar layout and design.

On this case it makes sense to group these pages togeter because of following

  1. The goal is to make an optimal experience for all product pages, not for the individual ones
  2. You can enjoy very quick sampling on the single product page and make frequent optimizations for it
  3. Your analytical views are not bloated with hundreds of product 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>

This parameter accepts a space separated list of paths. For example:

shorten: '/products /profiles'

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()
})

route([path])

Starts tracking how the newly loaded page is consumed. Volument checks for mouse- and keyboard events to know whether the visitor is active or idle.

The optional path argument identifies the page, and it is displayed on all the analytical views. location.pathname is used by default.

The previously monitored page, if any, is being tracked to our servers.

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 over the interent.

Do not track- option

You can disable tracking for indiviual visitors too. A typical scenario is to respect the 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>