User Properties

User properties are properties and values that you define for a User of your app to allow you to better understand your audience. For example, you can define a User property that tracks the frequent flyer status of a person that installs your airline mobile app. You can view this data in the Facebook Analytics dashboard under People > User Properties.

To use User Properties you need to:

  • Create a User ID for each person using your app that you use to identify that specific User. Each User IDs should be:
    • A unique combination of letters and numbers
    • No more than 100 characters long
    • Stored on the device of the User
    • Included in the app events logged from the device of the User

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

  • Create User Property Names based on what you would like to track. Facebook provides pre-defined names or you can create custom property names to fit your needs. We recommend using pre-defined names when possible but when creating Custom property names, they are a few requirements:
    • Should start with a dollar sign, for example $city
    • Should be no more than 40 characters long
    • Can contain only letters, numbers, whitespace, hyphens (-), and 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.

  • Create User Property Values associated with each User Property name. A property value must be no more than 100 characters.

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

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.

User Properties for Pixel

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

Requirements

Set the User ID

Use the following code to set the User ID:

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

Setting User Properties

Use the following code to set the User properties:

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

Sample Code

The following example demonstrates how to set the User ID 123456 for Pixel ID 9998887776665554, and pre-defined and custom User properties:

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

User Properties for Android

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

Requirements

  • A callback URL (optional).

Set the User ID

Use the following code to set the User ID:

AppEventsLogger.setUserID(String {user-id});

Clear 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.

Set User Properties

Use the following code to set the User properties:

AppEventsLogger.updateUserProperties(Bundle {parameters}, GraphRequest.Callback {callback-url});
ParameterDescription

{parameters}

A Bundle of key value pairs that define the User properties and their values.

{callback-url}

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

Sample Code

The following example demonstrates how to set the User ID 123456, and pre-defined and custom User properties:

AppEventsLogger.setUserID("123456");             // Set the User ID.
      
Bundle user_props = new Bundle();                // Set the User Properties
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) {
            }
});

User Properties for iOS

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

Requirements

  • A callback (optional).

Set the User ID

Use the following code to set the User ID:

[FBSDKAppEvents setUserID:(NSString *){user-id}]

Clear 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.

Set User Properties

Use the following code to set the User properties:

[FBSDKAppEvents updateUserProperties:(NSDictionary *){parameters} handler:(FBSDKGraphRequestHandler){handler}];
ParameterDescription

{parameters}

A pointer to an 'NSDictionary' object with key-value pairs that define the user properties and their values.

{handler}

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

Sample Code

The following example demonstrates how to set the User ID 123456, and pre-defined and custom User properties:

[FBSDKAppEvents activateApp];            // Set the User ID.
[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]);}];

User Properties for JavaScript

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

Requirements

Set 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            : '{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({user-id});   
    FB.AppEvents.logPageView();
  };
  ...
</script>
ParameterDescription

{app-id}

Your app ID.

{version}

The number of the Graph API version your app is using.

{user-id}

The User ID is a unique combination of letters and numbers that you create to identify the User of your app.

Clear 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.

Set User Properties

Use the following code to set the User properties:

FB.AppEvents.updateUserProperties({parameters}, 
     {callback}: ?(response: Object) => void,
): void
ParameterDescription

{parameters}

A comma separated list of key-value pairs that define the User properties and their values.

{callback}

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

Sample Code

The following example demonstrates how to set the User ID 123456, and pre-defined and custom User properties:

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