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 CommandBar (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 CommandBar.

User properties in perspective​

There are a number of ways to target users in CommandBar. 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 CommandBar 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 CommandBar 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 method in the CommandBar SDK
  2. Using the CommandBar API (docs coming soon — please message the team for access)

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 CommandBar 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 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

/api/{your_org_id}/bulk-identify​

Request Headers​

If you do not have an API key, please reach out to your CommandBar contact person.

{
	"X-API-KEY": YOUR_API_KEY,
	"Content-Type": "application/json"
}

Request Body​

The body must be an array of objects containing the user id to update and an object of properties to update. It must be valid JSON

[
  {
    "id": "1", // user ID
    "properties": {
      "animal": "dog"
    }
  },
  {
    "id": "2",
    "properties": {
      "animal": "cat"
    }
  }
]

Using user properties during 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 CommandBar 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.