feat: Page tagging (#114)

Author: limhjgrace

app/page_event.html

@@ -71,6 +71,13 @@
                 cwr('recordPageView', '/page_view_two');
             }
 
+            function recordPageViewWithPageAttributes() {
+                cwr('recordPageView', {
+                    pageId: '/page_view_two',
+                    pageTags: ['pageGroup1']
+                });
+            }
+
             const parseEvents = () => {
                 const requestBody = document.getElementById('request_body');
                 const events = JSON.parse(requestBody.innerText).batch.events;
@@ -145,6 +152,12 @@
         <button id="recordPageView" onclick="recordPageView()">
             Record Page View
         </button>
+        <button
+            id="recordPageViewWithPageAttributes"
+            onclick="recordPageViewWithPageAttributes()"
+        >
+            Record Page View with page attributes
+        </button>
         <button id="doNotRecordPageView" onclick="doNotRecordPageView()">
             Do Not Record Page View
         </button>

src/CommandQueue.ts

@@ -38,7 +38,7 @@ export class CommandQueue {
         ): void => {
             this.orchestration.setAwsCredentials(payload);
         },
-        recordPageView: (payload: string): void => {
+        recordPageView: (payload: any): void => {
             this.orchestration.recordPageView(payload);
         },
         recordError: (payload: any): void => {

src/__tests__/CommandQueue.test.ts

@@ -259,7 +259,7 @@ describe('CommandQueue tests', () => {
         const cq: CommandQueue = getCommandQueue();
         await cq.push({
             c: 'recordPageView',
-            p: 'page1'
+            p: '/console/home'
         });
         expect(Orchestration).toHaveBeenCalled();
         expect(recordPageView).toHaveBeenCalled();

src/event-cache/EventCache.ts

@@ -2,7 +2,7 @@ import { Session, SessionManager } from '../sessions/SessionManager';
 import { v4 } from 'uuid';
 import { MetaData } from '../events/meta-data';
 import { Config } from '../orchestration/Orchestration';
-import { PageManager } from '../sessions/PageManager';
+import { PageAttributes, PageManager } from '../sessions/PageManager';
 import {
     AppMonitorDetails,
     UserDetails,
@@ -65,9 +65,9 @@ export class EventCache {
     /**
      * Update the current page interaction for the session.
      */
-    public recordPageView = (pageId: string) => {
+    public recordPageView = (payload: string | PageAttributes) => {
         if (this.isCurrentUrlAllowed()) {
-            this.pageManager.recordPageView(pageId);
+            this.pageManager.recordPageView(payload);
         }
     };
 

src/event-cache/__tests__/EventCache.test.ts

@@ -226,6 +226,35 @@ describe('EventCache tests', () => {
         );
     });
 
+    test('when page is recorded with page tags provided, event metadata records the page tag data', async () => {
+        // Init
+        const EVENT1_SCHEMA = 'com.amazon.rum.page_view_event';
+        const eventCache: EventCache = Utils.createEventCache({
+            ...DEFAULT_CONFIG
+        });
+        const expectedEvents: RumEvent[] = [
+            {
+                id: expect.stringMatching(/[0-9a-f\-]+/),
+                timestamp: new Date(),
+                type: EVENT1_SCHEMA,
+                metadata:
+                    '{"version":"1.0.0","title":"","pageId":"/rum/home","pageTags":["pageGroup1"]}',
+                details: '{"version":"1.0.0","pageId":"/rum/home"}'
+            }
+        ];
+
+        // Run
+        eventCache.recordPageView({
+            pageId: '/rum/home',
+            pageTags: ['pageGroup1']
+        });
+
+        // Assert
+        expect(await eventCache.getEventBatch()).toEqual(
+            expect.arrayContaining(expectedEvents)
+        );
+    });
+
     test('when page matches both allowed and denied, recordEvent does not record the event', async () => {
         // Init
         const EVENT1_SCHEMA = 'com.amazon.rum.event1';

src/event-schemas/meta-data.json

@@ -62,7 +62,8 @@
         },
         "domain": {
             "type": "string"
-        }
+        },
+        "pageTags": { "type": "array", "items": { "type": "string" } }
     },
     "additionalProperties": false,
     "required": ["version", "domain"]

src/orchestration/Orchestration.ts

@@ -20,6 +20,7 @@ import { WebVitalsPlugin } from '../plugins/event-plugins/WebVitalsPlugin';
 import { XhrPlugin } from '../plugins/event-plugins/XhrPlugin';
 import { FetchPlugin } from '../plugins/event-plugins/FetchPlugin';
 import { PageViewPlugin } from '../plugins/event-plugins/PageViewPlugin';
+import { PageAttributes } from '../sessions/PageManager';
 
 const DATA_PLANE_REGION_PLACEHOLDER = '${REGION}';
 const DATA_PLANE_DEFAULT_ENDPOINT =
@@ -284,10 +285,12 @@ export class Orchestration {
 
     /**
      * Update the current page the user is interacting with.
-     * @param pageId The unique ID for the page within the application.
+     * @param payload Can be string or PageAttributes object
+     *      If string, payload is pageId (The unique ID for the page within the application).
+     *      If PageAttributes, payload contains pageId as well as page attributes to include in events with pageId
      */
-    public recordPageView(pageId: string) {
-        this.eventCache.recordPageView(pageId);
+    public recordPageView(payload: string | PageAttributes) {
+        this.eventCache.recordPageView(payload);
     }
 
     /**

src/orchestration/__tests__/Orchestration.test.ts

@@ -19,11 +19,13 @@ jest.mock('../../dispatch/Dispatch', () => ({
 
 const enableEventCache = jest.fn();
 const disableEventCache = jest.fn();
+const recordPageView = jest.fn();
 
 jest.mock('../../event-cache/EventCache', () => ({
     EventCache: jest.fn().mockImplementation(() => ({
         enable: enableEventCache,
-        disable: disableEventCache
+        disable: disableEventCache,
+        recordPageView: recordPageView
     }))
 }));
 
@@ -353,4 +355,23 @@ describe('Orchestration tests', () => {
 
         expect(actual).toEqual(expected);
     });
+
+    test('when the page is manually recorded with pageTag attribute then EventCache.recordPageView() is called', async () => {
+        // Init
+        const orchestration = new Orchestration('a', 'c', 'us-east-1', {});
+
+        const expected = {
+            pageId: '/rum/home',
+            pageTags: ['pageGroup1']
+        };
+        orchestration.recordPageView(expected);
+
+        let actual;
+
+        // Assert
+        expect(recordPageView).toHaveBeenCalledTimes(1);
+        actual = recordPageView.mock.calls[0][0];
+
+        expect(actual).toEqual(expected);
+    });
 });

src/sessions/PageManager.ts

@@ -16,6 +16,12 @@ export type Attributes = {
     pageId: string;
     parentPageId?: string;
     interaction?: number;
+    pageTags?: string[];
+};
+
+export type PageAttributes = {
+    pageId: string;
+    pageTags?: string[];
 };
 
 /**
@@ -68,7 +74,14 @@ export class PageManager {
         };
     }
 
-    public recordPageView(pageId: string) {
+    public recordPageView(payload: string | PageAttributes) {
+        let pageId;
+        if (typeof payload === 'string') {
+            pageId = payload;
+        } else {
+            pageId = payload.pageId;
+        }
+
         if (this.useCookies()) {
             this.recordInteraction = true;
         }
@@ -85,7 +98,9 @@ export class PageManager {
         }
 
         // Attributes will be added to all events as meta data
-        this.collectAttributes();
+        this.collectAttributes(
+            typeof payload === 'object' ? payload : undefined
+        );
 
         // The SessionManager will update its cookie with the new page
         this.recordPageViewEvent();
@@ -118,7 +133,7 @@ export class PageManager {
         };
     }
 
-    private collectAttributes() {
+    private collectAttributes(customPageAttributes?: PageAttributes) {
         this.attributes = {
             title: document.title,
             pageId: this.page.pageId
@@ -130,6 +145,12 @@ export class PageManager {
                 this.attributes.parentPageId = this.page.parentPageId;
             }
         }
+
+        if (customPageAttributes) {
+            Object.keys(customPageAttributes).forEach((attribute) => {
+                this.attributes[attribute] = customPageAttributes[attribute];
+            });
+        }
     }
 
     private createPageViewEvent() {

src/sessions/__integ__/PageManager.test.ts

@@ -2,6 +2,9 @@ import { Selector } from 'testcafe';
 import { REQUEST_BODY } from '../../test-utils/integ-test-utils';
 
 const recordPageView: Selector = Selector(`#recordPageView`);
+const recordPageViewWithPageAttributes: Selector = Selector(
+    `#recordPageViewWithPageAttributes`
+);
 const dispatch: Selector = Selector(`#dispatch`);
 const clear: Selector = Selector(`#clearRequestResponse`);
 const doNotRecordPageView = Selector(`#doNotRecordPageView`);
@@ -115,3 +118,44 @@ test('when page is denied then page view is not recorded', async (t: TestControl
         pageInteractionId: '/page_view_two-1'
     });
 });
+
+test('when pageTag attribute is passed in when manually recording page view event, then PageViewEventPlugin records pageTag data in metadata', async (t: TestController) => {
+    // If we click too soon, the client/event collector plugin will not be loaded and will not record the click.
+    // This could be a symptom of an issue with RUM web client load speed, or prioritization of script execution.
+
+    await t
+        .wait(300)
+        .click(dispatch)
+        .expect(REQUEST_BODY.textContent)
+        .contains('BatchId')
+        .click(clear)
+        .click(recordPageViewWithPageAttributes)
+        .click(dispatch)
+        .expect(REQUEST_BODY.textContent)
+        .contains('BatchId');
+
+    const json = removeUnwantedEvents(
+        JSON.parse(await REQUEST_BODY.textContent)
+    );
+    const eventType = json.RumEvents[0].type;
+    const eventDetails = JSON.parse(json.RumEvents[0].details);
+    const metaData = JSON.parse(json.RumEvents[0].metadata);
+
+    await t
+        .expect(eventType)
+        .eql('com.amazon.rum.page_view_event')
+        .expect(eventDetails)
+        .contains({
+            pageId: '/page_view_two',
+            interaction: 1,
+            pageInteractionId: '/page_view_two-1',
+            parentPageInteractionId: '/page_event.html-0'
+        })
+        .expect(metaData)
+        .contains({
+            pageId: '/page_view_two',
+            title: 'RUM Integ Test'
+        })
+        .expect(metaData.pageTags[0])
+        .eql('pageGroup1');
+});