refactor: colocate segment events (#2840)

* refactor: segment events refactoring * refactor: alternative refactoring variant for event segments * refactor: some refactoring * refactor: refactoring after review * refactor: refactoring after review * refactor: refactoring after review * refactor: corrected settings changed event * refactor: added segment constant for component generator
openedx · Dec 22, 2023 · e3a34e1 · e3a34e1
1 parent de070d2
commit e3a34e1
Show file tree

Hide file tree

Showing 14 changed files with 105 additions and 33 deletions.
diff --git a/www/netlify/functions/trackGenerateComponent.js b/www/netlify/functions/trackGenerateComponent.js
@@ -1,5 +1,6 @@
 const { v4: uuidv4 } = require('uuid');
 const Analytics = require('analytics-node');
+const { COMPONENT_GENERATED_EVENT } = require('../../segment-events');
 
 const analytics = new Analytics(process.env.SEGMENT_KEY);
 
@@ -12,7 +13,7 @@ exports.handler = async function eventHandler(event) {
   // dispatch event to Segment
   analytics.track({
     anonymousId: uuidv4(),
-    event: 'openedx.paragon.functions.track-generate-component.created',
+    event: COMPONENT_GENERATED_EVENT,
     properties: { componentName },
   });
 

diff --git a/www/segment-events/constants.js b/www/segment-events/constants.js
@@ -0,0 +1,44 @@
+/**
+ * Events are identified by the following structured pattern:
+ * openedx.paragon.event_environment.event_name.event_action
+ */
+
+export const ICON_COPIED_EVENT = 'openedx.paragon.docs.icons-table.selected-icon.copied';
+export const LEAVE_FEEDBACK_CLICKED_EVENT = 'openedx.paragon.docs.leave-feedback.clicked';
+export const CONTRAST_CHECKER_CLICKED_EVENT = 'openedx.paragon.docs.menu.tools.visit-contrast-checker.clicked';
+export const PAGE_EDIT_BTN_CLICKED_EVENT = 'openedx.paragon.docs.page-edit.clicked';
+export const COMPONENT_GENERATED_EVENT = 'openedx.paragon.functions.track-generate-component.created';
+
+export const PLAYGROUND_EVENTS = {
+  LINK_CLICKED: 'openedx.paragon.docs.menu.playground.visit-playground.clicked',
+  URL_COPIED: 'openedx.paragon.docs.playground.copy-url.copied',
+};
+
+export const SHADOW_GENERATOR_LAYER_EVENTS = {
+  ENABLED: 'openedx.paragon.docs.elevation.shadow-generator.layer.enabled',
+  DISABLED: 'openedx.paragon.docs.elevation.shadow-generator.layer.disabled',
+  REMOVED: 'openedx.paragon.docs.elevation.shadow-generator.layer.removed',
+  ADDED: 'openedx.paragon.docs.elevation.shadow-generator.layer.added',
+  UPDATED: 'openedx.paragon.docs.elevation.shadow-generator.layer.updated',
+};
+
+export const SETTINGS_EVENTS = {
+  OPENED: 'openedx.paragon.docs.settings.opened',
+  CLOSED: 'openedx.paragon.docs.settings.closed',
+  CHANGED: 'openedx.paragon.docs.setting.changed',
+};
+
+export const EXAMPLE_CODE_BLOCK_WITH_HEADING_EVENTS = {
+  CLOSED: 'openedx.paragon.docs.example-code-block.closed',
+  OPENED: 'openedx.paragon.docs.example-code-block.opened',
+};
+
+export const EXAMPLE_CODE_BLOCK_WITHOUT_HEADING_EVENTS = {
+  CLOSED: 'openedx.paragon.docs.example-code-block.without-heading.closed',
+  OPENED: 'openedx.paragon.docs.example-code-block.without-heading.opened',
+};
+
+export const USAGE_INSIGHTS_EVENTS = {
+  TAB_CLICKED: 'openedx.paragon.docs.usage-insights.tab.clicked',
+  COMPONENT_LINK_CLICKED: 'openedx.paragon.docs.usage-insights.component-usage-link.clicked',
+};
diff --git a/www/segment-events/index.js b/www/segment-events/index.js
@@ -0,0 +1,3 @@
+export * from './constants';
+
+export { sendUserAnalyticsEvent } from './utils';
diff --git a/www/segment-events/utils.js b/www/segment-events/utils.js
@@ -0,0 +1,8 @@
+function sendUserAnalyticsEvent(eventName, context) {
+  if (context) {
+    return global.analytics.track(eventName, context);
+  }
+  return global.analytics.track(eventName);
+}
+
+module.exports = { sendUserAnalyticsEvent };
diff --git a/www/src/components/CodeBlock.tsx b/www/src/components/CodeBlock.tsx
@@ -21,6 +21,11 @@ import { FormattedMessage, useIntl } from 'react-intl';
 import * as ParagonReact from '~paragon-react';
 import * as ParagonIcons from '~paragon-icons';
 import { ContentCopy } from '~paragon-icons';
+import {
+  EXAMPLE_CODE_BLOCK_WITH_HEADING_EVENTS,
+  EXAMPLE_CODE_BLOCK_WITHOUT_HEADING_EVENTS,
+  sendUserAnalyticsEvent,
+} from '../../segment-events';
 import MiyazakiCard from './exampleComponents/MiyazakiCard';
 import HipsterIpsum from './exampleComponents/HipsterIpsum';
 import ExamplePropsForm from './exampleComponents/ExamplePropsForm';
@@ -64,16 +69,19 @@ function CollapsibleLiveEditor({ children, clickToCopy, handleCodeChange }: Coll
     const headingElement = getCodeBlockHeading(e.target);
 
     if (!headingElement) {
-      global.analytics.track(`openedx.paragon.docs.ui.example-code-block.${collapseIsOpen ? 'closed' : 'opened'}`, {
-        value: `${componentNameAndCategory}id-not-generated`,
-      });
+      const event = collapseIsOpen
+        ? EXAMPLE_CODE_BLOCK_WITHOUT_HEADING_EVENTS.CLOSED
+        : EXAMPLE_CODE_BLOCK_WITHOUT_HEADING_EVENTS.OPENED;
 
+      sendUserAnalyticsEvent(event, { value: `${componentNameAndCategory}id-not-generated` });
       return;
     }
 
-    global.analytics.track(`openedx.paragon.docs.ui.example-code-block.${collapseIsOpen ? 'closed' : 'opened'}`, {
-      value: `${componentNameAndCategory}${headingElement.id}`,
-    });
+    const event = collapseIsOpen
+      ? EXAMPLE_CODE_BLOCK_WITH_HEADING_EVENTS.CLOSED
+      : EXAMPLE_CODE_BLOCK_WITH_HEADING_EVENTS.OPENED;
+
+    sendUserAnalyticsEvent(event, { value: `${componentNameAndCategory}${headingElement.id}` });
   };
 
   return (

diff --git a/www/src/components/IconsTable.tsx b/www/src/components/IconsTable.tsx
@@ -3,6 +3,7 @@ import PropTypes from 'prop-types';
 import debounce from 'lodash.debounce';
 import { Icon, SearchField, Toast } from '~paragon-react';
 import * as IconComponents from '~paragon-icons';
+import { ICON_COPIED_EVENT, sendUserAnalyticsEvent } from '../../segment-events';
 
 const WINDOW_HEIGHT = 2400;
 const ROW_HEIGHT = 100;
@@ -75,7 +76,7 @@ function IconsTable({ iconNames }) {
   const copyToClipboard = (content) => {
     navigator.clipboard.writeText(content);
     setShowToast(true);
-    global.analytics.track('openedx.paragon.docs.icons-table.selected-icon.copied', { name: currentIcon });
+    sendUserAnalyticsEvent(ICON_COPIED_EVENT, { name: currentIcon });
   };
 
   const handleChangeSearchValue = useMemo(() => debounce(setSearchValue, 500, { leading: false }), []);

diff --git a/www/src/components/LeaveFeedback.tsx b/www/src/components/LeaveFeedback.tsx
@@ -2,6 +2,7 @@ import React, { AnchorHTMLAttributes } from 'react';
 import PropTypes from 'prop-types';
 import { Nav, Button, Hyperlink } from '~paragon-react';
 import { useLocation } from '@reach/router';
+import { LEAVE_FEEDBACK_CLICKED_EVENT, sendUserAnalyticsEvent } from '../../segment-events';
 
 export interface LeaveFeedbackProps extends Partial<AnchorHTMLAttributes<HTMLAnchorElement>> {
   isNavLink?: boolean;
@@ -12,9 +13,7 @@ function LeaveFeedback({ isNavLink, ...props }: LeaveFeedbackProps) {
   const FEEDBACK_URL = `https://github.com/openedx/paragon/issues/new?title=%5Bparagon-openedx.netlify.app%5D%20Feedback%20(on%20${location.pathname})&amp;labels=docs&template=feedback_template.md`;
   const leaveFeedbackLinkTitle = 'Leave feedback';
 
-  const handleLinkFeedbackClick = () => {
-    global.analytics.track('openedx.paragon.docs.leave_feedback.clicked');
-  };
+  const handleLinkFeedbackClick = () => sendUserAnalyticsEvent(LEAVE_FEEDBACK_CLICKED_EVENT);
 
   if (isNavLink) {
     return (

diff --git a/www/src/components/Menu.tsx b/www/src/components/Menu.tsx
@@ -16,6 +16,11 @@ import classNames from 'classnames';
 import Search from './Search';
 import { SettingsContext } from '../context/SettingsContext';
 import { THEMES } from '../../theme-config';
+import {
+  PLAYGROUND_EVENTS,
+  sendUserAnalyticsEvent,
+  CONTRAST_CHECKER_CLICKED_EVENT,
+} from '../../segment-events';
 import { FOUNDATION_PAGES } from '../config';
 
 // MDX transforms markdown generated by gatsby-transformer-react-docgen
@@ -145,13 +150,9 @@ function MenuComponentListCategory({ children, title }: IMenuComponentListCatego
   );
 }
 
-const handlePlaygroundClick = () => {
-  global.analytics.track('openedx.paragon.docs.menu.playground.visit_playground.clicked');
-};
+const handlePlaygroundClick = () => sendUserAnalyticsEvent(PLAYGROUND_EVENTS.LINK_CLICKED);
 
-const handleContrastCheckerClick = () => {
-  global.analytics.track('openedx.paragon.docs.menu.tools.visit_contrast_checker.clicked');
-};
+const handleContrastCheckerClick = () => sendUserAnalyticsEvent(CONTRAST_CHECKER_CLICKED_EVENT);
 
 MenuComponentListCategory.propTypes = {
   children: PropTypes.node.isRequired,

diff --git a/www/src/components/PageEditBtn/index.tsx b/www/src/components/PageEditBtn/index.tsx
@@ -1,6 +1,7 @@
 import React, { AnchorHTMLAttributes } from 'react';
 import PropTypes from 'prop-types';
 import { Button, Hyperlink, Nav } from '~paragon-react';
+import { PAGE_EDIT_BTN_CLICKED_EVENT, sendUserAnalyticsEvent } from '../../../segment-events';
 
 export interface PageEditBtnProps extends Partial<AnchorHTMLAttributes<HTMLAnchorElement>> {
   githubEditPath?: string,
@@ -10,9 +11,7 @@ export interface PageEditBtnProps extends Partial<AnchorHTMLAttributes<HTMLAncho
 function PageEditBtn({ githubEditPath, isNavLink, ...props }: PageEditBtnProps) {
   const pageEditLinkTitle = 'Edit this page';
 
-  const handlePageEditBtnClick = () => {
-    global.analytics.track('openedx.paragon.docs.page_edit.clicked');
-  };
+  const handlePageEditBtnClick = () => sendUserAnalyticsEvent(PAGE_EDIT_BTN_CLICKED_EVENT);
 
   if (isNavLink) {
     return (

diff --git a/www/src/components/insights/UsagesList.tsx b/www/src/components/insights/UsagesList.tsx
@@ -1,6 +1,7 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import { Hyperlink } from '~paragon-react';
+import { USAGE_INSIGHTS_EVENTS, sendUserAnalyticsEvent } from '../../../segment-events';
 
 type UsagesType = {
   filePath: string,
@@ -21,10 +22,9 @@ export default function UsagesList({
   projectName,
 } : UsagesListPropTypes) {
   const handleUsageLinkClick = (linkToUsage) => {
-    global.analytics.track(
-      'openedx.paragon.docs.usage-insights.component-usage-link.clicked',
-      { project: projectName, component: componentName, linkToUsage },
-    );
+    sendUserAnalyticsEvent(USAGE_INSIGHTS_EVENTS.COMPONENT_LINK_CLICKED, {
+      project: projectName, component: componentName, linkToUsage,
+    });
   };
 
   return (

diff --git a/www/src/context/SettingsContext.tsx b/www/src/context/SettingsContext.tsx
@@ -5,6 +5,7 @@ import { IntlProvider } from 'react-intl';
 import { messages } from '~paragon-react';
 
 import { THEMES, DEFAULT_THEME } from '../../theme-config';
+import { SETTINGS_EVENTS, sendUserAnalyticsEvent } from '../../segment-events';
 
 export interface IDefaultValue {
   settings: {
@@ -44,12 +45,16 @@ function SettingsContextProvider({ children }) {
     }
     setSettings(prevState => ({ ...prevState, [key]: value }));
     global.localStorage.setItem('pgn__settings', JSON.stringify({ ...settings, [key]: value }));
-    global.analytics.track(`openedx.paragon.docs.settings.${key}.changed`, { [key]: value });
+    sendUserAnalyticsEvent(SETTINGS_EVENTS.CHANGED, { setting: key, value });
   };
 
   const toggleSettings = (value: boolean) => {
+    const event = value
+      ? SETTINGS_EVENTS.OPENED
+      : SETTINGS_EVENTS.CLOSED;
+
     setShowSettings(value);
-    global.analytics.track(`openedx.paragon.docs.settings.${value ? 'opened' : 'closed'}`);
+    sendUserAnalyticsEvent(event);
   };
 
   // this hook will be called after the first render, so we can safely access localStorage

diff --git a/www/src/pages/foundations/elevation.jsx b/www/src/pages/foundations/elevation.jsx
@@ -13,6 +13,7 @@ import { Close, WbSunny, DoDisturb } from '~paragon-icons';
 import SEO from '../../components/SEO';
 import Layout from '../../components/PageLayout';
 import { SettingsContext } from '../../context/SettingsContext';
+import { sendUserAnalyticsEvent, SHADOW_GENERATOR_LAYER_EVENTS } from '../../../segment-events';
 
 const boxShadowSides = ['down', 'up', 'right', 'left', 'centered'];
 const boxShadowLevels = [1, 2, 3, 4, 5];
@@ -86,7 +87,7 @@ function BoxShadowToolkit({
   });
 
   const updateBoxShadowModel = (property, value) => {
-    global.analytics.track('openedx.paragon.docs.elevation.generator.updated', { property, value });
+    sendUserAnalyticsEvent(SHADOW_GENERATOR_LAYER_EVENTS.UPDATED, { property, value });
 
     const newBoxShadowModel = {
       ...boxShadowModel,
@@ -196,20 +197,20 @@ function BoxShadowGenerator() {
   };
 
   const addNewBoxShadowLayer = () => {
-    global.analytics.track('openedx.paragon.elevation.generator.layer.added');
+    sendUserAnalyticsEvent(SHADOW_GENERATOR_LAYER_EVENTS.ADDED);
     setBoxShadows([
       ...boxShadows,
       { id: boxShadows[boxShadows.length - 1].id + 1, enabled: true, style: DEFAULT_BOX_SHADOW },
     ]);
   };
 
   const removeBoxShadowLayer = (toolkitId) => {
-    global.analytics.track('openedx.paragon.elevation.shadow-generator.layer.removed');
+    sendUserAnalyticsEvent(SHADOW_GENERATOR_LAYER_EVENTS.REMOVED);
     setBoxShadows(boxShadows.filter((shadow) => shadow.id !== toolkitId));
   };
 
   const disableBoxShadowLayer = (toolkitId) => {
-    global.analytics.track('openedx.paragon.elevation.shadow-generator.layer.disabled');
+    sendUserAnalyticsEvent(SHADOW_GENERATOR_LAYER_EVENTS.DISABLED);
     const updatedBoxShadows = boxShadows
       .map((shadow) => {
         if (shadow.id === toolkitId) {
@@ -221,7 +222,7 @@ function BoxShadowGenerator() {
   };
 
   const enableBoxShadowLayer = (toolkitId) => {
-    global.analytics.track('openedx.paragon.elevation.shadow-generator.layer.enabled');
+    sendUserAnalyticsEvent(SHADOW_GENERATOR_LAYER_EVENTS.ENABLED);
     const updatedBoxShadows = boxShadows
       .map((shadow) => {
         if (shadow.id === toolkitId) {

diff --git a/www/src/pages/insights.tsx b/www/src/pages/insights.tsx
@@ -18,6 +18,7 @@ import ComponentsUsage from '../components/insights/ComponentsUsage';
 
 // @ts-ignore
 import dependentProjectsAnalysis from '../../../dependent-usage.json'; // eslint-disable-line
+import { sendUserAnalyticsEvent, USAGE_INSIGHTS_EVENTS } from '../../segment-events';
 import { INSIGHTS_TABS, INSIGHTS_PAGES } from '../config';
 import componentsUsage from '../utils/componentsUsage';
 import { IInsightsContext } from '../types/types';
@@ -63,7 +64,7 @@ export default function InsightsPage({ pageContext: { tab, githubEditPath } }: I
 
   const handleOnSelect = (value: string) => {
     if (value !== tab) {
-      global.analytics.track(`openedx.paragon.docs.insights.tabs.${value.toLowerCase().trim()}.clicked`);
+      sendUserAnalyticsEvent(USAGE_INSIGHTS_EVENTS.TAB_CLICKED, { tabName: value });
       navigate(INSIGHTS_PAGES.find(item => item.tab === value).path);
     }
   };

diff --git a/www/src/pages/playground.tsx b/www/src/pages/playground.tsx
@@ -14,6 +14,7 @@ import localforage from 'localforage';
 import SEO from '../components/SEO';
 import { SiteTitle } from '../components/header';
 import { storageKey } from '../../playroom/constants';
+import { PLAYGROUND_EVENTS, sendUserAnalyticsEvent } from '../../segment-events';
 
 const FEEDBACK_URL = 'https://github.com/openedx/paragon/issues/new?assignees=&labels=playground&template=feedback_template.md&title=[Playground]';
 
@@ -73,7 +74,7 @@ export default function Playground({ location }) {
             onClick={() => {
               setCopyUrlState('copied');
               navigator.clipboard.writeText(location.href);
-              global.analytics.track('openedx.paragon.docs.playground.url-copied');
+              sendUserAnalyticsEvent(PLAYGROUND_EVENTS.URL_COPIED);
             }}
             labels={{
               default: 'Copy URL',