feat: add telemetry to companion (#1117)

* feat: add types for state

* tmp

* feat: ipfs-companion tracks views and sessions

* Update add-on/src/lib/telemetry.js

Co-authored-by: Nishant Arora <[email protected]>

* Update add-on/src/lib/telemetry.js

Co-authored-by: Nishant Arora <[email protected]>

* Update add-on/src/lib/telemetry.js

Co-authored-by: Nishant Arora <[email protected]>

* Update add-on/_locales/en/messages.json

Co-authored-by: Marcin Rataj <[email protected]>

* Update add-on/_locales/en/messages.json

Co-authored-by: Marcin Rataj <[email protected]>

* Update add-on/_locales/en/messages.json

Co-authored-by: Marcin Rataj <[email protected]>

* Update add-on/_locales/en/messages.json

Co-authored-by: Marcin Rataj <[email protected]>

* chore: fix options and state typings

* chore: use debug logger

* fix(lint): remove unused method

* fix(lint): run 'npm run fix:lint'

* chore: build and lint success

* chore(types): fix type errors

* chore: add docs/telemetry/COLLECTED_DATA.md

see ipfs-shipyard/ignite-metrics#35

* chore: update old metric group names in logConsent

* chore: clean up UI

* chore: use ignite-metrics from npm

* chore: update ignite-metrics and some types

* fix(tests): tests dont fail on countly-sdk-web import

* fix: build

* chore: temporarily use updated ignite-metrics

* chore: use deployed ignite-metrics version

* chore: address PR comments

* use latest ignite-metrics library
* don't use singleton function for grabbing metricsProvider
* ensure metrics initialize and update properly

* chore: pin ignite-metrics dependency

* chore(lint): fix lint errors

* fix: use browser.runtime.sendMessage

* Telemetry messages are passed between contexts using browser.runtime
* Upgraded to @ipfs-shipyard/[email protected]
* Updated consent handling from state to be more explicit

---------

Co-authored-by: Nishant Arora <[email protected]>
Co-authored-by: Marcin Rataj <[email protected]>

Author: 3 people

.gitignore

@@ -15,3 +15,6 @@
 /coverage
 /.nyc_output
 /add-on/manifest.json
+
+.DS_Store
+.vscode

add-on/_locales/en/messages.json

@@ -710,5 +710,45 @@
   "page_landingWelcome_projects_title": {
     "message": "Related Projects",
     "description": "Projects section title (page_landingWelcome_projects_title)"
+  },
+  "option_header_telemetry": {
+    "message": "Telemetry",
+    "description": "A section header on the Preferences screen (option_header_telemetry)"
+  },
+  "option_telemetry_disclaimer": {
+    "message": "We're collecting minimal telemetry data to improve and prioritize our work. Please consent to the collection of these metrics to assist in our efforts!",
+    "description": "Disclaimer about telemetry collection in the telemetry section on the Preferences screen (option_telemetry_disclaimer)"
+  },
+  "option_telemetryGroupMinimal_title": {
+    "message": "Feature Telemetry",
+    "description": "A title for the 'minimal' grouping of metrics we collect (option_telemetryGroupMinimal_title)"
+  },
+  "option_telemetryGroupMinimal_description": {
+    "message": "Collect basic feature and usage metrics to help maintainers to prioritize work on the most useful features.",
+    "description": "A description for the 'minimal' grouping of metrics we collect (option_telemetryGroupMinimal_description)"
+  },
+  "option_telemetryGroupMarketing_title": {
+    "message": "Marketing title",
+    "description": "A title for the 'marketing' grouping of metrics we collect (option_telemetryGroupMarketing_title)"
+  },
+  "option_telemetryGroupMarketing_description": {
+    "message": "Marketing description",
+    "description": "A description for the 'marketing' grouping of metrics we collect (option_telemetryGroupMarketing_description)"
+  },
+  "option_telemetryGroupPerformance_title": {
+    "message": "Performance title",
+    "description": "A title for the 'performance' grouping of metrics we collect (option_telemetryGroupPerformance_title)"
+  },
+  "option_telemetryGroupPerformance_description": {
+    "message": "Performance description",
+    "description": "A description for the 'performance' grouping of metrics we collect (option_telemetryGroupPerformance_description)"
+  },
+  "option_telemetryGroupTracking_title": {
+    "message": "Tracking title",
+    "description": "A title for the 'tracking' grouping of metrics we collect (option_telemetryGroupTracking_title)"
+  },
+  "option_telemetryGroupTracking_description": {
+    "message": "Tracking description",
+    "description": "A description for the 'tracking' grouping of metrics we collect (option_telemetryGroupTracking_description)"
   }
 }

