User properties

Setting properties

The easiest way to set properties is to add the properties to the identify function during the initial login.

• Identify the user and set the user properties

posthog.identify('user_id', {
    name: 'James PostHog', // also sets the display name in the PostHog UI
    email: 'hey@posthog.com',
})

// { name: 'James PostHog', email: 'hey@posthog.com' }

To update the properties of a user you can use set, set_once, and $unset. Depending on the integration library the actual function calls look a bit different, but internally they all work the same way.

• set: Set the property even if the property exists on the user

posthog.people.set( { location: 'London'  })

// { location: 'London' }

• set_once: Set the property if the property does not exist on the user

posthog.people.set_once( { initial_location: 'Rome'})
posthog.people.set_once( { initial_location: 'London'})

// { initial_location: 'Rome' }

All these methods can be used in properties with normal event capture:

• Set the properties through a capture

posthog.capture(
    'Set some user properties', 
    { 
        $set: { location: 'London'  },
        $set_once: { initial_location: 'London' },
        $unset: [ 'priority' ],
    }

When to use set and set_once?

Use set when we want the value to be the most recently sent value. For example, to update the email for a user.

Use set_once when we want to set the first value and it to never be updated afterwards, e.g. the first URL that referred a user to the site.

In summary: set always overrides, set_once only writes when the property doesn't already exist on the user.

For example:

posthog.people.set( { location: 'London'  })
posthog.people.set( { location: 'Rome'  })

// { location: 'Rome' }

posthog.people.set_once( { initial_location: 'London'  })
posthog.people.set_once( { initial_location: 'Rome'  })

// { location: 'London' }

Note: that we ignore the event timestamps and just process everything at ingestion time.

Sometimes we might want to mix set and set_once usage. Imagine, when we have some heuristics that help us determine a value, but users can also specify it. In these cases it might be beneficial to use set_once for the heuristically computed value and set for user specified value. This way we can ensure that the user specified value is always used, but if the user doesn't specify it, we can still use the heuristically computed value.

How are properties managed when merging or aliasing users

When an anonymous user is identified as user (A), all the properties of the anonymous user are added to user (A). If there is a conflict, the properties of user (A) are kept.

client.identify({
    distinctId: 'user_A',
    properties: {
        name: 'User A',
        location: 'London',
        timezone: 'GMT',
    },
})

client.reset()

// as an anonymous user
posthog.people.set({ name: 'Anonymous User', phone: '0800-POSTHOG' })

client.identify({
    distinctId: 'user_A',
    properties: {
        timezone: 'GMT+1', // daylight saving time
    },
})

// for user 'user_A', { name: 'User A', location: 'London', phone: '0800-POSTHOG', timezone: 'GMT+1' }

When a user (B) is merged into another user (A), all the properties of the user (B) are added to user (A). If there is a conflict, the properties of user (A) are kept.

client.identify({
    distinctId: 'user_A',
    properties: {
        location: 'London',
        name: 'User A',
    },
})

client.identify({
    distinctId: 'user_B',
    properties: {
        name: 'User B',
        location: 'Rome',
        phone: '0800-POSTHOG',
    },
})

posthog.alias('user_A', 'user_B')

// for user 'user_A', { name: 'User A', location: 'London', phone: '0800-POSTHOG' }

Any events sent to either user_A or user_B will be received under the same person.

Note: that the '[alias ID]' cannot be associated with multiple distinct ids.

Person Display Name

The person display name is the name that is shown in the PostHog UI. The person properties that are used as the display name can be configured in Project Settings.

Default user properties

It's often useful to set the email property for a user. This is useful for many of the apps, filtering users in the PostHog UI and as the Person Display Name.

The following properties are automatically set for all users when using the posthog-js library:

GeoIP Properties

By default, the GeoIP plugin is turned on which adds the following properties to all events.