User properties

Here you will find various information about the properties of users.

Do not confuse user properties and event properties. The event properties reflect additional information about the event (for example, the "Made an order" event may have the "Sum", "Products" properties, etc.). User properties reflect user information. For example: name, email, number of orders, the sum of all orders, etc.

Data types

5 types are available:

number
string
date/time
boolean
list

Numbers can only be integers in range from -2^53 to +2^53, or from -9007199254740992 to +9007199254740992.

Maximal string length is 255 characters.

Strings of up to 255 characters can be items of the list (up to 30 items in one list).

Date/time format: ISO 8601: YYYY-MM-DDTHH:MM:SS. Simplified format is acceptable: YYYY-MM-DD, in which case time is set as: 00:00:00.

Example:

{
    value1: 145,
    value2: "Hello, world!",
    value3: true,
    value4: "2015-09-13T13:25:05",
    value5: ["element1", "element2", "element3"]
}

Property identification formats

Sometimes a simply creating a property is not enough. For example, if you track the number of times a button is clicked, it would be convenient to increment the property value by one each time (add operation).

Another example - you want to know which section the user visited first. Here, the property should be written only if it is not already created (set_once operation).

A complex format for setting properties is an array of objects. Each object is an atomic operation on a property. There are three fields in the object: op - operation, key - property name, value - value. The following operations are supported:

update_or_create - most commonly used operation. Creates property (or updates if it already exists)
set_once - create only if property does not exist yet
add - add a set amount to the property value (if the property does not exist, it will be created with 0 value, and then increased by a set amount)
delete - delete property
append - add into a list
union - add into a list if such item is not already present in the list
exclude - delete from the list

Examples:

[
    // Set value (update, if value is already defined)
    {"op": "update_or_create", "key": "my_property", "value": "Hello"},

    // Set if property is undefined
    {"op": "set_once", "key": "my_property", "value": "Hello"},

    // Increment/decrement
    {"op": "add", "key": "my_property", "value": "1"},
    {"op": "add", "key": "my_property", "value": "-1"},
    {"op": "add", "key": "my_property", "value": "15"},
    {"op": "add", "key": "my_property", "value": "-53"},

    // Delete property
    {"op": "delete", "key": "my_property", "value": "0"},

    // Add an item into the list
    {"op": "append", "key": "my_list_property", "value": "super-element"},

    // add into a list if such item is not already present in the list ("add to set")
    {"op": "union", "key": "my_list_property", "value": "super-element"},

    // Delete element from the list
    {"op": "exclude", "key": "my_list_property", "value": "super-element"},
]

At the moment lists can contain up to 30 items. Only strings can be items of a list.

In case append is used, items are added sequentially. The order will be preserved. When 31st item is added, defining would a new item be added is impossible(and which item would be removed before adding).

In case union is used order is not preserved. New item insertion is not guaranteed if list already contains 30 items. But not having identical items is guaranteed.

System (standard) user properties

All property names beginning with $ are system. Thus custom properties (those you create) should not begin with $.

Only 3 system properties values can be written. These properties are: $name, $phone, $email. All the rest can only be read.

Name	Description
`$name`	Name
`$email`	Email
`$phone`	Phone
`$last_seen`	Last activity. Date of last event
`$last_contacted`	Date of last user’s reply or date when a message to user was last sent (including auto-messages)
`$last_reply`	Date of last user’s reply
`$conversations_emails`	Amount of email conversations
`$conversations_chats`	Amount of chat conversations
`$conversations_popups`	Amount of pop-up conversations
`$sessions`	Sessions count
`$user_id`	User ID
`$score`	Score (user rating)
`$initial_referrer`	Initial referrer
`$initial_referrer_domain`	Initial referrer. Only domain
`$initial_utm_campaign`	First UTM Campaign tag
`$initial_utm_source`	First UTM Source tag
`$initial_utm_medium`	First UTM Medium tag
`$initial_utm_content`	First UTM Content tag
`$initial_utm_term`	First UTM Term tag
`$last_utm_campaign`	Last UTM Campaign tag
`$last_utm_source`	Last UTM Source tag
`$last_utm_medium`	Last UTM Medium tag
`$last_utm_content`	Last UTM Content tag
`$last_utm_term`	Last UTM Term tag
`$country`	Country
`$region`	Region
`$city`	City
`$latitude`	Latitude
`$longitude`	Longitude
`$email_unsubscribed`	Unsubscribed from emails
`$avatar`	Name of avatar file. Users avatars are stored here: `https://files.dashly.app/avatars-users/{{ $avatar }}`
`$social_vk`	VK page URL
`$social_facebook`	Facebook page URL
`$social_fourqsuare`	Foursquare page URL
`$social_googleplus`	Google+ page URL
`$social_pinterest`	Pinterest page URL
`$social_twitter`	Twitter page URL
`$social_skype`	Skype

Deprecated properties: $comment, $last_active_user, $online, $idle, $cluster_id, $app_uid, $uid, $identity.

After user performs an event(for example, event with ID=123), he will obtain 3 properties for this event:

Name	Description
`$event_123_count`	Number of performances
`$event_123_first`	Date, when event was first performed by the user
`$event_123_last`	Date, when event was last performed by the user

E-commerce properties

E-commerce specific properties. These properties can be identified via API.

Name	Description
`$cart_amount`	Cart amount (integer)
`$viewed_products`	Viewed products (list of product names)
`$cart_items`	Cart (list of product names)
`$last_order_status`	Last order status
`$last_payment`	Last payment amount (integer)
`$revenue`	Total revenue from user (integer)
`$profit`	Total profit from user (integer)
`$group`	Group
`$discount`	Discount (integer)
`$orders_count`	Orders count (integer)
`$ordered_items`	Ordered items (list of product names)
`$ordered_categories`	Ordered items’ categories (list of product categories’ names)
`$viewed_categories`	Viewed products’ categories (list of product categories’ names)