Home Data Types Properties Stateful vs. stateless properties

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

Stateful vs. stateless properties

In this article you'll learn:

  • The difference between stateful and stateless properties in Heap.
  • How to track the history of stateless properties.

Overview

What does it mean for a property in Heap to be stateful or stateless?

In essence, you can think of stateful properties as keeping a history of their values, while stateless properties only keep the latest value. This article from Redhat gives further explanation of this “state of being” concept.

Stateful Properties

In Heap, a stateful property keeps the history of its previous values. New values do not override old values.  

The following Heap properties are stateful:

For example, let’s say you want to know all the different browsers a specific customer uses to look at your website. We want to know which browser was used each time they had a session, not just the most recent browser they used. It would not be useful if the value of this property was replaced every time a new browser was used. By using the built-in Session Property Browser, we can query a history of all the browsers they have used.

In the chart results below, we can see that this customer likes to use the latest version of Chrome. They used Chrome version 111 in March, and they switched over to version 112 in when it came out in April. 

The built-in User Property Initial Browser tracks the name of the user’s browser during their first session

Stateless Properties

In Heap, a stateless property has one value for all time, which gets overridden every time you send it a new value. It does not keep the history of previous values. 

The following Heap properties are stateless:

For example, let’s say you have a user property for home address. A user has their home address collected in your app, then later they move and they input their new home address. Because this user property is stateless, as far as Heap is concerned, this user has only ever had the present address. We can’t tell you what the old value (the user’s previous home address) was or how it changed. 

When you change the value of a stateless property in Heap, this change is permanent. You lose the old value and there is no way to get it back.

Tracking the history of a stateless property

By default, the history of a stateless property is not stored. But what if you want the history of a user or account property? 

For example, let’s say you have an account property that tracks if an account is “paying”. If you try to make a chart that tracks how many paying accounts you had in the last 3 months, it will not be accurate. What if an account was paying two weeks ago, but they canceled yesterday? That account would not be counted as “paying”, even though they were up until yesterday. 

If you want to factor in what status a user’s account had at the time they performed a specific event (ex: the history of their account status), we recommend adding this data point as an event property using the addEventProperties API. You will need an engineer to modify the code of your website to use this API. 

Unlike autocaptured data, new properties that you add will not be retroactive and will only be collected from the point of implementation going forward.

Snapshots: No-code property tracking 

Another way to track properties historically is to use Snapshots. Snapshots are created in the Heap app and don’t require an engineer to modify your site’s code. 

Compared to Heap’s APIs, Snapshots have some limitations: they can only capture data on your webpage, and each individual Snapshot is limited in scope to the specific event associated to it. To learn more about how to create Snapshots, see Snapshots Overview for some common examples.