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.

For more information on creating user properties, choose your product or Facebook SDK:

Facebook Pixel

This section shows you how to set the User ID and user properties in Facebook Pixels.

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.

<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 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'
        }
      )
    

Facebook SDK for Android

This section shows you how to set the User ID and user properties using the Facebook SDK for Android.

Setting the User ID

Use the following code to set the User ID:

AppEventsLogger.setUserID(String userID);
Parameter Description

userID

The user ID is a string composed of 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.

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

Clearing the User ID

Use the following code to clear the User ID from the device:

AppEventsLogger.clearUserID();

After you clear the User ID from the device, app events from the device are sent without a User ID.

Setting User Properties

Use the following code to set the user properties:

AppEventsLogger.updateUserProperties(Bundle parameters, GraphRequest.Callback callback);
Parameter Description

parameters

A Bundle of key value pairs that define the user properties and their values. 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 (_).

Each value must be less than 100 characters.

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.

callback

An optional callback that determines if the updateUserProperties function was successful.

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

Property 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 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.
AppEventsLogger.setUserID("123456");
      
// Set the User Properties
Bundle user_props = new Bundle();
user_props.putString("$state", "California");
user_props.putString("$city", "Menlo Park");
user_props.putInt("shoeSize", "11");
user_props.putString("shoeWidth", "D");
user_props.putString("subscription", "Premium");

AppEventsLogger.updateUserProperties(user_props, new GraphRequest.Callback() {
            @Override
            public void onCompleted(GraphResponse response) {

   }
});

Facebook SDK for iOS

This section shows you how to set the User ID and user properties using the Facebook SDK for iOS.

Setting the User ID

Use the following code to set the User ID:

[FBSDKAppEvents setUserID:(NSString *)userID]
Parameter Description

userID

The user ID is an NSString composed of 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.

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

Clearing the User ID

Use the following code to clear the User ID from the device:

[FBSDKAppEvents setUserID:nil];

After you clear the User ID from the device, app events from the device are sent without a User ID.

Setting User Properties

Use the following code to set the user properties:

[FBSDKAppEvents updateUserProperties:(NSDictionary *)parameters handler:(FBSDKGraphRequestHandler)handler];
Parameter Description

parameters

A pointer to an 'NSDictionary' object with key-value pairs that define the user properties and their values. 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 (_).

Each value must be less than 100 characters.

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.

handler

An optional callback that determines if the updateUserProperties function was successful.

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

Property 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 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.
[FBSDKAppEvents activateApp];
[FBSDKAppEvents setUserID:@"123456"];

      
// Set the User Properties
NSDictionary *user_props = [[NSDictionary alloc] initWithObjectsAndKeys:
        @"California", @"$state", 
      	@"Menlo Park", @"$city", 
      	@"11", @"shoeWidth", @"D", 
      	@"premium", @"subscription"];
      
[FBSDKAppEvents updateUserProperties:user_props
         handler:^void(FBSDKGraphRequestConnection *connection,
         id result,
         NSError *error) {NSLog(@"%@",[error localizedDescription]);}];

Facebook SDK for JavaScript

This section shows you how to set the User ID and user properties using the Facebook SDK for JavaScript.

Setting the User ID

Use the following code to set the User ID:

/* This example demonstrates setting the user ID for a user with 
   user properties in the initialization event. Set the 
   autoLogAppEvents property to false in the initialization function.     
*/
     
<script>
  window.fbAsyncInit = function() {
    FB.init({
      appId            : '<your_app_id>',
      autoLogAppEvents : false,
      xfbml            : true,
      version          : '<version>'
    });
    
    /* Call the setUserID function before calling the logPageView 
       function to ensure the page view is associated with the
       specified user.
    */
    FB.AppEvents.setUserID(userID);   
    FB.AppEvents.logPageView();
  };

  ...
     </script>
    
Parameter Description

<your_app_id>

Your App ID enclosed in single quotes ( ' ).

<version>

Ther version number of your app in single quotes ( ' ).

userID

The User ID 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.

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

Clearing the User ID

Use the following code to clear the User ID from the device:

FB.AppEvents.clearUserID(): void

After you clear the User ID from the device, app events from the device are sent without a User ID.

Setting User Properties

Use the following code to set the user properties:

FB.AppEvents.updateUserProperties(
     params: {[key: string]: string | number}, 
     cb: ?(response: Object) => void,
): void
    
Parameter Description

param

Key-value pairs that define the user properties and their values. 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 (_).

Each value must be less than 100 characters.

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.

cb

An optional callback that determines if the updateUserProperties function was successful.

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

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

FB.init({appId: '...', version: 'v2.8'});
FB.AppEvents.setUserID('123456');
FB.AppEvents.updateUserProperties({$state: 'California', 
                                   $city: 'Menlo Park', 
                                   shoeSize: '11', 
                                   shoeWidth: 'D', 
                                   subscription: 'premium}, (res) => {
    console.log(res);
    }
);