Track Properties

Properties (attributes) are an excellent way of getting to know your users. They can contain user information and state.

All properties can be used to search, filter and sort your users in Contacts. The more you track, the better you can understand your users.

How many different custom properties can I track?

Take some time to think about the name you give to your properties. You can name them anything you like, but it's best to use a clear, concise name.

Each GoSquared project can track up to 1000 custom properties. Above this limit, properties with new names will be ignored.

Reserved property names

GoSquared defines a list of common properties that are useful to track:

emailThe email address and unique identifier of this
nameThe full name of the user (automatically derived from first_name and last_name if this isn't set).StringSimon Tabor
first_nameFirst name, concatenated with last_name.StringSimon
last_nameLast name, concatenated with first_name.StringTabor
usernameThe username for this person.Stringsimontabor
descriptionA short description for the user. Defaults to their Twitter bio if we can find it.StringSimon is a developer at GoSquared
avatarThe absolute URL of the avatar for this person. Defaults to the gravatar for email.String
phoneThe phone number for this person.String+447901229693
created_atSet the date that the user first signed up for your service – ISO 8601 timestamp.String2016-06-07T15:44:20Z
idAn alternate option for the unique identifier of this user.String253552
companyAn object containing company details (name, size etc).Object{ "name": "GoSquared" }
company_nameThe name of the company the user works at.StringGoSquared
company_sizeThe size of the company.Number12
company_industryThe industry of the company.StringAnalytics
company_positionThe position of this user within the company.StringDeveloper
customAn object of any other properties (custom properties)Object{ "plan": "pro" }

Some of these special properties are used by GoSquared to provide powerful functionality. For example, email is used to look up additional information about an individual from publicly available sources.

Custom properties

Besides special properties, you can track any property of any data type and GoSquared will make that data searchable, sortable and filterable. Place your custom properties under the custom property.

Contacts needs to know about what kind of data each custom property contains – whether the property is text, a number, or a date etc. Therefore, when you track a custom property, it is automatically assigned a “type” based on the value you send. Contacts can then make sure the data is searched, sorted and filtered in the correct way for that data. Possible types are Text, Number, Date, Boolean and Null.

For example, if you send a subscription_created property with a value like 2015-03-03T15:00:00+00:00, it will be assigned the date type. Alternatively, if you send a subscription_value property with a value like 49.99, it will be assigned the number type. Date detection is fairly lenient, so long as it resembles at least a portion of an ISO 8601 string.

Contacts will always try its best to figure out the most appropriate type for your custom properties. Sometimes it’s not always possible to get it exactly right, such as if you send a numeric Unix timestamp and want it treated as a date. In those cases, you can manually correct the property type by heading to Settings > Current Project > Contacts.

If you know the ID of the visitor, it is safer to use the Identify function as it will ensure that the ID is properly set.

You can set properties on unidentified visitors and they'll be merged into the identified profile as soon as they become identified.


_gs('properties', {
  name: 'Example User',
  email: '',
  // all custom props go in the "custom" object
  custom: {
    stringy_thing: 'thingy', // string type
    floaty_thing: 5.0,       // numeric type
    integery_thing: 23       // numeric type