Mobile/Projects/Telemetry probes for Fennec UI elements: Difference between revisions

Mobile/Projects/Telemetry probes for Fennec UI elements (view source)

Revision as of 23:58, 21 March 2014

14 bytes removed , 21 March 2014

Editing concepts.

Rnewman

canmove, Confirmed users

640

edits

@@ Line 64: / Line 64: @@
 === Sessions ===
-Sessions are essentially scopes. They are meant to give context to events; this allows events to be more simple and reusable. Sessions are usually bound to some component of the UI. They are started when the user begins interacting with the UI component and are stopped when the user leaves. They also allow you record how long a user interacts with a given UI component. A simple use-case for sessions is the bookmarks panel in about:home. We start a session when the user swipes into the panel and stop it when they leave. This bookmarks session does two things: Firstly, it gives scope to any generic event that may occur within the panel (e.g loading a URL). Secondly, it allows us to figure out how much time users are spending in the bookmarks panel.
+Sessions are essentially scopes. They are meant to give context to events; this allows events to be more simple and reusable. Sessions are usually bound to some component of the UI, some user action with a duration, or some transient state.
-To start a session, call ''Telemetry.startUISession(String sessionName)''. Session names should be brief, lowercase, and should describe what UI component the user is interacting with. In certain cases where the UI component is dynamic, they could include an ID, essential to identifying that component. An example of this is with dynamic home panels, we use session names of the format "''homepanel:<panel_id>''" to identify home panel sessions.
+For example, a session might be begun when a user begins interacting with the UI component, and stopped when the interaction ends. They implicitly record the duration of the interaction.
-To stop a session call ''Telemetry.stopUISession(String sessionName, String reason)''. ''sessionName'' is the name of the session and
+A simple use-case for sessions is the bookmarks panel in about:home. We start a session when the user swipes into the panel, and stop it when they swipe away. This bookmarks session does two things: firstly, it gives scope to any generic event that may occur within the panel (e.g., loading a URL). Secondly, it allows us to figure out how much time users are spending in the bookmarks panel.
-''reason'' is essentially the reason the session was stopped. The reason field should capture why the user stopped interacting with the UI component; it should be brief, lowercase and generic so it can be reused in different places. Examples reasons are:
+To start a session, call ''Telemetry.startUISession(String sessionName)''. Session names should be brief, lowercase, and should describe which UI component the user is interacting with. In certain cases where the UI component is dynamic, they could include an ID, essential to identifying that component. An example of this is with dynamic home panels, we use session names of the format "''homepanel:<panel_id>''" to identify home panel sessions.
+To stop a session call ''Telemetry.stopUISession(String sessionName, String reason)''. ''sessionName'' is the name of the open session and ''reason'' is a descriptive cause for the ending. The reason field should capture why the user stopped interacting with the UI component. It should be brief, lowercase, and generic so it can be reused in different places. Examples reasons are:
 * "switched" - user transitioned to a UI element of equal level
 * "exit" - user left for an entirely different element.
 === Events ===
-Events capture key occurrences that of importance to us. They should be brief and simple, and should not contain sensitive or excess information. Context for events should come from the session (scope). An event can be created with four fields (via ''Telemetry.sendUIEvent''): action, method, extras, and timestamp.
+Events capture key occurrences. They should be brief and simple, and should not contain sensitive or excess information. Context for events should come from the session (scope). An event can be created with four fields (via ''Telemetry.sendUIEvent''): action, method, extras, and timestamp.
 * '''action''': name of the event. Should be brief and lowercase. If needed, you can make use of namespacing with a '-' separator. Example event names: "panel-switch", "panel-enable", "panel-disable", "panel-install".
-* '''method''' (Optional): used for user actions that can be performed in many ways. This field specifies the method in which the action was performed. For e.g, say we want to record an event for when a user adds an item to their reading list. This action can be performed by either long-tapping the reader icon in the address bar or done from within reader mode. We would use the same event name for both actions but specify two methods: "addressbar" and "readermode".
+* '''method''' (Optional): used for user actions that can be performed in many ways. This field specifies the method in which the action was performed. For example, users can add an item to their reading list either by long-tapping the reader icon in the address bar, or from within reader mode. We would use the same event name for both user actions but specify two methods: "addressbar" and "readermode".
-* '''extras''' (Optional): for extra information that may be useful in understanding the event. It is important to keep this very brief.
+* '''extras''' (Optional): for extra information that may be useful in understanding the event. Make an effort to keep this brief.
-* '''timestamp''' (Optional): time the event occurred. If not specified this field defaults to the realtime clock.
+* '''timestamp''' (Optional): time the event occurred. If not specified this field defaults to the current value of the realtime clock.
 === Clock ===