| OLD | NEW |
|---|
| 1 # User Action Guidelines | 1 # User Action Guidelines |
| 2 | 2 |
| 3 This document gives the best practices on how to use user actions in code and | 3 This document gives the best practices on how to use user actions in code and |
| 4 how to document them for the dashboard. User actions come with only a name and | 4 how to document them for the dashboard. User actions come with only a name and |
| 5 a timestamp. They are best used when you care about a sequence--which actions | 5 a timestamp. They are best used when you care about a sequence--which actions |
| 6 happen in what order. If you don't care about the order, you should be using | 6 happen in what order. If you don't care about the order, you should be using |
| 7 histograms (likely enumerated histograms). | 7 histograms (likely enumerated histograms). |
| 8 | 8 |
| 9 Often, you want both user actions and histogram logging in your code. They | 9 Often, you want both user actions and histogram logging in your code. They |
| 10 enable different analyses. They're complementary. | 10 enable different analyses. They're complementary. |
| (...skipping 38 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 49 | 49 |
| 50 ### Generally, Do Not Emit Impressions | 50 ### Generally, Do Not Emit Impressions |
| 51 | 51 |
| 52 It's okay to emit user actions such as "ShowTranslateInfobar" or | 52 It's okay to emit user actions such as "ShowTranslateInfobar" or |
| 53 "DisplayedImageLinkContextMenu". However, more detailed impression information, | 53 "DisplayedImageLinkContextMenu". However, more detailed impression information, |
| 54 especially those not caused by the user (as in the second example) and not as | 54 especially those not caused by the user (as in the second example) and not as |
| 55 attention-grabbing (as in the first example), is often not useful for analyzing | 55 attention-grabbing (as in the first example), is often not useful for analyzing |
| 56 sequences of user actions. For example, don't emit | 56 sequences of user actions. For example, don't emit |
| 57 "ShowedSecureIconNextToOmnibox". | 57 "ShowedSecureIconNextToOmnibox". |
| 58 | 58 |
| 59 ### Testing | 59 ## Testing |
| 60 | 60 |
| 61 Test your user actions using *chrome://user-actions*. Make sure they're being | 61 Test your user actions using *chrome://user-actions*. Make sure they're being |
| 62 emitted when you expect and not emitted at other times. | 62 emitted when you expect and not emitted at other times. |
| 63 | 63 |
| 64 If this is a general UI surface, please try to check every platform. In | 64 If this is a general UI surface, please try to check every platform. In |
| 65 particular, check Windows (Views-based platforms), Mac (non-Views), Android | 65 particular, check Windows (Views-based platforms), Mac (non-Views), Android |
| 66 phone (yet other UI wrapper code), Android tablet (often triggers lookalike but | 66 phone (yet other UI wrapper code), Android tablet (often triggers lookalike but |
| 67 different menus), and iOS (yet more different UI wrapper code). | 67 different menus), and iOS (yet more different UI wrapper code). |
| 68 | 68 |
| 69 Also, check that your new user action is not mostly redundant with other user | 69 Also, check that your new user action is not mostly redundant with other user |
| 70 actions (see [advice above](#Do-Not-Emit-Redundantly)) and not emitted | 70 actions (see [advice above](#Do-Not-Emit-Redundantly)) and not emitted |
| 71 excessively (see [advice above](#Do-Not-Emit-Excessively)). | 71 excessively (see [advice above](#Do-Not-Emit-Excessively)). |
| 72 | 72 |
| 73 ### Revising User Actions | 73 In addition to testing interactively, you can have unit tests check the number |
| 74 of times a user action was emitted. See [user_action_tester.h](https://cs.chrom
ium.org/chromium/src/base/test/user_action_tester.h) |
| 75 for details. |
| 74 | 76 |
| 75 If you're changing the semantics of a user action (when it's emitted), make it | 77 ## Revising User Actions |
| 76 into a new user action with a new name. Otherwise the dashboard will be mixing | 78 |
| 77 two different interpretations of the data and make no sense. | 79 When changing the semantics of a user action (when it's emitted), make it into |
| 80 a new user action with a new name. Otherwise the dashboard will be mixing two |
| 81 different interpretations of the data and make no sense. |
| 78 | 82 |
| 79 ## Documenting User Actions | 83 ## Documenting User Actions |
| 80 | 84 |
| 81 ### Add User Actions and Documentation in the Same Changelist | 85 ### Add User Actions and Documentation in the Same Changelist |
| 82 | 86 |
| 83 If possible, please add the actions.xml description in the same changelist in | 87 If possible, please add the actions.xml description in the same changelist in |
| 84 which you add the user-action-emitting code. This has several benefits. One, | 88 which you add the user-action-emitting code. This has several benefits. One, |
| 85 it sometimes happens that the actions.xml reviewer has questions or concerns | 89 it sometimes happens that the actions.xml reviewer has questions or concerns |
| 86 about the user action description that reveal problems with interpretation of | 90 about the user action description that reveal problems with interpretation of |
| 87 the data and call for a different recording strategy. Two, it allows the user | 91 the data and call for a different recording strategy. Two, it allows the user |
| (...skipping 35 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 123 obsolete, annotating them with the associated date or milestone in the obsolete | 127 obsolete, annotating them with the associated date or milestone in the obsolete |
| 124 tag entry. If your user action is being replaced by a new version, we suggest | 128 tag entry. If your user action is being replaced by a new version, we suggest |
| 125 noting that in the previous user action's description. | 129 noting that in the previous user action's description. |
| 126 | 130 |
| 127 Deleting user action entries would be bad if someone accidentally reused your | 131 Deleting user action entries would be bad if someone accidentally reused your |
| 128 old user action name and which therefore corrupts new data with whatever old | 132 old user action name and which therefore corrupts new data with whatever old |
| 129 data is still coming in. It's also useful to keep obsolete user action | 133 data is still coming in. It's also useful to keep obsolete user action |
| 130 descriptions in actions.xml--that way, if someone is searching for a user action | 134 descriptions in actions.xml--that way, if someone is searching for a user action |
| 131 to answer a particular question, they can learn if there was a user action at | 135 to answer a particular question, they can learn if there was a user action at |
| 132 some point that did so even if it isn't active now. | 136 some point that did so even if it isn't active now. |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2866293002:
Metrics Documentation - Add Instruction for How To Unit Test (Closed)
