Back to Docs

Variance.js

On This Page

If you’re familiar with CDPs like Segment or RudderStack, you’re likely familiar with the basic functionality of Variance.js. At its basic, Variance.js makes it easy to send data directly to Variance through either your Javascript frontend or backend. Variance.js is compatible with Segment and handles data the exact same way.

At its core, Variance.js supports sending data in a few different ways:

  • Identify: for who the customer is
  • Track: for what the customer is doing
  • Page: for which page the customer is visited
  • Group: for which organization or company the customer is part of
  • Alias: for stitching together multiple identities

Best Practices

Our thoughts from seeing hundreds of CDP implementations.

  • Don’t boil the ocean. Knock out the key events you know you want first and set up an easy way to add more as you realize you need them. Lots of Segment projects fall over trying to reach perfection.
  • Don't go crazy with properties at first. Less is more at the beginning. Don’t load up your events with properties you aren’t sure you’ll need. As you see data start to flow you'll be able to figure out where you need more properties and where to consolidate events.
  • Use a good identify method for accounts. Group is one approach, but it’s a bit complicated, the simpler one is to include `company.id` and `company.name` traits with each identify call if your system supports sending data that way (also be sure to include email trait).
  • Try to use reserved traits when possible. There are a number of reserved traits for things like email, name, and title. When possible, use those as it will be easier for Variance and other systems to understand them.
  • Set up a separate source for your website and throw the JS on there. Lots of good stuff you can do with your web traffic—both intel from logged-in users who are visiting various pages to touting anonymous and identified traffic. Don’t worry about anything but page views at the beginning there.
  • Use the noun + past-tense verb structure for your track events. If you stay consistent with that it's easier to work with. That would mean `Form Submitted` or `Video Viewed`.

Getting Started with Tracking

Here's a very simple list of events that every SaaS app should track:

  • Account Created
  • Account Deleted
  • Signed Up
  • Signed In
  • Signed Out
  • Invite Sent
  • Account Added User
  • Account Removed User
  • Trial Started
  • Trial Ended

Adding a Variance.js Connection

To get started with Variance.js you'll need to add a connection on your integrations page.

Just add your variance.js connection.

From there you will see a few fields:

  • Name: this is the name you are giving your connection. If it's going on your website you might want to call it `www.yourdomain.com`. This name will show up in the Variance interface.
  • Domain: this is the domain you will be installing Variance.js on. It's important to get this right, because we will only accept data from this domain.
  • Account matching: finally, you'll choose your account matching criteria.
Setting up your Variance.js connection

Installing Variance.js

When you create a new Variance.js connection we will give you a snippet to install on your website. You'll find that at the bottom of the Variance.js connection page. If you copy that snippet into your website's `<head>` tag you should be good to go.

Just copy that snippet

Alternatively, you can use Variance.js as a package with `npm install @variancehq/variance-js`. If you want to dig into the code, you can find it on Github.

Identify

`identify` is the way you associate users with IDs. You want to call `identify` when:

  • A user signs up
  • A user signs in
  • A user updates their information

In Variance, `identify` is what powers the contact list (and for many the account list as well). Here’s what a typical `identify` call would look like:

variance.identify("048e791c-3018-4dff-95b1-d9e9af7f87cb", {
	name: "Noah Brier",
	email: "[email protected]",
	company: {
          name: "Variance",
          id: “...”
      }
});

Let’s break down the components:

  • User ID: the `048e791c-3018-4dff-95b1-d9e9af7f87cb` represents an ID you store for the user in your database. This should obviously be unique and it’s a best practice to avoid using email addresses as User IDs as they might change.
  • Name: this is a property (known as a trait in this case) that you can arbitrarily add. Name would be a typical property you would want to include. (Recommended)
  • Email: same as name, a good thing to include (Recommended)
  • Company: this is a way to pass account information to Variance. When you set up Variance.js you can declare how you want to connect contacts to accounts and this is one method. (Recommended)

You can send any number of traits with an `identify` call and they can be passed in whatever way makes the most sense for your application. 

Reserved Traits

We follow the Segment standard for having a number of reserved traits that we display with priority in Variance. That list is:

  • `address` [object] (object optionally containing `city`, `country`, `postalCode`, `state`, or `street`)
  • `age` [number]
  • `avatar` [string]
  • `birthday` [date]
  • `company` [object] (object optionally containing `name`, `id`, `industry`, `employee_count`, or `plan`)
  • `createdAt` [date]
  • `description` [string]
  • `email` [string]
  • `firstName` [string]
  • `id` [string]
  • `lastName` [string]
  • `name` [string]
  • `phone` [string]
  • `title` [string]
  • `username` [string]
  • `website` [string]

