User properties (Beta)

App Events allow you to measure user activity which, combined with Anaytics for Apps, allows you to understand user behavior. One of the key features of Analytics for Apps 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.

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.

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

The user properties table

Once you have called setUserID, then you can also create a table with custom fields for user properties, which 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 for Apps.

AppEventsLogger.updateUserProperties(Bundle parameters, GraphRequest.Callback callback)
[FBSDKAppEvents updateUserProperties:(NSDictionary *)parameters handler:(FBSDKGraphRequestHandler)handler];
Parameter Description

parameters

A Bundle (Android) or NSDictionary (iOS) of key-value pairs representing user properties and their values.

Values should be strings or numbers only.

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

Each value must be less than 100 characters.

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

callback / handler

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 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 pr-edefined 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.

Customer data in Analytics for Apps

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

To view analytics for user properties:

  1. Go to Analytics for Apps 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, select the relationship, and enter a value.
  6. Click the Apply button.

Analytics for Apps will create and display the charts for the user property and value you entered.