Setting User Properties

IMPORTANT NOTE: Please be sure to not track any user data that may be against your privacy terms. If you need any assistance with privacy concerns, then please reach out to our Platform team here.

The JavaScript SDK automatically pulls useful data about the browser, including browser type and operating system version. They are displayed as user properties in Amplitude. You can read more about them here.

The SDK supports the operations set, setOnce, unset, and add on individual user properties. The operations are declared via a provided Identify interface. Multiple operations can be chained together in a single Identify object. The Identify object is then passed to the Amplitude client to send to the server. The results of the operations will be visible immediately in the dashboard and will take effect for events logged after.

To use the Identify interface in Android or Unity, you will first need to import the class.
To use the AMPIdentify interface in iOS, you will first need to include the header.

#import "AMPIdentify.h"
import com.amplitude.api.Identify;
import com.amplitude.api.Identify;

set

This sets the value of a user property.

var identify = new amplitude.Identify().set('gender', 'female').set('age', 20);
amplitude.getInstance().identify(identify);
AMPIdentify *identify = [[[AMPIdentify identify] set:@"gender" value:@"female"] set:@"age"
    value:[NSNumber numberWithInt:20]];
[[Amplitude instance] identify:identify];
Identify identify = new Identify().set("gender", "female").set("age", 20);
Amplitude.getInstance().identify(identify);
Amplitude.Instance.setUserProperty("gender", "female"); // string value
Amplitude.Instance.setUserProperty("age", 20); // int value
Amplitude.Instance.setUserProperty("some float values", new float[]{20f, 15.3f, 4.8f}); // float array

setOnce

This sets the value of a user property only once. Subsequent setOnce operations on that user property will be ignored. In the following example, 'sign_up_date' will be set once to '2015-08-24', and the following setOnce to '2015-09-14' will be ignored.

var identify = new amplitude.Identify().setOnce('sign_up_date', '2015-08-24');
amplitude.getInstance().identify(identify);

var identify = new amplitude.Identify().setOnce('sign_up_date', '2015-09-14');
amplitude.getInstance().identify(identify);
AMPIdentify *identify1 = [[AMPIdentify identify] setOnce:@"sign_up_date" value:@"2015-08-24"];
[[Amplitude instance] identify:identify1];

AMPIdentify *identify2 = [[AMPIdentify identify] setOnce:@"sign_up_date" value:@"2015-09-14"];
[[Amplitude instance] identify:identify2];
Identify identify1 = new Identify().setOnce("sign_up_date", "2015-08-24");
Amplitude.getInstance().identify(identify1);

Identify identify2 = new Identify().setOnce("sign_up_date", "2015-09-14");
amplitude.identify(identify2);
Amplitude.Instance.setOnceUserProperty("sign_up_date", "08/24/2015");
Amplitude.Instance.setOnceUserProperty("sign_up_date", "09/14/2015");

unset

This will unset and remove a user property.

var identify = new amplitude.Identify().unset('gender').unset('age');
amplitude.getInstance().identify(identify);
AMPIdentify *identify = [[[AMPIdentify identify] unset:@"gender"] unset:@"age"];
[[Amplitude instance] identify:identify];
Identify identify = new Identify().unset("gender").unset("age");
Amplitude.getInstance().identify(identify);
Amplitude.Instance.unsetUserProperty("sign_up_date");
Amplitude.Instance.unsetUserProperty("age");

add

This will increment a user property by some numerical value. If the user property does not have a value set yet, it will be initialized to 0 before being incremented.

var identify = new amplitude.Identify().add('karma', 1).add('friends', 1);
amplitude.getInstance().identify(identify);
AMPIdentify *identify = [[[AMPIdentify identify] add:@"karma" value:[NSNumber numberWithFloat:0.123]]
    add:@"friends" value:[NSNumber numberWithInt:1]];
[[Amplitude instance] identify:identify];
Identify identify = new Identify().add("karma", 1).add("friends", 1);
Amplitude.getInstance().identify(identify);
Amplitude.Instance.addUserProperty("karma", 1.5);
Amplitude.Instance.addUserProperty("friends", 1);

