├── contexts ├── app.json ├── localisation.json ├── business_objects.json ├── identity.json └── entities.json ├── components ├── rating │ ├── rating_select.json │ └── rating.md ├── screen │ ├── screen_view.json │ └── screen.md ├── hyperlink │ ├── hyperlink.md │ └── hyperlink_select.json ├── media │ ├── media.md │ └── media_interaction.json ├── search │ ├── search_result_select.json │ ├── search_filter.json │ ├── search_initiate.json │ └── search.md ├── navigation │ ├── navigation_select.json │ ├── navigation_state.json │ └── navigation.md ├── modal │ ├── modal_dismiss.json │ ├── modal_display.json │ ├── modal_select.json │ └── modal.md ├── selection_control │ ├── slider_adjust.json │ ├── switch_select.json │ ├── checkbox_select.json │ ├── radio_select.json │ └── selection_control.md ├── list │ ├── list_view.json │ ├── list_select.json │ ├── list.md │ └── list_state.json ├── notification │ ├── notification_dismiss.json │ ├── notification_display.json │ ├── notification_select.json │ └── notification.md ├── input │ ├── input_exit.json │ └── input.md ├── button │ ├── button_select.json │ └── button.md └── card │ ├── card_select.json │ ├── card_flip.json │ ├── card.md │ └── card_state.json ├── event_core.json └── readme.md /contexts/app.json: -------------------------------------------------------------------------------- 1 | { 2 | "app" : { 3 | "version" : "1.9.294", 4 | "build" : "7bdje8c" 5 | } 6 | } -------------------------------------------------------------------------------- /components/rating/rating_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{value of the rating}}", 4 | "component" : "setting", 5 | "component_event" : "rating_select", 6 | "intent" : "navigation" 7 | } -------------------------------------------------------------------------------- /components/screen/screen_view.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "display", 3 | "label" : "{{title of the screen}}", 4 | "component" : "screen", 5 | "component_event" : "screen_view", 6 | "intent" : "navigation" 7 | } -------------------------------------------------------------------------------- /components/hyperlink/hyperlink.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Hyperlink 2 | 3 | Text hyperlinks are sections of text that have a URL linked within them. 4 | 5 | # Component Events 6 | ## Hyperlink Select 7 | When the link is selected. -------------------------------------------------------------------------------- /components/media/media.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Media 2 | 3 | Any audio and/or visual elements use the media component. 4 | 5 | # Component Events 6 | ## Media Interaction 7 | When the user interacts with any kind of audio/visual media. -------------------------------------------------------------------------------- /components/search/search_result_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{name of the result item}}", 4 | "component" : "search", 5 | "component_event" : "search_result_select", 6 | "intent" : "search" 7 | } -------------------------------------------------------------------------------- /components/navigation/navigation_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{title of the navigation item}}", 4 | "component" : "navigation", 5 | "component_event" : "navigation_select", 6 | "intent" : "navigation" 7 | } -------------------------------------------------------------------------------- /contexts/localisation.json: -------------------------------------------------------------------------------- 1 | { 2 | "localisation" : { 3 | "translation_key_name" : "{{translation_key}}", 4 | "displayed_language" : "{{2-letter ISO 639-1 language code}}", 5 | "displayed_region" : "{{2-letter ISO 3166-1 country code}}" 6 | } 7 | } -------------------------------------------------------------------------------- /components/modal/modal_dismiss.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "select", 4 | "timer" 5 | ], 6 | "label" : "{{title of the modal}}", 7 | "component" : "modal", 8 | "component_event" : "modal_dismiss", 9 | "intent" : "navigation" 10 | } -------------------------------------------------------------------------------- /components/modal/modal_display.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "display", 4 | "timer" 5 | ], 6 | "label" : "{{title of the modal}}", 7 | "component" : "modal", 8 | "component_event" : "modal_display", 9 | "intent" : "navigation" 10 | } -------------------------------------------------------------------------------- /contexts/business_objects.json: -------------------------------------------------------------------------------- 1 | { 2 | "partner_id" : "fedex", 3 | 4 | "objects": [{ 5 | "id" : "ihdc723dd", 6 | "type" : "support_ticket" 7 | }], 8 | [{ 9 | "id" : "podn1223sss-fwefefwf", 10 | "type" : "order" 11 | }] 12 | } -------------------------------------------------------------------------------- /components/selection_control/slider_adjust.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{label of the slider}}", 4 | "component" : "selection_control", 5 | "component_event" : "slider_adjust", 6 | "intent" : "setting", 7 | "start_state" : 1.0, 8 | "end_state" : 1.2 9 | } -------------------------------------------------------------------------------- /components/rating/rating.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Rating 2 | Wherever the user can assign a numeric or non-numeric feedback, a rating component is being used. For example a 👍 or 👎 element. 3 | 4 | # Component Events 5 | ## Rating Select 6 | A rating select is when the user chooses a rating value. -------------------------------------------------------------------------------- /components/list/list_view.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "select", 4 | "timer", 5 | "scroll", 6 | "display" 7 | ], 8 | "label" : "{{title of the list}}", 9 | "component" : "list", 10 | "component_event" : "list_view", 11 | "intent" : "navigation" 12 | } -------------------------------------------------------------------------------- /components/notification/notification_dismiss.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "select", 4 | "timer" 5 | ], 6 | "label" : "{{title of the notification}}", 7 | "component" : "notification", 8 | "component_event" : "notification_dismiss", 9 | "intent" : "navigation" 10 | } -------------------------------------------------------------------------------- /components/screen/screen.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Screen 2 | 3 | Screens are the context of the entire frame in a mobile app or the entire page of a website. 4 | 5 | # Component Events 6 | ## Screen View 7 | When the entire screen is changed, under any circumstances. The event is called when the user is shown the screen. -------------------------------------------------------------------------------- /components/input/input_exit.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "click", 3 | "label" : "{{title of the input field}}", 4 | "component" : "input", 5 | "component_event" : "input_exit", 6 | "intent" : "navigation", 7 | "start_state" : [ 8 | "empty", 9 | "filled" 10 | ], 11 | "end_state" : [ 12 | "empty", 13 | "filled" 14 | ] 15 | } -------------------------------------------------------------------------------- /components/selection_control/switch_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{label of the switch}}", 4 | "component" : "selection_control", 5 | "component_event" : "switch_select", 6 | "intent" : "setting", 7 | "start_state" : [ 8 | "active", 9 | "inactive" 10 | ], 11 | "end_state" : [ 12 | "active", 13 | "inactive" 14 | ] 15 | } -------------------------------------------------------------------------------- /components/selection_control/checkbox_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{label of the checkbox}}", 4 | "component" : "selection_control", 5 | "component_event" : "checkbox_select", 6 | "intent" : "setting", 7 | "start_state" : [ 8 | "active", 9 | "inactive" 10 | ], 11 | "end_state" : [ 12 | "active", 13 | "inactive" 14 | ] 15 | } -------------------------------------------------------------------------------- /components/selection_control/radio_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{label of the radio button}}", 4 | "component" : "selection_control", 5 | "component_event" : "radio_select", 6 | "intent" : "setting", 7 | "start_state" : [ 8 | "active", 9 | "inactive" 10 | ], 11 | "end_state" : [ 12 | "active", 13 | "inactive" 14 | ] 15 | } -------------------------------------------------------------------------------- /components/search/search_filter.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{name of the search element}}", 4 | "component" : "search", 5 | "component_event" : "search_filter", 6 | "intent" : "navigation", 7 | "options" : { 8 | "location" : ["{{input term}}","",null], 9 | "radius" : ["{{integer}}",null], 10 | "is_open_now" : [true, false, null] 11 | } 12 | } -------------------------------------------------------------------------------- /contexts/identity.json: -------------------------------------------------------------------------------- 1 | { 2 | "username": "{{unique identifier for the user}}", 3 | "user_id": "{{unique identifier for the user}}", 4 | "gender" : ["m","f"], 5 | "is_biometrics_active": [true, false], 6 | "is_registered" : [true, false], 7 | "is_logged_in" : [true, false], 8 | "is_email_confirmed" : [true, false], 9 | "language" : ["en","de","fr","it"], 10 | "is_push_active" : [true, false] 11 | } -------------------------------------------------------------------------------- /components/input/input.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Input 2 | 3 | Any input fields not found within a search component are considered as an input component. 4 | 5 | # Component Events 6 | ## Input Exit 7 | When the user exits an input text field (by clicking/interacting elsewhere). 8 | 9 | **N.B. Since the Input Exit could contain confidential or private information, the label is set to the actual title of the input field itself, e.g. “email” or “height_cm”.** -------------------------------------------------------------------------------- /components/notification/notification_display.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "display", 4 | "timer" 5 | ], 6 | "label" : "{{title of the notification}}", 7 | "component" : "notification", 8 | "component_event" : "notification_display", 9 | "intent" : "navigation", 10 | "start_state" : [ 11 | "error", 12 | "warning" 13 | ], 14 | "end_state" : [ 15 | "error", 16 | "warning" 17 | ] 18 | } -------------------------------------------------------------------------------- /components/button/button_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{button text}}", 4 | "component" : "button", 5 | "component_event" : "button_select", 6 | "intent" : [ 7 | "camera", 8 | "microphone", 9 | "location", 10 | "map", 11 | "messaging", 12 | "navigation", 13 | "share", 14 | "storage", 15 | "telephone", 16 | "purchase", 17 | "setting" 18 | ] 19 | } -------------------------------------------------------------------------------- /components/card/card_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{title of the card}}", 4 | "component" : "card", 5 | "component_event" : "card_select", 6 | "intent" : [ 7 | "camera", 8 | "microphone", 9 | "location", 10 | "map", 11 | "messaging", 12 | "navigation", 13 | "share", 14 | "storage", 15 | "telephone", 16 | "purchase", 17 | "setting" 18 | ] 19 | } -------------------------------------------------------------------------------- /components/list/list_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "click", 3 | "label" : "{{title of the list item}}", 4 | "component" : "list", 5 | "component_event" : "list_select", 6 | "intent" : [ 7 | "camera", 8 | "microphone", 9 | "location", 10 | "map", 11 | "messaging", 12 | "navigation", 13 | "share", 14 | "storage", 15 | "telephone", 16 | "purchase", 17 | "setting" 18 | ] 19 | } -------------------------------------------------------------------------------- /components/modal/modal_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{title of the modal}}", 4 | "component" : "modal", 5 | "component_event" : "modal_select", 6 | "intent" : [ 7 | "camera", 8 | "microphone", 9 | "location", 10 | "map", 11 | "messaging", 12 | "navigation", 13 | "share", 14 | "storage", 15 | "telephone", 16 | "purchase", 17 | "setting" 18 | ] 19 | } -------------------------------------------------------------------------------- /components/search/search_initiate.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "select", 4 | "display", 5 | "timer" 6 | ], 7 | "label" : "{{search term}}", 8 | "component" : "search", 9 | "component_event" : "search_initiate", 10 | "intent" : "search", 11 | "options" : { 12 | "location" : ["{{input term}}","",null], 13 | "radius" : ["{{integer}}",null], 14 | "is_open_now" : [true, false, null] 15 | }, 16 | "version" : 1.0 17 | } -------------------------------------------------------------------------------- /components/navigation/navigation_state.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{title of the navigation item}}", 4 | "component" : "navigation", 5 | "component_event" : "navigation_state", 6 | "intent" : "navigation", 7 | "start_state" : [ 8 | "visible", 9 | "hidden", 10 | "expanded", 11 | "collapsed" 12 | ], 13 | "end_state" : [ 14 | "visible", 15 | "hidden", 16 | "expanded", 17 | "collapsed" 18 | ] 19 | } -------------------------------------------------------------------------------- /components/hyperlink/hyperlink_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{destination URL}}", 4 | "component" : "hyperlink", 5 | "component_event" : "hyperlink_select", 6 | "intent" : [ 7 | "camera", 8 | "microphone", 9 | "location", 10 | "map", 11 | "messaging", 12 | "navigation", 13 | "share", 14 | "storage", 15 | "telephone", 16 | "purchase", 17 | "setting" 18 | ] 19 | } 20 | -------------------------------------------------------------------------------- /components/notification/notification_select.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : "select", 3 | "label" : "{{title of the notification}}", 4 | "component" : "notification", 5 | "component_event" : "notification_select", 6 | "intent" : [ 7 | "camera", 8 | "microphone", 9 | "location", 10 | "map", 11 | "messaging", 12 | "navigation", 13 | "share", 14 | "storage", 15 | "telephone", 16 | "purchase", 17 | "setting" 18 | ] 19 | } -------------------------------------------------------------------------------- /contexts/entities.json: -------------------------------------------------------------------------------- 1 | { 2 | "realm_id" : [ 3 | "001", 4 | "002", 5 | "003" 6 | ], 7 | "realm_name" : [ 8 | "home", 9 | "support_functions", 10 | "products", 11 | "services" 12 | ], 13 | "service_id" : [ 14 | "001", 15 | "002", 16 | "003", 17 | "004" 18 | ], 19 | "service_name" : [ 20 | "home", 21 | "user_login", 22 | "password_reset", 23 | "shopping_cart" 24 | ] 25 | } -------------------------------------------------------------------------------- /components/list/list.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: List 2 | 3 | Lists are collections of items that contain elements within them. The elements can sometimes be interacted with individually as well. 4 | 5 | # Component Events 6 | ## List View 7 | A list view when a list itself is shown to the user. 8 | 9 | ## List Select 10 | A select event is when an item in a list is interacted with. 11 | 12 | ## List State 13 | The list state event is when the display of the list is changed in any way (e.g. expanding or collapsing content). -------------------------------------------------------------------------------- /components/card/card_flip.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "select", 4 | "scroll", 5 | "timer" 6 | ], 7 | "label" : "{{title of the card}}", 8 | "component" : "card", 9 | "component_event" : "card_flip", 10 | "intent" : [ 11 | "camera", 12 | "microphone", 13 | "location", 14 | "map", 15 | "messaging", 16 | "navigation", 17 | "share", 18 | "storage", 19 | "telephone", 20 | "purchase", 21 | "setting" 22 | ] 23 | } -------------------------------------------------------------------------------- /components/navigation/navigation.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Navigation 2 | 3 | Navigation items concern movement within the page or digital product, for example switching tabs. 4 | 5 | *Distinguishing between lists and navigation can sometimes be difficult. Discuss internally when it's not clear which component is being used.* 6 | 7 | # Component Events 8 | ## Navigation Select 9 | When the user selects any item in the navigation. 10 | 11 | ## Navigation State 12 | When the navigation state is changed, e.g. through expanding or collapsing. -------------------------------------------------------------------------------- /components/button/button.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Button 2 | 3 | Buttons can be selected by the user to take the user to a different destination (in or out of view range). Buttons can also be floating/hovering above elements and can provide a context menu to interact with multiple options. Buttons do not need to be in a classic rectangle shape either. 4 | 5 | # Component Events 6 | ## Button Select 7 | When the button is selected and released again. 8 | 9 | ## Button Hold 10 | When the button is selected, but not released immediately (within a set period of time). -------------------------------------------------------------------------------- /components/media/media_interaction.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "select", 4 | "display", 5 | "scroll", 6 | "timer" 7 | ], 8 | "label" : "{{title of the media element}}", 9 | "component" : "media", 10 | "component_event" : "media_interaction", 11 | "intent" : "media", 12 | "media_type" : [ 13 | "audio", 14 | "video" 15 | ], 16 | "media_interaction_type" : [ 17 | "play", 18 | "pause", 19 | "resume", 20 | "replay", 21 | "fast_forward", 22 | "rewind", 23 | "slower", 24 | "faster", 25 | "record" 26 | ] 27 | } -------------------------------------------------------------------------------- /components/card/card.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Card 2 | 3 | Cards contain content and (potential) actions about a single subject or topic. 4 | 5 | **N.B. Interactions within cards themselves are governed by the individual action type (e.g. a toggle will be under the Selection Controls component). Card events only concern interactions with the Card itself.** 6 | 7 | # Component Events 8 | ## Card Select 9 | A select event is when a card is interacted with. 10 | 11 | ## Card Flip 12 | A flip event is when a card is flipped to the opposite side. 13 | 14 | ## Card State 15 | The state event is when the display of the card is changed in any way (e.g. expanding or collapsing content). -------------------------------------------------------------------------------- /components/notification/notification.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Notification 2 | 3 | Notifications allow users to view and/or select a choice from a variety of alerts or messages. They include elements that are often referred to as “Indicators”, “Helpers”, “Upload Bar” or “Alerts”. 4 | 5 | *N.B. The “modal” type component is not considered as Notifications but on its own.* 6 | 7 | # Component Events 8 | ## Notification Display 9 | When the notification is shown (within view). 10 | 11 | ## Notification Dismiss 12 | When the notification is hidden from the user, with or without user input. 13 | 14 | ## Notification Select 15 | When the notification is interacted with by the user. -------------------------------------------------------------------------------- /components/modal/modal.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Modal 2 | 3 | Modals are elements that visually display over other screens and (in some cases) prevent the user from continuing until an action is successful. 4 | 5 | **N.B.** Unlike Cards, interactions within modals themselves use the Modal Select event and will additionally also trigger the individual component’s type. 6 | 7 | *e.g. Clicking a checkbox within a modal will trigger BOTH a Modal Select & Checkbox Select event.* 8 | 9 | # Component Events 10 | ## Modal Display 11 | When the modal is shown (within view). 12 | 13 | ## Modal Dismiss 14 | When the modal is hidden from the user, with or without user input. 15 | 16 | ## Modal Select 17 | When the modal is interacted with by the user. -------------------------------------------------------------------------------- /components/list/list_state.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "select", 4 | "timer", 5 | "scroll" 6 | ], 7 | "label" : "{{title of the list}}", 8 | "component" : "list", 9 | "component_event" : "list_state", 10 | "intent" : "navigation", 11 | "start_state" : [ 12 | "active", 13 | "inactive", 14 | "loading", 15 | "focus", 16 | "error", 17 | "warning", 18 | "visible", 19 | "hidden", 20 | "expanded", 21 | "collapsed" 22 | ], 23 | "end_state" : [ 24 | "active", 25 | "inactive", 26 | "loading", 27 | "focus", 28 | "error", 29 | "warning", 30 | "visible", 31 | "hidden", 32 | "expanded", 33 | "collapsed" 34 | ] 35 | } -------------------------------------------------------------------------------- /components/selection_control/selection_control.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Selection Control 2 | 3 | All instances of Selection Controls such as radio buttons, checkboxes, sliders and toggles, which allow a user to make selections on the page. This also includes different shapes of selectors, such as date pickers. 4 | 5 | # Component Events 6 | ## Radio Select 7 | When the radio button is clicked or pressed. 8 | 9 | ## Checkbox Select 10 | When the checkbox is checked or unchecked. This includes other shapes than squares that have the same behaviour (e.g. hearts). 11 | 12 | ## Switch Select 13 | When the switch is moved in either direction. 14 | 15 | *N.B. The switch can also be represented by a pair of radio buttons!* 16 | 17 | ## Slider Adjust 18 | When the slider is moved in either direction. -------------------------------------------------------------------------------- /components/search/search.md: -------------------------------------------------------------------------------- 1 | # Data Library Component: Search 2 | 3 | A search component is used when information can be filtered or found using a search bar or filters. 4 | 5 | **Interactions within Search only triggers events from the Search component and not from other components.** 6 | 7 | # Component Events 8 | ## Search Initiate 9 | When the triggers a search with any or no filters applied. 10 | In a text field with instant search, it is recommended to only trigger this event for words with >= 3 letters (for Latin languages). 11 | 12 | ## Search Filter 13 | When the user adjusts any element from the filter options default values provided (e.g. moves the distance slider from default 10km to 30km). 14 | 15 | ## Search Result Select 16 | When the user selects any element of the search results list. -------------------------------------------------------------------------------- /components/card/card_state.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "select", 4 | "timer", 5 | "scroll" 6 | ], 7 | "label" : "{{title of the card}}", 8 | "component" : "card", 9 | "component_event" : "card_state", 10 | "intent" : [ 11 | "camera", 12 | "microphone", 13 | "location", 14 | "map", 15 | "messaging", 16 | "navigation", 17 | "share", 18 | "storage", 19 | "telephone", 20 | "purchase", 21 | "setting" 22 | ], 23 | "start_state" : [ 24 | "active", 25 | "inactive", 26 | "loading", 27 | "focus", 28 | "error", 29 | "warning", 30 | "visible", 31 | "hidden", 32 | "expanded", 33 | "collapsed" 34 | ], 35 | "end_state" : [ 36 | "active", 37 | "inactive", 38 | "loading", 39 | "focus", 40 | "error", 41 | "warning", 42 | "visible", 43 | "hidden", 44 | "expanded", 45 | "collapsed" 46 | ] 47 | } -------------------------------------------------------------------------------- /event_core.json: -------------------------------------------------------------------------------- 1 | { 2 | "trigger" : [ 3 | "click", 4 | "display", 5 | "scroll", 6 | "timer" 7 | ], 8 | "label" : "{{primary label of the element}}", 9 | "component" : [ 10 | "button", 11 | "card", 12 | "hyperlink", 13 | "input", 14 | "list", 15 | "media", 16 | "modal", 17 | "navigation", 18 | "notification", 19 | "rating", 20 | "screen", 21 | "search", 22 | "selection_control" 23 | ], 24 | "component_event" : [ 25 | "button_click", 26 | "card_flip", 27 | "card_select", 28 | "card_state", 29 | "checkbox_select", 30 | "hyperlink_click", 31 | "input_exit", 32 | "list_select", 33 | "list_state", 34 | "list_view", 35 | "media_interaction", 36 | "modal_dismiss", 37 | "modal_display", 38 | "modal_select", 39 | "navigation_select", 40 | "navigation_state", 41 | "notification_dismiss", 42 | "notification_display", 43 | "notification_select", 44 | "radio_select", 45 | "screen_view", 46 | "search_filter", 47 | "search_initiate", 48 | "search_result_select", 49 | "slider_adjust", 50 | "switch_select" 51 | ], 52 | "intent" : [ 53 | "camera", 54 | "microphone", 55 | "location", 56 | "map", 57 | "media", 58 | "messaging", 59 | "navigation", 60 | "share", 61 | "storage", 62 | "telephone", 63 | "purchase", 64 | "setting" 65 | ], 66 | "start_state" : [ 67 | "active", 68 | "inactive", 69 | "loading", 70 | "focus", 71 | "error", 72 | "warning", 73 | "visible", 74 | "hidden", 75 | "expanded", 76 | "collapsed", 77 | "empty", 78 | "filled" 79 | ], 80 | "end_state" : [ 81 | "active", 82 | "inactive", 83 | "loading", 84 | "focus", 85 | "error", 86 | "warning", 87 | "visible", 88 | "hidden", 89 | "expanded", 90 | "collapsed", 91 | "empty", 92 | "filled" 93 | ], 94 | "media_type" : [ 95 | "audio", 96 | "video" 97 | ], 98 | "media_interaction_type" : [ 99 | "play", 100 | "pause", 101 | "resume", 102 | "replay", 103 | "fast_forward", 104 | "rewind", 105 | "slower", 106 | "faster", 107 | "record" 108 | ], 109 | "search_properties" : { 110 | "location" : ["{{input term}}","",null], 111 | "radius" : ["{{integer}}",null], 112 | "is_open_now" : [true, false, null] 113 | }, 114 | "version" : 1.0 115 | } -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # Welcome the Data Library! 2 | ## Introduction 3 | The goal of any kind of frontend tracking is to capture behavioural data in a way that is clear, comprehensive, and actionable. The data captured must be able to provide answers to a wide range of business questions. 4 | 5 | In order to design such a tracking system, we have to start by understanding what are the behaviours we want to capture, which means understanding the user experience of the service in question. 6 | 7 | ## Core Concept 8 | This concept revolves around a core set of interactions that are possible on different types of UX elements. These given elements are defined as Components in our Data Library and upon these elements, certain interactions (events) are possible, according to our pre-defined specification. 9 | 10 | ## Reasons for Doing 11 | - reduction of efforts in development for tracking specifications, implementing tracking and testing due to the "one-shot" implementation strategy 12 | 13 | - ensure a better alignment of data collection to the systems that are optimised for them due to a tool-agnostic strategy 14 | 15 | - increase data quality through a systematic approach and more consistent implementation 16 | 17 | - guarantee principles of data protection and privacy by design (e.g. by preventing leakage of personal data) 18 | 19 | # Semantics 20 | ## Syntax 21 | The schemas are defined in JSON. The reasons for doing this are because JSON: 22 | 23 | - …is a universal standard in programming 24 | - …allows for nesting of keys which automatically forms a relationship that we do not need to explicitly describe 25 | - …can be used across varying systems and is not vendor-specific 26 | - …syntax is relatively easy to read 27 | - …does not pre-determine how data should be stored 28 | 29 | ## Format 30 | All event properties and values use `snake_case` and all values are always **lowercased**. All values are sent in English (although translation keys can additionally be used if needed). 31 | 32 | ## Stateless 33 | All events and values within are stateless; they neither refer to other events that already happened nor do the values reflect any other state than what is currently known at the time of the event occurring. 34 | 35 | # Specification 36 | The specification consists of three main parts: 37 | 38 | **1. Data Library Components & Events** 39 | 40 | A component consists of a UX element that is visible in the frontend. The components are grouped as sensibly as possible to avoid a large amount of similar components. Events that are possible on the component are listed as separate unique events. 41 | 42 | **2. Event Core** 43 | 44 | The event core covers the information of what event was triggered, such as which UX component it was and whether it was triggered by a click or other type of interaction. 45 | 46 | **Non-Nullable Properties** 47 | 48 | The following properties must ALWAYS be sent with a value that is not null: 49 | 50 | - action 51 | - label 52 | - component 53 | - component_event 54 | 55 | **Nullable Properties** 56 | If one of the properties below is not required for an event it does not need to be declared in the event. 57 | 58 | | | start_state | end_state | options | media_type | media_interaction_type | 59 | | ----------- | ----------- | ----------- | ----------- | ----------- | ----------- | 60 | | screen_view | | | | | | 61 | | hyperlink_select | | | | | | 62 | | button_select | | | | | | 63 | | radio_select | x | x | | | | 64 | | checkbox_select | x | x | | | | 65 | | switch_select | x | x | | | | 66 | | slider_adjust | x | x | | | | 67 | | card_select | | | | | | 68 | | card_flip | | | | | | 69 | | card_state | x | x | | | | 70 | | notification_display | | | | | | 71 | | notification_dismiss | | | | | | 72 | | notification_select | | | | | | 73 | | modal_display | | | | | | 74 | | modal_dismiss | | | | | | 75 | | modal_select | | | | | | 76 | | navigation_select | | | | | | 77 | | navigation_state | x | x | | | | 78 | | list_select | | | | | | 79 | | list_state | x | x | | | | 80 | | search_initiate | | | x | | | 81 | | search_filter | | | | | | 82 | | search_result_select | | | x | | | 83 | | media_interaction | | | | x | x | 84 | | input_exit | x | x | | | | 85 | 86 | **3. Event Contexts** 87 | 88 | As part of the event, additional information can be sent about things related to the event, such as user identity, region and language settings, etc. 89 | 90 | **N.B.** All Event Contexts must be sent with every event - the information within is validated against the schema as part of event processing. Bad values or events will be marked or discarded as necessary. 91 | 92 | ## Global Event Schema 93 | **The Event Core and Event Contexts are covered under the Global Event Schema.** 94 | 95 | The schema is a "contract" that must be upheld and consists of properties and their acceptable values. Each event must adhere to the schema. There are a set of event properties that are non-nullable and some that are dependent on which event was sent. 96 | 97 | The event schema stored in this repository covers all possible properties and acceptable values. 98 | 99 | ## Data Library Components & Events 100 | Each component is visible under the relevant components subdirectory, e.g. /components/modal. The possible events are defined individually and have their own individual readme & JSON files (which adhere to the Global Event Schema) but offer examples and more detailed information about each event. 101 | 102 | ## Event Contexts 103 | Each Event Context is defined within the /_contexts directory as it's own individual JSON file. 104 | > **N.B.**: An event will always be sent with both the Event Core as well as the Event Contexts but depending on which analytics system you are sending the information too, the syntax may need to be adapted. 105 | 106 | # Examples & Values 107 | Many values within the schemas can be considered as suggestions, with many more properties or values that can be added. Concrete examples of various component implementations can be found in the /_examples directory. 108 | 109 | # More Information 110 | 111 | ## Event Core: `intent` 112 | Many teams struggle to understand how to implement the `intent` property. Seen from a user flow perspective, there are only a limited amount of possible outcomes when interacting with an element on the page. These for values are represented in the schema through the values `camera`,`microphone`, `location`, `map`, etc. A large percentage of events will have the `navigation` value by default. This property _can_ be constructed late-join, but it is highly recommended to implement it at the time of collection. 113 | 114 | ## Event Core: `options` 115 | Filtering (search) is possibly one of the more difficult aspects of the Data Library to implement. Since many search modals have various levels of filters and adjustments, the list of properties can become very long, it's recommended to try and standardise the search properties across all implementations of search in your product. For example, if you have a store selling lights and lightbulbs, with two different search modules (one for each), it makes sense to have a `wattage` property for both, rather than adding `max_wattage` for lights and `output_wattage` for lightbulbs. 116 | 117 | In addition, the `options` parameter can be used to attach more specific items that don't conform to the event core model, but don't belong inside of it's own schema due to being about the event itself (rather than its meaning). 118 | 119 | ## Contexts: Entities & Business Objects 120 | Semantically, these two contexts will be the most important for your event data. Without these 2 you might as well just be implementing counters of how often users click buttons! For data modeling further downstream, you need to understand what the button _is_, not only that it's a button. This is where these two contexts come in. You can add any additional contexts and properties necessary for your business. 121 | 122 | ### Entities 123 | When implementing the Entities, think about how your product is built. The classification is based on your operating business model(s) and company type. For a B2C SaaS selling furniture, accessories and other services for rental apartments, the realms may be named `products` and `services`. 124 | 125 | ### Business Objects 126 | For the Business Objects, assess what types of information you are offering on your platform. Obviously in an e-commerce situation you will have a `products` object, but think deeper about what other types of objects you may have such as `order`, `support_case` or `faq_item`. A semantic tagging of your business objects will allow you to more easily and fully model and understand exactly what actions are being taken by your users. --------------------------------------------------------------------------------