Solved

difference between built-in properties: "User ID" and "Identity"

  • 19 April 2022
  • 3 replies
  • 455 views

Userlevel 1
Badge +1

Hi, I have a question regarding the difference between two Heap built-in properties. What is the difference between “Identity” and “User ID”. User ID is explained here: https://developers.heap.io/docs/using-identify but I don’t see any apparent difference between that and https://developers.heap.io/reference/identity

icon

Best answer by jonathan 19 April 2022, 17:44

View original

3 replies

Userlevel 5
Badge +3

Hey @Mrosh — 

The primary difference is that User ID is assigned by Heap, and Identity is assigned by you. 

Let’s go a little deeper:

When a user first arrives at your site, Heap sets cookies. One of these cookies contains a userId value. We don’t know who the user is, you don’t know who this user is, but we set this anonymous userId so we can track the user’s activity on that device and browser. If the user visits from another device/browser, they will get another anonymous userId set in another cookie (or cookie equivalent on native mobile apps). Modulo the user clearing cookies or being subject to ITP 2.1, the id cookie persists for 13 months. 

So what about when a user logs in or otherwise lets you know who they are? That’s where the identify API comes in. You use that API to tell Heap that this anonymous user should actually be henceforth known as e.g. jonathan@mynewstartup.io. You can call this on every page, passing the value of the user’s identity. The user logs in on both devices; now Heap tracks activity across both devices/browsers under the same identity and you have a fuller view of the customer’s journey. Same goes for native apps, etc. The identity should ideally be canonical as in permanent. Usually there is already an identity your company uses internally, whether an email or an alphanumeric identifier. Your engineers will know.

Once the user is identified, the userId set in the cookie still exists, but the User ID property in Heap changes (to a hash of the identity, so it is unique). We use that value to create a map from the anonymous userId we set in the cookie to the hashed userId we created from the identity, so that all data from those two devices/browsers will be associated with the identified user. (You shouldn’t need to worry about any of that, but noting it since the User ID in Heap will change as we “resolve” the anonymous users to an identified user.)

I hope this helps clarify things!

 

Userlevel 1
Badge +1

Thanks @jonathan for your thorough reply and explanation. That’s actually what I thought at first, but the point of confusion was when I saw that identity is marked as a “Built-in User Property” and not as “via custom API”. Is there a reason that identity is still marked as “built-in” when we have defined it through identify API

Userlevel 5
Badge +3

@Mrosh It is a bit confusing, totally get it. I’ll take this feedback to the product team, thank you for sharing.

It’s “builtin” to the extent that when you call heap.identify(somevalue) it populates a very specific first-class attribute called Identity and not something custom like UUID

Glad I could help clear up the answer for you, would you mind going ahead and marking it as solved so others can find it more easily? :) 

Reply