User Properties

This document explains how to include User properties, data about the User, in a pixel.

Before You Start

Set the User ID

Call the pixel fbq('init') function with the ID of your pixel and a JSON object containing the uid parameter:

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

{pixel-id}

The ID of your pixel.

{user-id}

A unique combination of letters and numbers that identifies the User. Maximum length 99 characters. Do not use any personally identifying information, such as names or email addresses.

Set User Properties

Call the pixel fbq('setUserProperties') function with the ID of your pixel and a JSON object containing predefined or custom properties:

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

{pixel-id}

The ID of your pixel.

{user-property}

A predefined property name, one created by Facebook for common properties, or custom property name, one created by you to address a property specific to your website. Predefined property names must start with a dollar sign ($). Custom property names must be less than 40 characters and contain only letters, numbers, hyphens(-), or underscores. You can include up to 100 custom properties. Pre-defined properties do not count against this limit.

{property-value}

A string less than 100 characters. If the property already exists for the set User ID, the new property value will overwrite the existing value.

Predefined Property Reference

The pixel supports the following predefined User properties. All predefined User properties must begin with a dollar sign ($):

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.

Example

The following example shows how to set the User ID abc123 for a pixel with the ID 283859598862258 with a mix of predefined and custom User parameters:

// Set the User ID
fbq('init', '283859598862258', {uid: 'abc123'});

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

See Also