User Properties

Whenever the pixel loads, you can include User properties (data about the User) and it will appear in your Facebook Analytics dashboard under People > User Properties. You can then use these properties to further define your website visitors so you can analyze their activities and evaluate the effectiveness of your conversion funnels.

To include user properties:

Set the User's ID, then
Set the User's Properties

Requirements

The pixel base code must already be installed on all of the pages where you will be including user properties.

Setting User ID

To set a User ID, call the pixel's fbq('init') function with your pixel's ID and a JSON object containing a uid property as additional parameters:

fbq('init', '<pixel-id>', {uid: '<user-id>'});

Placeholder	Description
`<pixel-id>`	Your pixel's ID.
`<user-id>`	A unique combination of letters and numbers that identifies the User. Maximum length 99 characters. Do not use any personally identifying information, such as names or email addresses.

For example:

fbq('init', '283859598862258', {uid: 'abc123'});

Setting User Properties

To set User properties, call the pixel's fbq('setUserProperties') function with your pixel's ID and a JSON object containing your properties as additional parameters:

fbq('setUserProperties', '<pixel-id>',
  {
    <user-property>: '<property-value>', 
    ...
  }
);

Placeholder	Description
`<pixel_id>`	Your pixel's ID.
`<user-property>`	A predefined property name, or custom property name. Predefined property names must start with a dollar sign (`$`). Custom property names must be less than 40 characters and contain only letters, numbers, hyphens(`-`), or underscores. You can include up to 100 custom properties. Pre-defined properties do not count against this limit.
`<property_value>`	A string less than 100 characters. If the property already exists for the set User ID, the new property value will overwrite the existing value.

For example:

fbq('setUserProperties', '283859598862258', 
  {
    $state: 'California',
    $city: 'Menlo Park', 
    shoeSize: '11',
    shoeWidth: 'D',
    subscription: 'premium'
  }
);

Predefined User Properties

The pixel supports the following predefined User properties. All predefined User properties must begin with a dollar sign ($):

Pre-Defined User Property Name	Description
`$account_created_time`	The UNIX timestamp when the user account was created.
`$city`	The city in which the user lives.
`$country`	The country in which the user lives.
`$currency`	The preferred currency of the user.
`$gender`	The gender of the user. To get consistent analytics, set this to m or f.
`$install_source`	The source from which the user installed your app.
`$language`	The preferred language of the user.
`$state`	The state in which the user lives.
`$user_type`	The type of the user. You define the types to get the analytics results you want.
`$zipcode`	The zip code of the user.

Example

The following example shows how to set the User ID abc123 for a pixel with the ID 283859598862258 with a mix of predefined and custom User parameters:

// Set the User ID
fbq('init', '283859598862258', {uid: 'abc123'});

// Set the User Properties
fbq('setUserProperties', '283859598862258', 
  {
    $state: 'California',
    $city: 'Menlo Park', 
    shoeSize: '11',
    shoeWidth: 'D',
    subscription: 'premium'
  }
);