Test Kitchen/Web schema

This page documents Test Kitchen's base schema for web. The schema includes three types of properties:

• core properties: fields describing the event itself
• interaction data: fields with custom values set by the instrument code to fit the needs of the experiment
• contextual attributes: fields describing the performer and environment of the event

This page helps you understand which properties of each type are available, so you can plan your instrumentation specification. For property descriptions and types, see the web base schema definition.

Core properties

These properties are added automatically to every event.

• $schema
• dt
• meta.stream
• meta.domain
• meta.id
• meta.dt
• meta.request_id

Instrument and experiment management

In addition, some core properties are added to events by the client to aid in instrument and experiment management. These properties are set automatically and cannot be customized. They include:

JavaScript:

• experiments
  • assigned
  • enrolled
• instrument_name

PHP: Unsupported

Managed data

These properties are not manually set by your instrument but are instead managed by the client libraries (as long as you use the Instrument class).

instrument_name

Reserved for the instrument ID (the one used with getInstrument()) for instruments configured in Test Kitchen UI.

funnel_event_sequence_position

0 for the first event submitted by instrument, incremented by 1 for each subsequent event

Unmanaged data

Test Kitchen supports interaction data that you can customize to fit the needs of your instrument. You can set these properties to any meaningful value to provide the data required for your event. See the SDK docs for information about how to set these properties when submitting events.

action (required)

Examples: "click", "type", "scroll"

action_subtype

Examples: "submit" or "cancel" for click actions; "up" or "down" for scroll actions

action_context

A short (maximum of 320 characters) human-readable string to provide meaningful context for the event. JSON-stringified objects preferred (as it makes querying/analysis easier), especially for multiple key-value pairs. Given the length limit, it is not recommend to stuff large blobs of data via JSON-encoded strings into this field.

action_source

A short (maximum of 64 characters) human-readable set of words to indicate the source of the event. For example: "sidebar" or "visualeditor uploadwizard modal"

element_friendly_name

Analyst-friendly name of the UI element interacted with. For example: "donate_link"

element_id

ID of the UI element interacted with

funnel_entry_token

A randomly generated identifier for linking multiple events belonging to a (work)flow. A single session (identified by performer.session_id may have multiple pageviews (identified by performer.pageview_id) which may have multiple instances of funnel_name that are separately identified by this token.

funnel_name

Analyst-friendly name such as "emergency_flow" or "add_a_link_suggestion"

Data modeling guidelines and recommendations

We recommend using snake_case for interaction data, as illustrated in the examples.

The most important property is action and it corresponds to the event name/type, for example: page_visit, click, impression, and form_submit. You are welcome to use other properties (action_subtype, action_source, action_context) as you want, but we recommend the following practices:

action_subtype

action_subtype is for differentiating between events with the same action (event type) for example:

• If action: click, then action_subtype could be cancel, submit, skip
• If action: scroll, then action_subtype could be up or down
• If action: insert (when editing with VisualEditor), then action_subtype could be table, math_formula, signature, or basic_reference.

action_source

action_source is for recording the source of the action, which is best understood through examples:

• If we had an action: page_visit event on every page visit, you would use action_source to record referrer – e.g. none, internal, external
• If we had an action: form_submit event on form submission, you might use action_source to record how the submission happened – e.g. submit_button_click vs enter_key_press
• If we had an action: impression event when a UI element is visible, you might use action_source to record if the element was visible right away (above_fold) or came into view only after user scrolled down far enough (scroll)
• If we had an action: init event when editing interface initialized, you might use action_source to record if it was initiated from page edit button or section edit button.

action_context

While the maximum number of characters allowed in action_context is 320 (per this decision), we recommend against stuffing large amounts of data. See also: Why is data stuffing bad?

action_context is for recording useful information about the context of the event, and is usually where developers collect a few pieces of structured data and JSON-stringify it (for easy querying). For example:

• For an action: search_results event, you could record total_results (int), and potentially the query (string).
• For an action: click event when user clicked one of those search results, you could record result_position (int).
• For an action: scroll event, you could record percent_scrolled (float).
• For an action: page_visit event, you could record appearance settings such as text_size (string: small, standard, or large), page_width (string: standard or wide), page_color (string: automatic (light), automatic (dark), light, or dark), and appearance_settings_location (string: side or top).

Contextual attributes

Contextual attributes provide information about the performer who triggered the event and the wiki where the event occurred. The values of contextual attributes are populated automatically by Test Kitchen when the event is generated as long as they have been added to the stream configuration.

All attributes must be enabled in the instrument's event stream configuration. For more information, see Contextual attributes.