User Properties

User properties are properties and values that you create for a user. User properties allow you to create segments in the Facebook Analytics dashboard that allow you to better understand your audience by using things your know about your audience. For example, you can create a user property that tracks the frequent flyer status of a user that installs an airline mobile app.

To create user properties, you need the following:

  1. User ID-a unique combination of letters and numbers that identifies the user .
  2. User Properties-an open ended data structure composed of key-value pairs. Each key-value pair represents the property name value. User properties can be pre-defined or custom properties.

After you set the User ID and assign user properties, you can view this data in the Analytics dashboard for your app under People > User Properties.

Setting the User ID

Use the following code to set the User ID:

fbq('init', '<pixel_id>', {uid: '<userID>'});
Parameter Description

<pixel_id>

Your Pixel ID. Enclose the Pixel ID in single quotes ( ' ).

<userID>

The User ID that is a unique combination of letters and numbers to identify the user. The length of the user ID must be less than 100 characters.

Do not use any personally identifying information, such as names or email addresses in the User ID.

Enclose the User ID in single quotes ( ' ).

The User ID is stored in the device of the user and is included in the app events logged from that device.

Setting User Properties

Use the following code to set the user properties:

fbq('setUserProperties', '<pixel id>', 
        {<user_property>: '<property_value>', 
         <user_property>: '<property_value>',
         ...
        }
    );
Parameter Description

<pixel_id>

Your Pixel ID. Enclose the Pixel ID in single quotes ( ' ).

<user_property>

The name of the property. The name can be a pre-defined or custom property name. Pre-defined property names start with a dollar sign ($). A custom property name must be less than 40 characters in length, and can contain only letters, numbers, whitespace, hyphens (-), or underscores (_).

You can have up to 100 custom property names and associated values. Pre-defined property names and values do not count against the 100 custom property name and value limit.

<property_value>

The value associated with the property name. A property value must be less than 100 characters. Enclose the property value in single quotes ( ' ).

If the property already exists for the User ID, the new property value overwrites the existing property value.

Before setting a custom user property, check the following table to determine if you can use a pre-defined user property.

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 demonstrates the code to set the User ID 123456 for Pixel ID 9998887776665554 and the following pre-defined and custom user properties:

TypeUser Property NameValue

Pre-defined

$state

California

Pre-defined

$city

Menlo Park

Custom

shoeSize

11

Custom

shoeWidth

D

Custom

subscription

premium

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