Set Element Properties

Version: v2

API Defined Elements

API Defined Elements provides an instrumented approach to defining Elements in Fullstory. Once created, API Elements can be used across the same Fullstory features as Elements created from CSS Selectors for search and analysis.

Use the data-fs-element="Element Name" data attribute in your HTML markup to create an API Element with an assigned name

Existing configured Elements can be given an API Element name through Fullstory Element settings to preserve continuity. Note: The API Element name must be assigned to the existing Element before the name is instrumented in code.

API Element names are permanently attached to their associated Element, though the display name may be changed at any time.

Limits

Up to 1,000 active Elements, instrumented via API or in-app, may be defined. Any new API Elements created after the limit is reached will be ignored. This limit does not include archived Elements.

Element properties represent a set of properties on a given element that can be made available for search and analytics. Unlike attributes which can only be utilized for matching elements via CSS selectors, element properties can be used for filtering, grouping, and other analyses similar to user, page, and event properties.

Use the data-fs-properties-schema data attribute in your HTML markup to capture attributes as element properties.

Element properties are available to search and analyze for all captured interactions that target elements with this attribute. Any Named Elements defined will be connected automatically to the properties captured at or above the depth of the corresponding element selector. Interactions on an element inherit all properties configured on the element and its ancestors, whether configured through this API or through the Fullstory UI.

You can set the data-fs-properties-schema data attribute on multiple elements in the same hierarchy. When conflicting properties are captured (i.e. the same name and type are captured for the same element interaction), the deepest property value captured is taken.

The data-fs-properties-schema data attribute should be a valid JSON object with key-value pairs. Each JSON key indicates an attribute from which the value should be captured. The corresponding JSON value indicates the value type or an optional advanced object indicating override name and value type.

Key-Value Pairs

key string required

Name of attribute on element from which the value should be captured.

value string/object required

If string, indicates the value type of the attribute to be captured.
If object, requires type field (string) indicating value type of the attribute to be captured and allows name field (string) to override captured element property name if the default attribute name is not desired.

Value Types

The allowed value types align with the types available for properties. Some single value types have special handling for better attribute type specific capture. All repeated value types are handled as JSON arrays with corresponding JSON type requirements.

Type	Examples
bool	`1`, `t`, `true`, `0`, `f`, `false` When the attribute value is not a valid bool value or does not exist, the resulting element property value falls back to attribute existence (i.e. value exists = true, value not exists = false)
bools	`[true, false]`, `[false]`
date	`2006-01-02T15:04:05Z`, `2006-01-02` Values should be a valid ISO8601 datetime or date
dates	`["2006-01-02T15:04:05Z", "2006-01-02"]` Values should be valid ISO8601 datetime or date strings
int	`0`, `-123`, `45`
ints	`[0, 1, 2]`, `[6, -6]`
real	`12.345`, `1`, `-0.5`
reals	`[12.345, 1]`, `[5]`
str	`foo`, `bar`, `foo@bar`
strs	`["foo", "bar"]`, `["foo", "bar", "foo@bar"]`

Limits

Capture up to 50 unique properties on a single element interaction.
Capture up to 500 unique properties across all element interactions.

Additional Information

Property Name Requirements
- Note: No type suffix should be used when specifying element properties. Type is implied by the value type specification.
Property Value Requirements
Property Cardinality Limiting

Example Use

Capturing Properties and instrumenting an API Element on the Add to Cart Button

<button
  id='add-to-cart'
  data-product-name='Baseball Cap'
  data-price='23.99'
  data-quantity='1'
  data-fs-properties-schema='{
    "id": "str",
    "data-product-name": {
      "type": "str",
      "name": "productName"
    },
    "data-price": "real",
    "data-quantity": "int"
  }'
  data-fs-element="Add to Cart Button"
/>

Results in the following element properties captured for any interaction on the button:

id (str): "add-to-cart"
productName (str): "Baseball Cap"
data-price (real): 23.99
data-quantity (int): 1

Additionally, an Element named Add to Cart Button will be automatically created and available for use in the Fullstory app.

API Defined Elements​

Limits​