feat: update auto tracking plugin

packages/plugin-auto-tracking-browser/jest.config.js

@@ -7,4 +7,6 @@ module.exports = {
   rootDir: '.',
   testEnvironment: 'jsdom',
   coveragePathIgnorePatterns: ['index.ts'],
-};
+  setupFiles: ['./test/setup.ts'],
+};
+

packages/plugin-auto-tracking-browser/package.json

@@ -46,6 +46,7 @@
     "@rollup/plugin-commonjs": "^23.0.4",
     "@rollup/plugin-node-resolve": "^15.0.1",
     "@rollup/plugin-typescript": "^10.0.1",
+    "css.escape": "^1.5.1",
     "rollup": "^2.79.1",
     "rollup-plugin-execute": "^1.1.1",
     "rollup-plugin-gzip": "^3.1.0",

packages/plugin-auto-tracking-browser/src/auto-tracking-plugin.ts

@@ -1,12 +1,15 @@
 /* eslint-disable no-restricted-globals */
 import { BrowserClient, BrowserConfig, EnrichmentPlugin } from '@amplitude/analytics-types';
 import * as constants from './constants';
-import { getText } from './helpers';
+import { getText, isPageUrlAllowed, getAttributesWithPrefix, removeEmptyProperties } from './helpers';
+import { finder } from './libs/finder';
 
 type BrowserEnrichmentPlugin = EnrichmentPlugin<BrowserClient, BrowserConfig>;
 type ActionType = 'click' | 'change';
+type AllowedTag = 'a' | 'button' | 'input' | 'select' | 'textarea' | 'label';
 
 const DEFAULT_TAG_ALLOWLIST = ['a', 'button', 'input', 'select', 'textarea', 'label'];
