feat: track Segment event to quantify users' preferred color scheme (#444)

This releases intends to begin collecting data on users' preference for light vs. dark color scheme as input and/or validation to the prioritization around supporting a true dark mode for the Open edX platform. That is, we'll be able to quantify what percentage of users would prefer to use a dark mode even though we don't offer one on Open edX.

Author: PKulkoRaccoonGang

package-lock.json

@@ -31,10 +31,11 @@
   },
   "homepage": "https://github.com/openedx/frontend-platform#readme",
   "devDependencies": {
-    "@edx/browserslist-config": "1.1.1",
     "@edx/brand": "npm:@edx/[email protected]",
+    "@edx/browserslist-config": "1.1.1",
     "@edx/frontend-build": "12.4.16",
     "@edx/paragon": "20.28.4",
+    "@testing-library/react-hooks": "^8.0.1",
     "axios-mock-adapter": "1.21.2",
     "core-js": "3.29.0",
     "enzyme": "3.11.0",

package.json

@@ -6,7 +6,7 @@ import OptionalReduxProvider from './OptionalReduxProvider';
 
 import ErrorBoundary from './ErrorBoundary';
 import AppContext from './AppContext';
-import { useAppEvent } from './hooks';
+import { useAppEvent, useTrackColorSchemeChoice } from './hooks';
 import { getAuthenticatedUser, AUTHENTICATED_USER_CHANGED } from '../auth';
 import { getConfig } from '../config';
 import { CONFIG_CHANGED } from '../constants';
@@ -49,6 +49,8 @@ export default function AppProvider({ store, children }) {
   const [authenticatedUser, setAuthenticatedUser] = useState(getAuthenticatedUser());
   const [locale, setLocale] = useState(getLocale());
 
+  useTrackColorSchemeChoice();
+
   useAppEvent(AUTHENTICATED_USER_CHANGED, () => {
     setAuthenticatedUser(getAuthenticatedUser());
   });

src/react/AppProvider.jsx

@@ -18,6 +18,11 @@ jest.mock('../analytics', () => ({
   identifyAuthenticatedUser: jest.fn(),
 }));
 
+jest.mock('./hooks', () => ({
+  ...jest.requireActual('./hooks'),
+  useTrackColorSchemeChoice: jest.fn(),
+}));
+
 describe('AppProvider', () => {
   beforeEach(async () => {
     await initialize({

src/react/AppProvider.test.jsx

@@ -1,6 +1,7 @@
 /* eslint-disable import/prefer-default-export */
 import { useEffect } from 'react';
 import { subscribe, unsubscribe } from '../pubSub';
+import { sendTrackEvent } from '../analytics';
 
 /**
  * A React hook that allows functional components to subscribe to application events.  This should
@@ -21,3 +22,27 @@ export const useAppEvent = (type, callback) => {
     };
   }, [callback, type]);
 };
+
+/**
+ * A React hook that tracks user's preferred color scheme (light or dark) and sends respective
+ * event to the tracking service.
+ *
+ * @memberof module:React
+ */
+export const useTrackColorSchemeChoice = () => {
+  useEffect(() => {
+    const trackColorSchemeChoice = ({ matches }) => {
+      const preferredColorScheme = matches ? 'dark' : 'light';
+
+      sendTrackEvent('openedx.ui.frontend-platform.prefers-color-scheme.selected', { preferredColorScheme });
+    };
+
+    const colorSchemeQuery = window.matchMedia('(prefers-color-scheme: dark)');
+
+    // send user's initial choice
+    trackColorSchemeChoice(colorSchemeQuery);
+
+    colorSchemeQuery.addEventListener('change', trackColorSchemeChoice);
+    return () => colorSchemeQuery.removeEventListener('change', trackColorSchemeChoice);
+  }, []);
+};

src/react/hooks.js

@@ -0,0 +1,51 @@
+import { renderHook } from '@testing-library/react-hooks';
+import { useTrackColorSchemeChoice } from './hooks';
+import { sendTrackEvent } from '../analytics';
+
+jest.mock('../analytics');
+
+const mockAddEventListener = jest.fn();
+let matchesMock;
+
+Object.defineProperty(window, 'matchMedia', {
+  value: jest.fn(() => ({
+    addEventListener: mockAddEventListener,
+    matches: matchesMock,
+  })),
+});
+
+describe('useTrackColorSchemeChoice hook', () => {
+  afterEach(() => {
+    mockAddEventListener.mockClear();
+    sendTrackEvent.mockClear();
+  });
+
+  it('sends dark preferred color schema event if query matches', async () => {
+    matchesMock = true;
+    renderHook(() => useTrackColorSchemeChoice());
+
+    expect(sendTrackEvent).toHaveBeenCalledTimes(1);
+    expect(sendTrackEvent).toHaveBeenCalledWith(
+      'openedx.ui.frontend-platform.prefers-color-scheme.selected',
+      { preferredColorScheme: 'dark' },
+    );
+  });
+
+  it('sends light preferred color schema event if query does not match', async () => {
+    matchesMock = false;
+    renderHook(() => useTrackColorSchemeChoice());
+
+    expect(sendTrackEvent).toHaveBeenCalledTimes(1);
+    expect(sendTrackEvent).toHaveBeenCalledWith(
+      'openedx.ui.frontend-platform.prefers-color-scheme.selected',
+      { preferredColorScheme: 'light' },
+    );
+  });
+
+  it('adds change event listener to matchMedia query', async () => {
+    renderHook(() => useTrackColorSchemeChoice());
+
+    expect(mockAddEventListener).toHaveBeenCalledTimes(1);
+    expect(mockAddEventListener).toHaveBeenCalledWith('change', expect.any(Function));
+  });
+});