add-on/src/background/background.html

@@ -2,3 +2,4 @@
 <meta charset="utf-8">
 <script src="/dist/bundles/ipfs.bundle.js"></script>
 <script src="/dist/bundles/backgroundPage.bundle.js"></script>
+<body></body>

add-on/src/background/background.js

@@ -13,12 +13,14 @@ browser.runtime.setUninstallURL(getUninstallURL(browser))
 
 // init add-on after all libs are loaded
 document.addEventListener('DOMContentLoaded', async () => {
+  browser.runtime.sendMessage({ telemetry: { trackView: 'background' } })
   // setting debug namespaces require page reload to get applied
   const debugNs = (await browser.storage.local.get({ logNamespaces: optionDefaults.logNamespaces })).logNamespaces
   if (debugNs !== localStorage.debug) {
     localStorage.debug = debugNs
     window.location.reload()
   }
   // init inlined to read updated localStorage.debug
+  // @ts-expect-error - TS does not know about window.ipfsCompanion
   window.ipfsCompanion = await createIpfsCompanion()
 })

add-on/src/landing-pages/welcome/page.js

@@ -55,7 +55,7 @@ const renderCompanionLogo = (i18n, isIpfsOnline) => {
 
   return html`
     <div class="mt4 mb2 flex flex-column justify-center items-center transition-all ${stateUnknown && 'state-unknown'}">
-      ${logo({ path: logoPath, size: logoSize, isIpfsOnline: isIpfsOnline })}
+      ${logo({ path: logoPath, size: logoSize, isIpfsOnline })}
       <p class="montserrat mt3 mb0 f2">${i18n.getMessage('page_landingWelcome_logo_title')}</p>
     </div>
   `

add-on/src/landing-pages/welcome/store.js

@@ -9,6 +9,7 @@ export default function createWelcomePageStore (i18n, runtime) {
     state.webuiRootUrl = null
     let port
     emitter.on('DOMContentLoaded', async () => {
+      browser.runtime.sendMessage({ telemetry: { trackView: 'welcome' } })
       emitter.emit('render')
       port = runtime.connect({ name: 'browser-action-port' })
       port.onMessage.addListener(async (message) => {

add-on/src/lib/ipfs-client/brave.js

@@ -16,39 +16,39 @@ const waitFor = (f, t) => pWaitFor(f, { interval: tickMs, timeout: t || Infinity
 // wrapper for chrome.ipfs.* that gets us closer to ergonomics of promise-based browser.*
 export const brave = hasBraveChromeIpfs()
   ? Object.freeze({
-      // This is the main check - returns true only in Brave and only when
-      // feature flag is enabled brave://flags and can be used for high level UI
-      // decisions such as showing custom node type on Preferences
-      getIPFSEnabled: async () =>
-        Boolean(await promisifyBraveCheck(chrome.ipfs.getIPFSEnabled)),
-
-      // Obtains a string representation of the resolve method
-      // method is one of the following strings:
-      // "ask" uses a gateway but also prompts them to install a local node
-      // "gateway" uses a gateway but also prompts them to install a local node
-      // "local" uses a gateway but also prompts them to install a local node
-      // "disabled" disabled by the user
-      // "undefined" everything else (IPFS feature flag is not enabled, error etc)
-      getResolveMethodType: async () =>
-        String(await promisifyBraveCheck(chrome.ipfs.getResolveMethodType)),
-
-      // Obtains the config contents of the local IPFS node
-      // Returns undefined if missing for any reason
-      getConfig: async () =>
-        await promisifyBraveCheck(chrome.ipfs.getConfig),
-
-      // Returns true if binary is present
-      getExecutableAvailable: async () =>
-        Boolean(await promisifyBraveCheck(chrome.ipfs.getExecutableAvailable)),
-
-      // Attempts to start the daemon and returns true if finished
-      launch: async () =>
-        Boolean(await promisifyBraveCheck(chrome.ipfs.launch)),
-
-      // Attempts to stop the daemon and returns true if finished
-      shutdown: async () =>
-        Boolean(await promisifyBraveCheck(chrome.ipfs.shutdown))
-    })
+    // This is the main check - returns true only in Brave and only when
+    // feature flag is enabled brave://flags and can be used for high level UI
+    // decisions such as showing custom node type on Preferences
+    getIPFSEnabled: async () =>
+      Boolean(await promisifyBraveCheck(chrome.ipfs.getIPFSEnabled)),
+
+    // Obtains a string representation of the resolve method
+    // method is one of the following strings:
+    // "ask" uses a gateway but also prompts them to install a local node
+    // "gateway" uses a gateway but also prompts them to install a local node
+    // "local" uses a gateway but also prompts them to install a local node
+    // "disabled" disabled by the user
+    // "undefined" everything else (IPFS feature flag is not enabled, error etc)
+    getResolveMethodType: async () =>
+      String(await promisifyBraveCheck(chrome.ipfs.getResolveMethodType)),
+
+    // Obtains the config contents of the local IPFS node
+    // Returns undefined if missing for any reason
+    getConfig: async () =>
+      await promisifyBraveCheck(chrome.ipfs.getConfig),
+
+    // Returns true if binary is present
+    getExecutableAvailable: async () =>
+      Boolean(await promisifyBraveCheck(chrome.ipfs.getExecutableAvailable)),
+
+    // Attempts to start the daemon and returns true if finished
+    launch: async () =>
+      Boolean(await promisifyBraveCheck(chrome.ipfs.launch)),
+
+    // Attempts to stop the daemon and returns true if finished
+    shutdown: async () =>
+      Boolean(await promisifyBraveCheck(chrome.ipfs.shutdown))
+  })
   : undefined
 
 export async function init (browser, opts) {

add-on/src/lib/ipfs-companion.js

@@ -23,6 +23,7 @@ import createRuntimeChecks from './runtime-checks.js'
 import { createContextMenus, findValueForContext, contextMenuCopyAddressAtPublicGw, contextMenuCopyRawCid, contextMenuCopyCanonicalAddress, contextMenuViewOnGateway, contextMenuCopyPermalink, contextMenuCopyCidAddress } from './context-menus.js'
 import { registerSubdomainProxy } from './http-proxy.js'
 import { runPendingOnInstallTasks } from './on-installed.js'
+import { handleConsentFromState, startSession, endSession, trackView } from './telemetry.js'
 const log = debug('ipfs-companion:main')
 log.error = debug('ipfs-companion:main:error')
 
@@ -33,6 +34,7 @@ export default async function init () {
   // INIT
   // ===================================================================
   let ipfs // ipfs-api instance
+  /** @type {import('../types.js').CompanionState} */
   let state // avoid redundant API reads by utilizing local cache of various states
   let dnslinkResolver
   let ipfsPathValidator
@@ -55,8 +57,11 @@ export default async function init () {
     runtime = await createRuntimeChecks(browser)
     state = initState(options)
     notify = createNotifier(getState)
+    // ensure consent is set properly on app init
+    handleConsentFromState(state)
 
     if (state.active) {
+      startSession()
       // It's ok for this to fail, node might be unavailable or mis-configured
       try {
         ipfs = await initIpfsClient(browser, state)
@@ -167,6 +172,15 @@ export default async function init () {
       const result = validIpfsOrIpns(path) ? resolveToPublicUrl(path) : null
       return Promise.resolve({ pubGwUrlForIpfsOrIpnsPath: result })
     }
+    if (request.telemetry) {
+      return Promise.resolve(onTelemetryMessage(request.telemetry, sender))
+    }
+  }
+
+  function onTelemetryMessage (request, sender) {
+    if (request.trackView) {
+      return trackView(request.trackView)
+    }
   }
 
   // PORTS (connection-based messaging)
@@ -366,11 +380,11 @@ export default async function init () {
     // https://github.com/ipfs-shipyard/ipfs-companion/issues/398
     if (runtime.isFirefox && ipfsPathValidator.isIpfsPageActionsContext(url)) {
       if (sameGateway(url, state.gwURL) || sameGateway(url, state.apiURL)) {
-        await browser.pageAction.setIcon({ tabId: tabId, path: '/icons/ipfs-logo-on.svg' })
-        await browser.pageAction.setTitle({ tabId: tabId, title: browser.i18n.getMessage('pageAction_titleIpfsAtCustomGateway') })
+        await browser.pageAction.setIcon({ tabId, path: '/icons/ipfs-logo-on.svg' })
+        await browser.pageAction.setTitle({ tabId, title: browser.i18n.getMessage('pageAction_titleIpfsAtCustomGateway') })
       } else {
-        await browser.pageAction.setIcon({ tabId: tabId, path: '/icons/ipfs-logo-off.svg' })
-        await browser.pageAction.setTitle({ tabId: tabId, title: browser.i18n.getMessage('pageAction_titleIpfsAtPublicGateway') })
+        await browser.pageAction.setIcon({ tabId, path: '/icons/ipfs-logo-off.svg' })
+        await browser.pageAction.setTitle({ tabId, title: browser.i18n.getMessage('pageAction_titleIpfsAtPublicGateway') })
       }
       await browser.pageAction.show(tabId)
     }
@@ -554,6 +568,8 @@ export default async function init () {
           await registerSubdomainProxy(getState, runtime)
           shouldRestartIpfsClient = true
           shouldStopIpfsClient = !state.active
+          // Any time the extension switches active state, start or stop the current session.
+          state.active ? startSession() : endSession()
           break
         case 'ipfsNodeType':
           if (change.oldValue !== braveNodeType && change.newValue === braveNodeType) {
@@ -620,6 +636,8 @@ export default async function init () {
           break
       }
     }
+    // ensure consent is set properly on state changes
+    handleConsentFromState(state)
 
     if ((state.active && shouldRestartIpfsClient) || shouldStopIpfsClient) {
       try {

add-on/src/lib/notifier.js

@@ -21,8 +21,8 @@ export default function createNotifier (getState) {
         return await browser.notifications.create({
           type: 'basic',
           iconUrl: browser.runtime.getURL('icons/ipfs-logo-on.svg'),
-          title: title,
-          message: message
+          title,
+          message
         })
       } catch (err) {
         log.error('failed to create a notification', err)

add-on/src/lib/options.js

@@ -1,8 +1,11 @@
 'use strict'
 
-import { isIPv4, isIPv6 } from 'is-ip'
 import isFQDN from 'is-fqdn'
+import { isIPv4, isIPv6 } from 'is-ip'
 
+/**
+ * @type {Readonly<import('../types.js').CompanionOptions>}
+ */
 export const optionDefaults = Object.freeze({
   active: true, // global ON/OFF switch, overrides everything else
   ipfsNodeType: 'external',
@@ -31,7 +34,12 @@ export const optionDefaults = Object.freeze({
   importDir: '/ipfs-companion-imports/%Y-%M-%D_%h%m%s/',
   useLatestWebUI: false,
   dismissedUpdate: null,
-  openViaWebUI: true
+  openViaWebUI: true,
+  telemetryGroupMinimal: true,
+  telemetryGroupPerformance: false,
+  telemetryGroupUx: false,
+  telemetryGroupFeedback: false,
+  telemetryGroupLocation: false
 })
 
 function buildDefaultIpfsNodeConfig () {