Skip to main content

User Properties

Have you ever filled out a census? Boring, right. But have you ever stopped to think why you have to fill out this long form for the government?

Well, we don’t actually know, but we imagine it’s so that the government can both better understand its user base and help direct services to you that are relevant.

Inspired, we do the same thing at Command AI (but without the slow boring form part). User properties allow you to maintain an up-to-date model about your users — describing who they are are and what they’ve done — that you can use for targeting experiences within Command AI.

User properties in perspective​

There are a number of ways to target users in Command AI. How do user properties compare to the other ways? Here’s a quick cheat sheet.

First of all, user properties can only be used for Who targeting - not Where or When. That’s because user properties relate to the identity of a user, including permanent (e.g. demographics) and semi-permanent (persisting across session) characteristics.

  • Built-in properties: these are properties that Command AI can calculate on your behalf, no setup needed. They include the user’s browser, operating system, etc.
  • Interactions: these are also built-in and allow you to track engagement with previous Command AI experiences like a nudge.
  • User properties: for storing custom properties about your users that persist from session to session like what product tier they are on.
  • Metadata: for storing properties about your users that should not persist session-to-session, perhaps the url of the page they are currently viewing.

Common examples of user properties​

Some common examples of user properties in practice include:

  • Revenue information: which subscription tier the user is on
  • Organization information: what organization the user is a part of
  • Feature availability: what features does the user in question have access (this is particularly useful for making sure you don’t show users irrelevant feature engagement campaigns)
  • Source: the channel where the user discovered the product (e.g. a blog post)

Ways to update user properties​

There are a few ways to specify user properties about a user:

  1. Using the boot Command AI SDK method
  2. Using the setUserProperties SDK method
  3. Using the Bulk Identify API

Using any of these methods allows you to update values for properties that have already been created or create new properties.

How to update user properties using the SDK​

The boot method takes an optional second argument that allows the client to pass a dictionary of key value pairs that correspond to user properties. These can be sourced from anywhere. The most common example of user properties passed to Command AI through this route come from the serialized user object that likely already exists on your client-side.

// Using boot to supply user properties
window.CommandBar.boot(loggedInUserId, {
  isPaid: false,
});

In addition, any properties that you pass to analytics providers like Segment and Heap or Amplitude are good candidates to pass to boot as user properties.

How to update user properties using the API​

The API route is the best approach to use when:

  • You want to update user properties in bulk. This API endpoint can handle up to 1000 users per request.
  • You want to add information to user properties that is available in other systems and not present in your app client-side

You can find more details about the endpoint here.

Using user properties for targeting​

Using user properties is simple. They are available in both the Audience creation interface and the custom Who targeting interface. Simply type or select the name of the user property, and specify the value it should take. You can use operators like less than, is greater than, etc for greater targeting flexibility.

Multiple user properties can be combined in a single targeting rule or audience.

User Property Targeting

FAQ​

Can I use a user property for targeting if its not available in my app client-side?​

Yes! User properties are stored in Command AI server-side, so they can be used for targeting even when values are not specified in your app client-side. A common example of when this would occur:

  • You use the API route to load in user properties from an external source
  • Those properties are not available in your client-side (and therefore not provided to the boot SDK method)
  • All properties are still available for targeting rules

How do I remove a property for a user?​

We recommend against doing this. It’s possible you’ll want to use the property in the future, and, for now, you can just stop referencing it in targeting rules.

However, if you need to do this, you can set the value of the field (through either the SDK or API) to null or an empty string.

How do I test to make sure my user properties are flowing correctly?​

You can see functional user properties in a couple of places:

  • Targeting: When building an audience, see what appears in the "User property" dropdown. Shared user properties will autopopulate, and once selected you can validate that the audience estimate appears accurate.
  • Tools panel: Log into your product, open the Command AI extension, and navigate to Tools > User Properties Inspector. From here, you can see which properties are flowing for the user you are currently logged in as.