User Properties

App events allow you to measure user activity which, combined with Facebook Analytics, allows you to understand user behavior. One of the key features of Facebook Analytics is segments. Segments allow you to better understand your audience by analyzing the behavior and demographics of a group of people that you define.

Many businesses also want to create segments based on other things they know about their customers. For example, an airline might want to create a segment based on values from their customer relationship management (CRM) system, such as frequent flyer status or the year that a customer became a member of their frequent flyer program.

With user properties, businesses can use their own CRM data to understand and analyze behavior. You can create user properties directly in your app or by using our API.

User IDs and user properties can't include any personally identifying information, such as people's names or email addresses.

These properties correspond to the

Application User Properties in the Graph API

.

User ID

By calling the setUserID function, you can assign an ID to a user of your app. For example, you could create a number that associates the user with information you collected when they installed your app. Typically, this is your identifier for the user in your own CRM or other back-end systems. The setUserID function is helpful if you expect to upload data from your app and use the API because it ensures that properties are attributed to the same user.

To associate the properties with a user with the JavaScript SDK, set the autoLogAppEvents property to false during initialization and call the setUserID function before the page view event.

AppEventsLogger.setUserID(String userID);
[FBSDKAppEvents setUserID:(NSString *)userID];
/* 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          : 'v2.10'
    });
    
    /* 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

userID

The user ID. The length of the user ID must be less than 100 characters.

When you set a user ID, this ID is stored on the user's device, and is included in app events logged from that device.

You can delete the ID stored on the device by calling the clearUserID() function in Android or passing nil for iOS. After you delete the ID, app events from the device are sent without a user ID.

AppEventsLogger.clearUserID();
[FBSDKAppEvents setUserID:nil];
FB.AppEvents.clearUserID(): void

The User Properties Table

Once you have called setUserID, then you can also create a table with custom fields for user properties, that you can update with custom values. For example, you could have a user property like "Customer Loyalty Status" with values like "Gold," "Silver," or "Bronze." This would allow you to see and segment analytics based on these values in Analytics.

AppEventsLogger.updateUserProperties(Bundle parameters, GraphRequest.Callback callback);
[FBSDKAppEvents updateUserProperties:(NSDictionary *)parameters handler:(FBSDKGraphRequestHandler)handler];
FB.AppEvents.updateUserProperties(
     params: {[key: string]: string | number}, 
     cb: ?(response: Object) => void,
): void
Parameter Description

Android SDK: parameters

iOS SDK: parameters

Javascript SDK: params

Data Type

Android SDK: Bundle

iOS: NSDictionary

JavaScript SDK: Object

Key-value pairs representing user properties and their values.

Values should be strings or numbers only.

Each key must be less than 40 characters in length, and the key can contain only letters, numbers, whitespace, hyphens (-), or underscores (_).

Each value must be less than 100 characters.

The total number of properties associated with your users cannot exceed 100.

Android SDK: callback

iOS SDK: handler

Javascript SDK: cb

A callback for the success or failure of updating the user properties. This is optional.

The following example represents a Bundle of user properties for a customer's shoe size, shoe width and subscription level. Adding these user properties allows you to view analytics about your customers based on these values. For example, you can create a segment of people who purchase wider shoes or measure cohorts of people in the 'premium' status level.

When you call updateUserProperties with this Bundle, the function performs the following actions, depending on what information has changed:

  • If no user property table exists, then the function creates a new table with the values in the bundle
  • If a user property table exists but some of the user properties are new, then the function adds these properties and their values to the table
  • If the user property table and properties already exist, but the values are different, then the values in the bundle overwrite the old values
{
  ‘shoeSize’: ‘11’,
  ‘shoeWidth’: ‘D’,
  ‘subscription’: ‘premium’,
}

In addition to the custom user properties that you define, there are the following pre-defined user properties. Note that pre-defined properties start with a dollar sign ($) to distinguish them from the properties that you define. These predefined properties do not count towards the limit of 100 user properties in total.

Property Description

$account_created_time

The time when the user's account was created, as a unix timestamp.

$city

The city in which the user lives.

$country

The country in which the user lives.

$currency

The user's preferred currency.

$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 user's preferred language.

$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 user's zip code.

Example

The following code example demonstrates how user properties might be used in a typical scenario.

AppEventsLogger.setUserID("123456");

Bundle user_props = new Bundle();
user_props.putString("CustomerStatus", "Gold");
user_props.putInt("Age", 25);

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

            }
        });
[FBSDKAppEvents activateApp];
[FBSDKAppEvents setUserID:@"123456"];
    
NSDictionary *user_props = [[NSDictionary alloc] initWithObjectsAndKeys:@"Gold", @"CustomerStatus", @"25", @"Age", nil];

[FBSDKAppEvents updateUserProperties:user_props
                             handler:^void(FBSDKGraphRequestConnection *connection,
                                           id result,
                                           NSError *error) {NSLog(@"%@",[error localizedDescription]);}];
FB.init({appId: '...', version: 'v2.8'});
FB.AppEvents.setUserID('123456');
FB.AppEvents.updateUserProperties({CustomerStatus: 'Gold', Age: 25}, (res) => {
    console.log(res);
    }
);
https://graph.facebook.com/v2.10/<appid>/user_properties?data=[{user_unique_id: '123456', custom_data: {CustomerStatus: 'Gold', Age: '25'}}]

For more information about using the Graph API to send user properties, see Using the Graph API.

Customer Data in Analytics

You can view analytics for your user properties in Facebook Analytics.

To view analytics for user properties:

  1. Go to Facebook Analytics and select your app. Facebook Analytics opens displaying the Overview page.
  2. In the left-hand menu, choose the section below Overview that you want to view analytics for. Then choose the subsection.
  3. Click the Edit button next the Segment drop-down menu just below the page title.
  4. In the Select Condition drop-down menu, select User Properties.

  5. in the Select Parameter drop-down menu, select the user property for which you want to see analytics, then select the relationship, and then enter a value.

  6. Click Apply.

Facebook Analytics creates and displays the charts for the user property and value you entered.