+const DEFAULT_DATA_ATTRIBUTE_PREFIX = 'data-amp-auto-track-';
 
 interface EventListener {
   element: Element;
@@ -15,12 +18,21 @@ interface EventListener {
 }
 
 interface Options {
+  tagAllowlist?: AllowedTag[];
   cssSelectorAllowlist?: string[];
-  tagAllowlist?: string[];
+  pageUrlAllowlist?: string[];
+  shouldTrackEventCallback?: (actionType: ActionType, element: Element) => boolean;
+  dataAttributePrefix?: string;
 }
 
 export const autoTrackingPlugin = (options: Options = {}): BrowserEnrichmentPlugin => {
-  const { tagAllowlist = DEFAULT_TAG_ALLOWLIST, cssSelectorAllowlist } = options;
+  const {
+    tagAllowlist = DEFAULT_TAG_ALLOWLIST,
+    cssSelectorAllowlist,
+    pageUrlAllowlist,
+    shouldTrackEventCallback,
+    dataAttributePrefix = DEFAULT_DATA_ATTRIBUTE_PREFIX,
+  } = options;
   const name = constants.PLUGIN_NAME;
   const type = 'enrichment';
 
@@ -52,6 +64,15 @@ export const autoTrackingPlugin = (options: Options = {}): BrowserEnrichmentPlug
     if (!element) {
       return false;
     }
+
+    if (shouldTrackEventCallback) {
+      return shouldTrackEventCallback(actionType, element);
+    }
+
+    if (!isPageUrlAllowed(window.location.href, pageUrlAllowlist)) {
+      return false;
+    }
+
     /* istanbul ignore next */
     const elementType = (element as HTMLInputElement)?.type || '';
     if (typeof elementType === 'string') {
@@ -62,9 +83,11 @@ export const autoTrackingPlugin = (options: Options = {}): BrowserEnrichmentPlug
           return false;
       }
     }
-    const tag = element.tagName.toLowerCase();
+    /* istanbul ignore next */
+    const tag = element?.tagName?.toLowerCase?.();
     /* istanbul ignore if */
-    if (!tagAllowlist.includes(tag)) {
+    if (!DEFAULT_TAG_ALLOWLIST.includes(tag) || !tagAllowlist.includes(tag)) {
+      // Tag needs to be in the default allowlist and the user provided allowlist.
       return false;
     }
     if (cssSelectorAllowlist) {
@@ -95,6 +118,9 @@ export const autoTrackingPlugin = (options: Options = {}): BrowserEnrichmentPlug
     /* istanbul ignore next */
     const rect =
       typeof element.getBoundingClientRect === 'function' ? element.getBoundingClientRect() : { left: null, top: null };
+    const ariaLabel = element.getAttribute('aria-label');
+    const attributes = getAttributesWithPrefix(element, dataAttributePrefix);
+    const selector = finder(element);
     /* istanbul ignore next */
     const properties: Record<string, any> = {
       [constants.AMPLITUDE_EVENT_PROP_ELEMENT_ID]: element.id,
@@ -103,6 +129,9 @@ export const autoTrackingPlugin = (options: Options = {}): BrowserEnrichmentPlug
       [constants.AMPLITUDE_EVENT_PROP_ELEMENT_TEXT]: getText(element),
       [constants.AMPLITUDE_EVENT_PROP_ELEMENT_POSITION_LEFT]: rect.left == null ? null : Math.round(rect.left),
       [constants.AMPLITUDE_EVENT_PROP_ELEMENT_POSITION_TOP]: rect.top == null ? null : Math.round(rect.top),
+      [constants.AMPLITUDE_EVENT_PROP_ELEMENT_ARIA_LABEL]: ariaLabel,
+      [constants.AMPLITUDE_EVENT_PROP_ELEMENT_ATTRIBUTES]: attributes,
+      [constants.AMPLITUDE_EVENT_PROP_ELEMENT_SELECTOR]: selector,
       [constants.AMPLITUDE_EVENT_PROP_PAGE_URL]: window.location.href.split('?')[0],
       [constants.AMPLITUDE_EVENT_PROP_PAGE_TITLE]: (typeof document !== 'undefined' && document.title) || '',
       [constants.AMPLITUDE_EVENT_PROP_VIEWPORT_HEIGHT]: window.innerHeight,
@@ -111,7 +140,7 @@ export const autoTrackingPlugin = (options: Options = {}): BrowserEnrichmentPlug
     if (tag === 'a' && actionType === 'click' && element instanceof HTMLAnchorElement) {
       properties[constants.AMPLITUDE_EVENT_PROP_ELEMENT_HREF] = element.href;
     }
-    return properties;
+    return removeEmptyProperties(properties);
   };
 
   const setup: BrowserEnrichmentPlugin['setup'] = async (config, amplitude) => {

packages/plugin-auto-tracking-browser/src/constants.ts

@@ -10,6 +10,9 @@ export const AMPLITUDE_EVENT_PROP_ELEMENT_TEXT = '[Amplitude] Element Text';
 export const AMPLITUDE_EVENT_PROP_ELEMENT_HREF = '[Amplitude] Element Href';
 export const AMPLITUDE_EVENT_PROP_ELEMENT_POSITION_LEFT = '[Amplitude] Element Position Left';
 export const AMPLITUDE_EVENT_PROP_ELEMENT_POSITION_TOP = '[Amplitude] Element Position Top';
+export const AMPLITUDE_EVENT_PROP_ELEMENT_ARIA_LABEL = '[Amplitude] Element Aria Label';
+export const AMPLITUDE_EVENT_PROP_ELEMENT_ATTRIBUTES = '[Amplitude] Element Attributes';
+export const AMPLITUDE_EVENT_PROP_ELEMENT_SELECTOR = '[Amplitude] Element Selector';
 export const AMPLITUDE_EVENT_PROP_PAGE_URL = '[Amplitude] Page URL';
 export const AMPLITUDE_EVENT_PROP_PAGE_TITLE = '[Amplitude] Page Title';
 export const AMPLITUDE_EVENT_PROP_VIEWPORT_HEIGHT = '[Amplitude] Viewport Height';

packages/plugin-auto-tracking-browser/src/helpers.ts

@@ -51,3 +51,45 @@ export const getText = (element: Element): string => {
   }
   return text;
 };
+
+export const isPageUrlAllowed = (url: string, pageUrlAllowlist: string[] | undefined) => {
+  if (!pageUrlAllowlist || !pageUrlAllowlist.length) {
+    return true;
+  }
+  return pageUrlAllowlist.some((allowedUrl) => {
+    const allowedUrlRegex = new RegExp(allowedUrl);
+    return url.match(allowedUrlRegex);
+  });
+};
+
+export const getAttributesWithPrefix = (element: Element, prefix: string): { [key: string]: string } => {
+  return element.getAttributeNames().reduce((attributes: { [key: string]: string }, attributeName) => {
+    if (attributeName.startsWith(prefix)) {
+      const attributeKey = attributeName.replace(prefix, '');
+      const attributeValue = element.getAttribute(attributeName);
+      if (attributeKey) {
+        attributes[attributeKey] = attributeValue || '';
+      }
+    }
+    return attributes;
+  }, {});
+};
+
+export const isEmpty = (value: unknown) => {
+  return (
+    value === undefined ||
+    value === null ||
+    (typeof value === 'object' && Object.keys(value).length === 0) ||
+    (typeof value === 'string' && value.trim().length === 0)
+  );
+};
+
+export const removeEmptyProperties = (properties: { [key: string]: unknown }) => {
+  return Object.keys(properties).reduce((filteredProperties: { [key: string]: unknown }, key) => {
+    const value = properties[key];
+    if (!isEmpty(value)) {
+      filteredProperties[key] = value;
+    }
+    return filteredProperties;
+  }, {});
+};