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:

Name Description Type Example
email The email address and unique identifier of this user. String email@example.com
name The full name of the user (automatically derived from first_name and last_name if this isn't set). String Simon Tabor
first_name First name, concatenated with last_name. String Simon
last_name Last name, concatenated with first_name. String Tabor
username The username for this person. String simontabor
description A short description for the user. Defaults to their Twitter bio if we can find it. String Simon is a developer at GoSquared
avatar The absolute URL of the avatar for this person. Defaults to the gravatar for email. String https://profile-img.com/simon.png
phone The phone number for this person. String +447901229693
created_at Set the date that the user first signed up for your service – ISO 8601 timestamp. String 2016-06-07T15:44:20Z
id An alternate option for the unique identifier of this user. String 253552
company An object containing company details (name, size etc). Object { "name": "GoSquared" }
company_name The name of the company the user works at. String GoSquared
company_size The size of the company. Number 12
company_industry The industry of the company. String Analytics
company_position The position of this user within the company. String Developer
custom An 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.

Usage

_gs('properties', {
  name: 'Example User',
  email: 'email@example.com',
  // 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
  }
});