Provide entityRef analytics context within TechDocs reader

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

.changeset/techdocs-analyze-entities.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs-react': patch
+---
+
+Analytics events captured within the `<TechDocsReaderPageProvider>` now include the conventional `entityRef` context value, associating those events with their corresponding entity.

plugins/techdocs-react/src/context.test.tsx

@@ -19,9 +19,13 @@ import { renderHook, act } from '@testing-library/react-hooks';
 import { ThemeProvider } from '@material-ui/core';
 
 import { lightTheme } from '@backstage/theme';
-import { TestApiProvider } from '@backstage/test-utils';
+import { MockAnalyticsApi, TestApiProvider } from '@backstage/test-utils';
 import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
-import { configApiRef } from '@backstage/core-plugin-api';
+import {
+  analyticsApiRef,
+  configApiRef,
+  useAnalytics,
+} from '@backstage/core-plugin-api';
 
 import { techdocsApiRef } from './api';
 import { useTechDocsReaderPage, TechDocsReaderPageProvider } from './context';
@@ -60,6 +64,8 @@ const configApiMock = {
   getOptionalBoolean: jest.fn().mockReturnValue(undefined),
 };
 
+const analyticsApiMock = new MockAnalyticsApi();
+
 const wrapper = ({
   entityRef = {
     kind: mockEntityMetadata.kind,
@@ -74,6 +80,7 @@ const wrapper = ({
   <ThemeProvider theme={lightTheme}>
     <TestApiProvider
       apis={[
+        [analyticsApiRef, analyticsApiMock],
         [configApiRef, configApiMock],
         [techdocsApiRef, techdocsApiMock],
       ]}
@@ -86,6 +93,10 @@ const wrapper = ({
 );
 
 describe('useTechDocsReaderPage', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
   it('should set title', async () => {
     const { result, waitForNextUpdate } = renderHook(
       () => useTechDocsReaderPage(),
@@ -157,4 +168,21 @@ describe('useTechDocsReaderPage', () => {
 
     expect(result.current.entityRef).toStrictEqual(caseSensitiveEntityRef);
   });
+
+  it('entityRef provided as analytics context', async () => {
+    const { waitForNextUpdate } = renderHook(
+      () => useAnalytics().captureEvent('action', 'subject'),
+      { wrapper },
+    );
+
+    await waitForNextUpdate();
+
+    expect(analyticsApiMock.getEvents()[0]).toMatchObject({
+      action: 'action',
+      subject: 'subject',
+      context: {
+        entityRef: 'component:default/test',
+      },
+    });
+  });
 });

plugins/techdocs-react/src/context.tsx

@@ -33,7 +33,11 @@ import {
   createVersionedValueMap,
 } from '@backstage/version-bridge';
 
-import { configApiRef, useApi } from '@backstage/core-plugin-api';
+import {
+  AnalyticsContext,
+  configApiRef,
+  useApi,
+} from '@backstage/core-plugin-api';
 
 import { techdocsApiRef } from './api';
 import { TechDocsEntityMetadata, TechDocsMetadata } from './types';
@@ -141,9 +145,13 @@ export const TechDocsReaderPageProvider = memo(
     const versionedValue = createVersionedValueMap({ 1: value });
 
     return (
-      <TechDocsReaderPageContext.Provider value={versionedValue}>
-        {children instanceof Function ? children(value) : children}
-      </TechDocsReaderPageContext.Provider>
+      <AnalyticsContext
+        attributes={{ entityRef: stringifyEntityRef(entityRef) }}
+      >
+        <TechDocsReaderPageContext.Provider value={versionedValue}>
+          {children instanceof Function ? children(value) : children}
+        </TechDocsReaderPageContext.Provider>
+      </AnalyticsContext>
     );
   },
   (prevProps, nextProps) => {