kissmetrics

The Kissmetrics Developer Hub

Welcome to the kissmetrics developer hub. You'll find comprehensive guides and documentation to help you start working with kissmetrics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Support    

The Data Model

People, Traits, Events and Properties

The Kissmetrics data model is comprised of four components: people, traits, events, and properties. Understanding these concepts is vital to being able to analyze the data you are collecting. A person is our representation of a user visiting your site. A person has traits that describe them, and they can also perform events. Similar to how people are described by traits, events are described by properties.

What are people?

People are the visitors on your sites. A person in Kissmetrics represents the physical person behind the computer that came to view your blog, website or app.

To understand how people are identified within Kissmetrics, take a look at Identities section.

What are traits?

Traits are additional bits of information describing your users. By using traits you are able to segment reports and dive deeper into your data.

Traits are passed as key-value pairs.

If you are using JavaScript to track on your site, you will automatically track some traits, including:

Trait Name
Description
Property Value Example

Campaign ID

The customer's unique identifier

abc123=

Campaign Source/medium/name

When a link directing to your site is using UTM parameters

Linkedin

KM Referrer

The URl that the visitor came from

www.example.com/blog/post1

KM Landing Page

The first page a user visited at the start of a session

www.kissmetrics.com

KM Returning

Whether the user is new or returning

Returning

KM Device Type

This is the device being used by the user

Computer vs Smartphone vs Tablet

KM Device Category

The type of device the user is operating

Computer vs Mobile

KM Screen Resolution

The size of the user's screen

1280x800

KM Operating System

The operating system of the above device

Mac OS X

KM Operating System Version

The version of the above operating system

Mac OS X 10.11.6

KM Browser

This is the browser that is being used by the user

Safari

KM Browser Version

The browser and version the user is running

4.2

KM City

The city from where the user is visiting your site

Boston

KM Region

The state or region from where the user is visiting your site

California

KM Country

The country from where the user is visiting your site

United States

KM Continent

This is the Continent from where the user is visiting your site

Europe

What are events?

Events are the actions that your users are taking on your site or within your app.

Event Live

If you are using JavaScript to track on your site, you will automatically track some events, including:

Event Name
Description

Visited Site

The event will be triggered upon each visit to the site (with up to a 30-minute window of inactivity accounted for before re-firing another Visited Site event)

Search Engine Hit

The event will be triggered upon arriving to the site from a search engine

Ad Campaign Hit

The event will be triggered from any ad campaign tagged with UTM parameters, or any Adwords campaign.

These automatically tracked events are a great start but you will also want to track many events on your own. In Kissmetrics, we refer to these as "Custom Events". Some examples include:

Event Name
Description

Signed Up

This event will be triggered when a visitor completes the sign-up

Logged in

The event will be triggered any time a visitor logs into your site or application

Completed check out

This event will be triggered when a visitor completes the checkout process

Subscribed to newsletter

This event will be triggered when a visitor subscribes to your newsletter

What are properties?

Properties are additional bits of information describing your user events. By using properties you are able to segment reports and dive deeper into your data. We highly recommend using properties on your events liberally.

Properties are passed as key-value pairs. Some of our traits, such as Campaign Name and Campaign Source, double as properties for the purpose of analyzing the built-in events mentioned above.

These starter properties are helpful, but you will also want to track your own. Some examples include:

Property Name
Description
Property Value Example

Product Viewed

The name of the product the user viewed

Leather Notebook

Promo Code

The promo code that was used during checkout

SUMMERSALE

Video Played

The name of the video that was watched by the user

Beginners Guide

It's worth noting that, for now, some of our older reports treat Properties as if they are Traits - but going forward, reports will be updated to support this new data model.

Now that you understand these concepts separately, let’s see how they all work together.

Janet is a first-time visitor to your e-commerce site. She originally arrived at the site from a post she saw on a fashion blog. While she was on your site, she viewed 2 dresses, added 1 to her shopping cart, created an account and ultimately left without buying anything.

To borrow some terminology from our JavaScript library, our code is going to record some events and properties and set some traits for Janet.

Record Visited Site
Set KM Returning:No
Record Viewed Product Product:Red Dress
Record Viewed Product Product:White+Gold Dress
Record Add to Cart Product:White+Gold Dress
Record Account Created Referral Code:AZCO-B4-N
Set Account status:Active

This example is hiding an important distinction between Properties and Traits, beyond "one gets recorded with events and one doesn't:" if you segment by Viewed Product's "Product" property, you may see "Red Dress" or "White+Gold Dress" (or both) depending on the way you choose to segment (First value will always show Red, for instance, while segmenting for the most recent value will return White+Gold). On the other hand, if you segment by Add to Cart's "Product" property, it will only ever return White+Gold Dress no matter how you slice it - this is because of the way Properties are tied to events. As far as our newer reports are concerned, the "Product" from "Add to Cart" and the one from "Viewed Product" are completely different.