Skip to main content

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 on your native views 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.

Set Element Properties​

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 on your native views 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.

TypeExamples
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​

[FS setAttribute:(nonnull UIView *) attributeName:(nonnull NSString *) attributeValue:(nonnull NSString *)]

Example Use​

Capturing Properties and instrumenting an API Element on the Add to Cart Button​
[FS setAttribute:self.cartButton attributeName:@"id" attributeValue:@"add-to-cart"];
[FS setAttribute:self.cartButton attributeName:@"data-product-name" attributeValue:@"Baseball Cap"];
[FS setAttribute:self.cartButton attributeName:@"data-price" attributeValue:@"23.99"];
[FS setAttribute:self.cartButton attributeName:@"data-quantity" attributeValue:@"1"];
[FS setAttribute:self.cartButton attributeName:@"data-fs-properties-schema" attributeValue:@"{\"id\": \"str\", \"data-product-name\": {\"type\": \"str\", \"name\": \"productName\"}, \"data-price\": \"real\", \"data-quantity\": \"int\"}"];
[FS setAttribute:self.cartButton attributeName:@"data-fs-element" attributeValue:@"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.