diff --git a/packages/design-system-docs/src/pages/components/Button/_Button.docs.scss b/packages/design-system-docs/src/pages/components/Button/_Button.docs.scss index b557ec4b2f..a784ee0d62 100644 --- a/packages/design-system-docs/src/pages/components/Button/_Button.docs.scss +++ b/packages/design-system-docs/src/pages/components/Button/_Button.docs.scss @@ -111,3 +111,32 @@ Style guide: components.button.react Style guide: components.button.guidance */ + +/* +Google Analytics + +**Analytics event tracking is disabled by default.** + +### Enable event tracking + +Import and set the `setButtonSendsAnalytics` feature flag to `true` in your application's entry file: + +```JSX +import { setButtonSendsAnalytics } from "@cmsgov/"; +setButtonSendsAnalytics(true); +``` +On applications where the page has `utag` loaded, the data goes to Tealium which allows it to route to Google Analytics or the currently approved data analytics tools. + +### Disable event tracking + +For the `analytics` prop, pass the value `false` to the component to disable analytics tracking for a singular component instance + +```JSX +analytics={false} +``` +### Override event tracking + +A custom heading value can be sent for an analytics event by using the prop `analyticsLabelOverride`. It is recommended that this value be used to prevent sensitive personal information from being passed to analytics trackers. + +Style guide: components.button.guidance-analytics +*/ diff --git a/packages/design-system/src/components/Button/Button.test.tsx b/packages/design-system/src/components/Button/Button.test.tsx index 69d38dcd49..af8b449bfe 100644 --- a/packages/design-system/src/components/Button/Button.test.tsx +++ b/packages/design-system/src/components/Button/Button.test.tsx @@ -156,6 +156,12 @@ describe('Button', () => { expect(tealiumMock).not.toBeCalled(); }); + it('overrides analytics event tracking on open', () => { + renderButton({ analyticsLabelOverride: 'alternate content' }); + fireEvent.click(screen.getByRole('button')); + expect(tealiumMock.mock.calls[0]).toMatchSnapshot(); + }); + it('passes along parent heading and type', () => { const analyticsParentHeading = 'Hello World'; const analyticsParentType = 'div'; diff --git a/packages/design-system/src/components/Button/Button.tsx b/packages/design-system/src/components/Button/Button.tsx index abbf41c16c..15e6b3281c 100644 --- a/packages/design-system/src/components/Button/Button.tsx +++ b/packages/design-system/src/components/Button/Button.tsx @@ -19,6 +19,12 @@ type CommonButtonProps = { * disable tracking for this component instance. */ analytics?: boolean; + /** + * An override for the dynamic content sent to analytics services. By default this content comes from the heading. + * + * In cases where this component’s heading may contain **sensitive information**, use this prop to override what is sent to analytics. + */ + analyticsLabelOverride?: string; /** * If needed for analytics, pass heading text of parent component of button. */ @@ -93,6 +99,7 @@ export type ButtonProps = CommonButtonProps & OtherProps; export const Button = ({ analytics, + analyticsLabelOverride, analyticsParentHeading, analyticsParentType, children, @@ -162,7 +169,7 @@ export const Button = ({ return; } - const buttonText = getAnalyticsContentFromRefs([contentRef]); + const buttonText = analyticsLabelOverride ?? getAnalyticsContentFromRefs([contentRef]); const buttonStyle = variation ?? 'default'; const buttonType = type ?? 'button'; const buttonParentHeading = analyticsParentHeading ?? ' '; diff --git a/packages/design-system/src/components/Button/__snapshots__/Button.test.tsx.snap b/packages/design-system/src/components/Button/__snapshots__/Button.test.tsx.snap index c764e0abb2..abb9333480 100644 --- a/packages/design-system/src/components/Button/__snapshots__/Button.test.tsx.snap +++ b/packages/design-system/src/components/Button/__snapshots__/Button.test.tsx.snap @@ -1,5 +1,24 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP +exports[`Button Analytics overrides analytics event tracking on open 1`] = ` +Array [ + Object { + "button_style": "default", + "button_type": "button", + "event_name": "button_engagement", + "event_type": "ui interaction", + "ga_eventAction": "engaged default button", + "ga_eventCategory": "ui interaction", + "ga_eventLabel": "alternate content", + "ga_eventType": "cmsds", + "ga_eventValue": "", + "parent_component_heading": " ", + "parent_component_type": " ", + "text": "alternate content", + }, +] +`; + exports[`Button Analytics sends button analytics event 1`] = ` Array [ Object {