Test Kitchen/Interaction data

This page documents the interaction data supported by the Test Kitchen base schemas. For property descriptions, types and other constraints (like their maximum length), see the base schema definitions.

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 and present tense (e.g. click instead of clicked) for interaction data, as illustrated in the examples. However, past tense can be okay too (depending on context), for example edit_saved when user lands on page after saving an edit.

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).