append

This will append a value or values to a user property array. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are appended. If the user property has an existing value and it is not a list, it will be converted into a list with the new value appended.

var identify = new amplitude.Identify().append('ab-tests', 'new-user-test').append('some_list', [1, 2, 3, 4, 'values']);
amplitude.getInstance().identify(identify);
NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] append:@"ab-tests" value:@"new-user-test"]
    append:@"some_list" value:array];
[[Amplitude instance] identify:identify];
Identify identify = new Identify().append("ab-tests", "new-user-test")
  .append("some_list", new JSONArray().put(1).put("some_string"));
Amplitude.getInstance().identify(identify);
Amplitude.Instance.appendUserProperty("ab-tests", "new_user_tests");
Amplitude.Instance.appendUserProperty("some_list", new int[]{1, 2, 3, 4});

prepend

This will prepend a value or values to a user property. Prepend means inserting the value(s) at the front of a given list. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are prepended. If the user property has an existing value and it is not a list, it will be converted into a list with the new value prepended.

var identify = new amplitude.Identify().prepend('ab-tests', 'new-user-test').prepend('some_list', [1, 2, 3, 4, 'values']);
amplitude.getInstance().identify(identify);
NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] prepend:@"ab-tests" value:@"new-user-test"]
    prepend:@"some_list" value:array];
[[Amplitude instance] identify:identify];
Identify identify = new Identify().prepend("ab-tests", "new-user-test")
  .prepend("some_list", new JSONArray().put(1).put("some_string"));
Amplitude.getInstance().identify(identify);
Identify identify = new Identify().prepend("ab-tests", "new-user-test")
  .prepend("some_list", new JSONArray().put(1).put("some_string"));
Amplitude.getInstance().identify(identify);

preInsert

This will pre insert a value or values to a user property, if it does not exist in the user property yet.
Pre insert means inserting the value(s) at the beginning of a given list. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are pre inserted. If the user property has an existing value, it will be no operation.

var identify = new amplitude.Identify().preInsert('ab-tests', 'new-user-test').preInsert('some_list', [1, 2, 3, 4, 'values']);
amplitude.getInstance().identify(identify);
NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] preInsert:@"ab-tests" value:@"new-user-test"]
    preInsert:@"some_list" value:array];
[[Amplitude instance] identify:identify];

postInsert

This will post insert a value or values to a user property, if it does not exist in the user property yet. Post insert means inserting the value(s) at the end of a given list. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are post inserted. If the user property has an existing value, it will be no operation.

var identify = new amplitude.Identify().postInsert('ab-tests', 'new-user-test').postInsert('some_list', [1, 2, 3, 4, 'values']);
amplitude.getInstance().identify(identify);
NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] postInsert:@"ab-tests" value:@"new-user-test"]
    postInsert:@"some_list" value:array];
[[Amplitude instance] identify:identify];

remove

Remove a value or values to a user property, if it does exist in the user property. Remove means remove the existing value(s) from the given list. If the item does not exist in the user property, it will be no operation.

var identify = new amplitude.Identify().remove('ab-tests', 'new-user-test').remove('some_list', [1, 2, 3, 4, 'values']);
amplitude.getInstance().identify(identify);
NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] remove:@"ab-tests" value:@"new-user-test"]
    remove:@"some_list" value:array];
[[Amplitude instance] identify:identify];

Note: If a user property is used in multiple operations on the same Identify object, then only the first operation will be saved and the rest will be ignored. In this example, only the set operation will be saved and the add and the unset will be ignored:

var identify = new amplitude.Identify()
 .set('karma', 10)
 .add('karma', 1)
 .unset('karma');
amplitude.getInstance().identify(identify);
AMPIdentify *identify = [[[[AMPIdentify identify] set:@"karma" value:[NSNumber numberWithInt:10]]
    add:@"friends" value:[NSNumber numberWithInt:1]] unset:@"karma"];
    [[Amplitude instance] identify:identify];
Identify identify = new Identify().set("karma", 10).add("karma", 1).unset("karma");
Amplitude.getInstance().identify(identify);
Identify identify = new Identify().set("karma", 10).add("karma", 1).unset("karma");
Amplitude.getInstance().identify(identify);

