MetaMetrics documentation (#6624)

docs/creating-metrics-events.md

@@ -0,0 +1,71 @@
+## Creating Metrics Events
+
+The `metricsEvent` method is made available to all components via context. This is done in `metamask-extension/ui/app/helpers/higher-order-components/metametrics/metametrics.provider.js`. As such, it can be called in all components by first adding it to the context proptypes:
+
+```
+static contextTypes = {
+  t: PropTypes.func,
+  metricsEvent: PropTypes.func,
+}
+```
+
+and then accessing it on `this.context`.
+
+Below is an example of a metrics event call:
+
+```
+this.context.metricsEvent({
+  eventOpts: {
+    category: 'Navigation',
+    action: 'Main Menu',
+    name: 'Switched Account',
+  },
+})
+```
+
+### Base Schema
+
+Every `metricsEvent` call is passed an object that must have an `eventOpts` property. This property is an object that itself must have three properties:
+- category: categorizes events according to the schema we have set up in our matomo.org instance
+- action: usually describes the page on which the event takes place, or sometimes a significant subsections of a page
+- name: a very specific descriptor of the event
+
+### Implicit properties
+
+All metrics events send the following data when called:
+- network
+- environmentType
+- activeCurrency
+- accountType
+- numberOfTokens
+- numberOfAccounts
+
+These are added to the metrics event via the metametrics provider.
+
+### Custom Variables
+
+Metrics events can include custom variables. These are included within the `customVariables` property that is a first-level property within first param passed to `metricsEvent`.
+
+For example:
+```
+this.context.metricsEvent({
+  eventOpts: {
+    category: 'Settings',
+    action: 'Custom RPC',
+    name: 'Error',
+  },
+  customVariables: {
+    networkId: newRpc,
+    chainId,
+  },
+})
+```
+
+Custom variables can have custom property names and values can be strings or numbers.
+
+**To include a custom variable, there are a set of necessary steps you must take.**
+
+1. First you must declare a constant equal to the desired name of the custom variable property in `metamask-extension/ui/app/helpers/utils/metametrics.util.js` under `//Custom Variable Declarations`
+1. Then you must add that name to the `customVariableNameIdMap` declaration
+    1. The id must be between 1 and 5
+    1. There can be no more than 5 custom variables assigned ids on a given url

ui/app/helpers/utils/metametrics.util.js

@@ -12,6 +12,8 @@ const METAMETRICS_TRACKING_URL = inDevelopment
   ? 'http://www.metamask.io/metametrics'
   : 'http://www.metamask.io/metametrics-prod'
 
+/** ***************Custom variables*************** **/
+// Custon variable declarations
 const METAMETRICS_CUSTOM_GAS_LIMIT_CHANGE = 'gasLimitChange'
 const METAMETRICS_CUSTOM_GAS_PRICE_CHANGE = 'gasPriceChange'
 const METAMETRICS_CUSTOM_FUNCTION_TYPE = 'functionType'
@@ -24,6 +26,28 @@ const METAMETRICS_CUSTOM_ERROR_MESSAGE = 'errorMessage'
 const METAMETRICS_CUSTOM_RPC_NETWORK_ID = 'networkId'
 const METAMETRICS_CUSTOM_RPC_CHAIN_ID = 'chainId'
 const METAMETRICS_CUSTOM_GAS_CHANGED = 'gasChanged'
+const METAMETRICS_CUSTOM_ASSET_SELECTED = 'assetSelected'
+
+const customVariableNameIdMap = {
+  [METAMETRICS_CUSTOM_FUNCTION_TYPE]: 1,
+  [METAMETRICS_CUSTOM_RECIPIENT_KNOWN]: 2,
+  [METAMETRICS_CUSTOM_CONFIRM_SCREEN_ORIGIN]: 3,
+  [METAMETRICS_CUSTOM_GAS_LIMIT_CHANGE]: 4,
+  [METAMETRICS_CUSTOM_GAS_PRICE_CHANGE]: 5,
+
+  [METAMETRICS_CUSTOM_FROM_NETWORK]: 1,
+  [METAMETRICS_CUSTOM_TO_NETWORK]: 2,
+
+  [METAMETRICS_CUSTOM_RPC_NETWORK_ID]: 1,
+  [METAMETRICS_CUSTOM_RPC_CHAIN_ID]: 2,
+
+  [METAMETRICS_CUSTOM_ERROR_FIELD]: 3,
+  [METAMETRICS_CUSTOM_ERROR_MESSAGE]: 4,
+
+  [METAMETRICS_CUSTOM_GAS_CHANGED]: 1,
+  [METAMETRICS_CUSTOM_ASSET_SELECTED]: 2,
+}
+/** ********************************************************** **/
 
 const METAMETRICS_CUSTOM_NETWORK = 'network'
 const METAMETRICS_CUSTOM_ENVIRONMENT_TYPE = 'environmentType'
@@ -32,20 +56,6 @@ const METAMETRICS_CUSTOM_ACCOUNT_TYPE = 'accountType'
 const METAMETRICS_CUSTOM_NUMBER_OF_TOKENS = 'numberOfTokens'
 const METAMETRICS_CUSTOM_NUMBER_OF_ACCOUNTS = 'numberOfAccounts'
 
-const customVariableNameIdMap = {
-  [METAMETRICS_CUSTOM_FUNCTION_TYPE]: 1,
-  [METAMETRICS_CUSTOM_RECIPIENT_KNOWN]: 2,
-  [METAMETRICS_CUSTOM_CONFIRM_SCREEN_ORIGIN]: 3,
-  [METAMETRICS_CUSTOM_GAS_LIMIT_CHANGE]: 4,
-  [METAMETRICS_CUSTOM_GAS_PRICE_CHANGE]: 5,
-  [METAMETRICS_CUSTOM_FROM_NETWORK]: 1,
-  [METAMETRICS_CUSTOM_TO_NETWORK]: 2,
-  [METAMETRICS_CUSTOM_RPC_NETWORK_ID]: 1,
-  [METAMETRICS_CUSTOM_RPC_CHAIN_ID]: 2,
-  [METAMETRICS_CUSTOM_ERROR_FIELD]: 1,
-  [METAMETRICS_CUSTOM_ERROR_MESSAGE]: 2,
-  [METAMETRICS_CUSTOM_GAS_CHANGED]: 1,
-}
 
 const customDimensionsNameIdMap = {
   [METAMETRICS_CUSTOM_NETWORK]: 5,
@@ -61,6 +71,7 @@ function composeUrlRefParamAddition (previousPath, confirmTransactionOrigin) {
   return `&urlref=${externalOrigin ? 'EXTERNAL' : encodeURIComponent(previousPath.replace(/chrome-extension:\/\/\w+/, METAMETRICS_TRACKING_URL))}`
 }
 
+// composes query params of the form &dimension[0-999]=[value]
 function composeCustomDimensionParamAddition (customDimensions) {
   const customDimensionParamStrings = Object.keys(customDimensions).reduce((acc, name) => {
     return [...acc, `dimension${customDimensionsNameIdMap[name]}=${customDimensions[name]}`]
@@ -68,6 +79,8 @@ function composeCustomDimensionParamAddition (customDimensions) {
   return `&${customDimensionParamStrings.join('&')}`
 }
 
+// composes query params in form: &cvar={[id]:[[name],[value]]}
+// Example: &cvar={"1":["OS","iphone 5.0"],"2":["Matomo Mobile Version","1.6.2"],"3":["Locale","en::en"],"4":["Num Accounts","2"]}
 function composeCustomVarParamAddition (customVariables) {
   const customVariableIdValuePairs = Object.keys(customVariables).reduce((acc, name) => {
     return {
@@ -84,6 +97,28 @@ function composeParamAddition (paramValue, paramName) {
     : `&${paramName}=${paramValue}`
 }
 
+/**
+  * @name composeUrl
+  * @param {Object} config - configuration object for composing the metametrics url
+  * @property {object} config.eventOpts Object containing event category, action and name descriptors
+  * @property {object} config.customVariables Object containing custom properties with values relevant to a specific event
+  * @property {object} config.pageOpts Objects containing information about a page/route the event is dispatched from
+  * @property {number} config.network The selected network of the user when the event occurs
+  * @property {string} config.environmentType The "environment" the user is using the app from: 'popup', 'notification' or 'fullscreen'
+  * @property {string} config.activeCurrency The current the user has select as their primary currency at the time of the event
+  * @property {string} config.accountType The account type being used at the time of the event: 'hardware', 'imported' or 'default'
+  * @property {number} config.numberOfTokens The number of tokens that the user has added at the time of the event
+  * @property {number} config.numberOfAccounts The number of accounts the user has added at the time of the event
+  * @property {string} config.previousPath The location path the user was on prior to the path they are on at the time of the event
+  * @property {string} config.currentPath The location path the user is on at the time of the event
+  * @property {string} config.metaMetricsId A random id assigned to a user at the time of opting in to metametrics. A hexadecimal number
+  * @property {string} config.confirmTransactionOrigin The origin on a transaction
+  * @property {string} config.url The url to track an event at. Overrides `currentPath`
+  * @property {boolean} config.excludeMetaMetricsId Whether or not the tracked event data should be associated with a metametrics id
+  * @property {boolean} config.isNewVisit Whether or not the event should be tracked as a new visit/user sessions
+  * @returns {String} Returns a url to be passed to fetch to make the appropriate request to matomo.
+  *   Example: https://chromeextensionmm.innocraft.cloud/piwik.php?idsite=1&rec=1&apiv=1&e_c=Navigation&e_a=Home&e_n=Clicked%20Send:%20Eth&urlref=http%3A%2F%2Fwww.metamask.io%2Fmetametrics%2Fhome.html%23send&dimension5=3&dimension6=fullscreen&dimension7=ETH&dimension8=default&dimension9=0&dimension10=3&url=http%3A%2F%2Fwww.metamask.io%2Fmetametrics%2Fhome.html%23&_id=49c10aff19795e9a&rand=7906028754863992&pv_id=53acad&uid=49c1
+  */
 function composeUrl (config) {
   const {
     eventOpts = {},