What if I don’t have a User ID?

If you’re using Variance.js on a marketing site you’ll have many visits that come from users without a User ID. This isn’t a problem. Variance.js automatically assigns an anonymous ID to each visitor and will include that if you send data via `identify` without a User ID attached.

While you won’t be able to see fully anonymous visitors in Variance, we do offer ways to identify accounts that visit your site through our Leads add-on. Get in touch if you’d like more information.

Track

`track` is how you send events to Variance. Each action a user takes that you want to keep track of should be sent via a `track` call. Here’s what a track call looks like:

variance.track("User Signed Up", {
	plan: "Pro",
	title: "Head of Sales"
});

Just like the identify call, we can include any properties that make sense. As mentioned in the Best Practices, don’t boil the ocean at the beginning with your properties. Get to know the shape of your data and add properties as needed.

What is “Object-Action?”

That means instead of calling something Created Dashboard or Added User, you would put the “object” (dashboard or user in the example) and then the action (created or added). By settling on a naming convention like this you can help ensure some consistency across your rollout.

One of the questions we get most frequently is where should I start? The answer to this is going to be pretty specific to your product and the actions that are most important to you. If you are building a business intelligence tool, `Dashboard Created` is probably a key event, but if you offer project management software you’re probably more interested in `Task Created`.

With that said, there are a few basic events that every SaaS company needs:

  • User Signed Up
  • User Signed In
  • Invite Sent
  • Account Upgraded
  • Account Downgraded

If you need help building out your unique tracking plan, just let us know and we’re happy to hop on a call.

Using variance.js in a Browser

If you are using the library in a browser a User ID will be automatically added to the call. This means once you identify a user, subsequent page and track calls will include the User ID. Anonymous ID works in a similar way.

Page

`page` is the way you send page visits to Variance. You can think of it like a `track` event for page visits instead of other actions. (In Variance we lump `track` and `page` together under Event Types for simplicity.) Here’s what a typical page event looks like:

variance.page("Home");

That’s it. The library will automatically capture `title` and `url` as part of it.

In fact, if you’re using our snippet on your public website, unless you opt to control it, you won’t even need to call page. We will automatically call it for you on every page and include `title`, `path`, `url`, `referrer`, and `search`. 

Group

`group` is one way you can associate a user with a group or organization. Within Variance it is generally used to connect a Contact to an Account (and Variance only supports a 1:1 relationship between a User ID and a Group ID.

Here’s what a `group` call might look like:

variance.group("1ddd6007-f4cc-4b12-8a26-e96827ed7abe", {	
      name: "Variance",	
      plan: "Pro"
});

Reserved Traits

As for `identify` follow the Segment standard for having a number of reserved traits that we display with priority on Accounts in Variance. That list is:

  • `address` [object] (object optionally containing `city`, `country`, `postalCode`, `state`, or `street`)
  • `avatar` [string]
  • `createdAt` [date]
  • `description` [string]
  • `email` [string]
  • `employees` [string]
  • `id` [string]
  • `industry` [string]
  • `name` [string]
  • `phone` [string]
  • `plan` [string]
  • `website` [string]

One note: if you include `website` we will default to that as the domain for the account.

Alias

`alias` is how you associate two identities together. It’s most commonly used for cases when you use an email address as a User ID prior to assigning a real User ID to the prospect. Imagine, for example, I was a prospect to your website and had signed up for your newsletter. When I signed up you used `[email protected]` as my ID. Now I’ve signed up for a free trial and have been assigned the ID `a20dd3df-235b-40f3-9c5a-3439a8263060`. You want to merge the two profiles together and you can do it with `alias`. It’s as simple as:

variance.alias("a20dd3df-235b-40f3-9c5a-3439a8263060")

What’s going on behind the scenes is that our library is inserting `previousId` automatically and using the ID you pass into the `alias` call as the new User ID. The Variance app will take the instruction and merge the profiles.

React Example

If you are using Variance.js in react, here's an example of what that might look like:

import { VarianceJs } from '@variancehq/variance-js'
import { useEffect, useState, createContext, useContext } from 'react'

const VarianceContext = createContext(undefined)

function useVariance() {
  return useContext(VarianceContext)
}

export function App() {
  const [variance, setVariance] = useState(undefined)

  useEffect(() => {
    void VarianceJs.load('').then(setVariance)
  }, [])

  return (
    
      
    
  )
}

function TrackButton() {
  return (
    
  )
}

You can find the full repository on Github if you want to learn more.

Last Updated: 
March 15, 2022