Arrays in User Properties

The SDK supports arrays in user properties. Any of the user property operations above (with the exception of add) can accept a JSONArray. You can directly set arrays or use append to generate an array.

var identify = new amplitude.Identify()
    .set('colors', ['rose', 'gold'])
    .append('ab-tests', 'campaign_a')
    .append('existing_list', [4, 5]);
amplitude.getInstance().identify(identify);
NSMutableArray *colors = [NSMutableArray array];
[colors addObject:@"rose"];
[colors addObject:@"gold"];
NSMutableArray *numbers = [NSMutableArray array];
[numbers addObject:[NSNumber numberWithInt:4]];
[numbers addObject:[NSNumber numberWithInt:5]];
AMPIdentify *identify = [[[[AMPIdentify identify] set:@"colors" value:colors] append:@"ab-tests"
    value:@"campaign_a"] append:@"existing_list" value:numbers];
[[Amplitude instance] identify:identify];
JSONArray colors = new JSONArray();
colors.put("rose").put("gold");
Identify identify = new Identify().set("colors", colors)
  .append("ab-tests", "campaign_a").append("existing_list", new int[]{4,5});
Amplitude.getInstance().identify(identify);
List<double> list = new List<double>();
list.add(2.5);
list.add(6.8);
Amplitude.Instance.appendUserProperty("my_list", list);

Setting Multiple User Properties

You may use setUserProperties shorthand to set multiple user properties at once. This method is simply a wrapper around Identify.set and identify. Here is an example:

var userProperties = {
 gender: 'female',
 age: 20
};
amplitude.getInstance().setUserProperties(userProperties);
NSMutableDictionary *userProperties = [NSMutableDictionary dictionary];
[userProperties setValue:@"VALUE" forKey:@"KEY"];
[userProperties setValue:@"OTHER_VALUE" forKey:@"OTHER_KEY"];
[[Amplitude instance] setUserProperties:userProperties];
JSONObject userProperties = new JSONObject();
try {
    userProperties.put("KEY", "VALUE");
    userProperties.put("OTHER_KEY", "OTHER_VALUE");
} catch (JSONException exception) {
}
Amplitude.getInstance().setUserProperties(userProperties);
Dictionary<string, object> userProperties = new Dictionary<string, object>() {
  {"float_gprop", 1.0}
};
Amplitude.Instance.setUserProperties(userProperties);

Clearing User Properties

You may use clearUserProperties to clear all user properties at once. This will wipe all of the current user's user properties. Note: The result is irreversible! Amplitude will not be able to sync the user's user property values before the wipe to any future events that the user triggers as they will have been reset.

amplitude.getInstance().clearUserProperties();
[[Amplitude instance] clearUserProperties];
Amplitude.getInstance().clearUserProperties();
Amplitude.Instance.clearUserProperties();

Updating User Properties in the Background

When you are updating user properties in the background and do not wish to trigger a session while updating them, make sure to set outOfSession to true:

AMPIdentify *identify = [[[AMPIdentify identify] set:@"gender" value:@"female"] set:@"age"
    value:[NSNumber numberForInt:20]];
[[Amplitude instance] identify:identify outOfSession:YES];
Identify identify = new Identify().set("color", "blue");
Amplitude.getInstance().identify(identify, true);

Setting Group Properties

Just like setting user properties, you can also use AMPIdentify interface to set and update group properties.

var groupIdentify = new amplitude.Identify().set('members', 80);
amplitude.getInstance().groupIdentify('company', 'Amplitude', groupIdentify);
Identify groupIdentify = new Identify().set("members", 80);
Amplitude.getInstance().groupIdentify("company", "Amplitude", groupIdentify);
AMPIdentify *groupIdentify = [[AMPIdentify identify] set:@"members" value:[NSNumber numberForInt:80]];
[[Amplitude instance] groupIdentifyWithGroupType:@"company" groupName:@"Amplitude" groupIdentify:groupIdentify];

What’s Next
Did this page help you?