@aws-amplify/analytics 7.0.1-console-preview.8d88eef.0 → 7.0.1-console-preview.b278dcb.0

package/lib-esm/types/index.d.ts

@@ -1,4 +1,3 @@
-export { AutoTrackAttributes, AutoTrackEventOpts, AutoTrackPageViewOpts, AutoTrackSessionOpts, EventAttributes, EventMetrics, EventTrackOpts, PageViewTrackOpts, SessionTrackOpts, } from './analytics';
 export { AnalyticsServiceOptions } from './options';
-export { AnalyticsIdentifyUserInput } from './inputs';
+export { AnalyticsConfigureAutoTrackInput, AnalyticsIdentifyUserInput, } from './inputs';
 export { KinesisStream, KinesisShard, KinesisEventData } from './kinesis';

package/lib-esm/types/inputs.d.ts

@@ -1,5 +1,6 @@
 import { UserProfile } from '@aws-amplify/core';
 import { AnalyticsServiceOptions } from '.';
+import { SessionTrackingOptions, PageViewTrackingOptions, EventTrackingOptions } from './trackers';
 /**
  * Input type for `identifyUser`.
  */
@@ -17,3 +18,18 @@ export type AnalyticsIdentifyUserInput<ServiceOptions extends AnalyticsServiceOp
      */
     options?: ServiceOptions;
 };
+/**
+ * Input type for `configureAutoTrack`.
+ */
+export type AnalyticsConfigureAutoTrackInput = {
+    enable: boolean;
+} & ({
+    type: 'session';
+    options?: SessionTrackingOptions;
+} | {
+    type: 'pageView';
+    options?: PageViewTrackingOptions;
+} | {
+    type: 'event';
+    options?: EventTrackingOptions;
+});

package/lib-esm/types/trackers.d.ts

@@ -0,0 +1,22 @@
+export type SessionTrackingOptions = {
+    attributes?: TrackerAttributes;
+};
+export type PageViewTrackingOptions = {
+    attributes?: TrackerAttributes;
+    eventName?: string;
+    urlProvider?: () => string;
+    appType?: 'multiPage' | 'singlePage';
+};
+export type EventTrackingOptions = {
+    attributes?: TrackerAttributes;
+    events?: DOMEvent[];
+    selectorPrefix?: string;
+};
+export type TrackerType = 'event' | 'pageView' | 'session';
+export type TrackerAttributes = Record<string, string>;
+export type TrackerEventRecorder = (eventName: string, attributes: TrackerAttributes) => void;
+export type DOMEvent = keyof GlobalEventHandlersEventMap;
+export interface TrackerInterface {
+    configure(eventRecorder: TrackerEventRecorder, options?: object): void;
+    cleanup(): void;
+}

package/lib-esm/utils/index.d.ts

@@ -3,3 +3,5 @@ export { groupBy } from './groupBy';
 export { EventBuffer, IAnalyticsClient, EventBufferConfig, } from './eventBuffer';
 export { enableAnalytics, disableAnalytics, isAnalyticsEnabled, } from './statusHelpers';
 export { getAnalyticsUserAgent, getAnalyticsUserAgentString, } from './userAgent';
+export { updateProviderTrackers } from './trackerHelpers';
+export { validateTrackerConfiguration } from './trackerConfigHelpers';

package/lib-esm/utils/index.js

@@ -5,3 +5,5 @@ export { groupBy } from './groupBy';
 export { EventBuffer, } from './eventBuffer';
 export { enableAnalytics, disableAnalytics, isAnalyticsEnabled, } from './statusHelpers';
 export { getAnalyticsUserAgent, getAnalyticsUserAgentString, } from './userAgent';
+export { updateProviderTrackers } from './trackerHelpers';
+export { validateTrackerConfiguration } from './trackerConfigHelpers';

package/lib-esm/utils/trackerConfigHelpers.d.ts

@@ -0,0 +1,5 @@
+import { AnalyticsConfigureAutoTrackInput } from '../types';
+/**
+ * Validates tracker configuration.
+ */
+export declare const validateTrackerConfiguration: (input: AnalyticsConfigureAutoTrackInput) => void;

package/lib-esm/utils/trackerConfigHelpers.js

@@ -0,0 +1,11 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AnalyticsValidationErrorCode, assertValidationError } from '../errors';
+/**
+ * Validates tracker configuration.
+ */
+export var validateTrackerConfiguration = function (input) {
+    assertValidationError(input.type === 'event' ||
+        input.type === 'pageView' ||
+        input.type === 'session', AnalyticsValidationErrorCode.InvalidTracker);
+};

package/lib-esm/utils/trackerConfigHelpers.native.d.ts

@@ -0,0 +1,5 @@
+import { AnalyticsConfigureAutoTrackInput } from '../types';
+/**
+ * Validates tracker configuration.
+ */
+export declare const validateTrackerConfiguration: (input: AnalyticsConfigureAutoTrackInput) => void;

package/lib-esm/utils/trackerConfigHelpers.native.js

@@ -0,0 +1,10 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AnalyticsValidationErrorCode, assertValidationError } from '../errors';
+/**
+ * Validates tracker configuration.
+ */
+export var validateTrackerConfiguration = function (input) {
+    // React Native only supports session tracking
+    assertValidationError(input.type === 'session', AnalyticsValidationErrorCode.UnsupportedPlatform);
+};

package/lib-esm/utils/trackerHelpers.d.ts

@@ -0,0 +1,9 @@
+import { TrackerEventRecorder, TrackerInterface, TrackerType } from '../types/trackers';
+import { ConfigureAutoTrackInput } from '../providers/pinpoint';
+/**
+ * Updates a provider's trackers as appropriate for the provided auto-track configuration.
+ *
+ * @remark
+ * This utility will mutate the provider's configured trackers via `providerTrackers`.
+ */
+export declare const updateProviderTrackers: (input: ConfigureAutoTrackInput, providerEventRecorder: TrackerEventRecorder, providerTrackers: Partial<Record<TrackerType, TrackerInterface>>) => void;

package/lib-esm/utils/trackerHelpers.js

@@ -0,0 +1,40 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { EventTracker, PageViewTracker, SessionTracker } from '../trackers';
+/**
+ * Updates a provider's trackers as appropriate for the provided auto-track configuration.
+ *
+ * @remark
+ * This utility will mutate the provider's configured trackers via `providerTrackers`.
+ */
+export var updateProviderTrackers = function (input, providerEventRecorder, providerTrackers) {
+    var trackerInstance;
+    var trackerType = input.type;
+    var currentTracker = providerTrackers[trackerType];
+    // Check if the tracker was disabled & should be cleaned up
+    if (!input.enable) {
+        if (currentTracker) {
+            currentTracker.cleanup();
+            delete providerTrackers[trackerType];
+        }
+        return;
+    }
+    // Re-configure the existing tracker, or create & configure an instance if it doesn't exist yet
+    if (currentTracker) {
+        currentTracker.configure(providerEventRecorder, input.options);
+        return;
+    }
+    // Create a new tracker instance for the type
+    if (trackerType === 'event') {
+        trackerInstance = new EventTracker(providerEventRecorder, input.options);
+    }
+    else if (trackerType === 'pageView') {
+        trackerInstance = new PageViewTracker(providerEventRecorder, input.options);
+    }
+    else if (trackerType === 'session') {
+        trackerInstance = new SessionTracker(providerEventRecorder, input.options);
+    }
+    if (trackerInstance) {
+        providerTrackers[trackerType] = trackerInstance;
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-amplify/analytics",
-  "version": "7.0.1-console-preview.8d88eef.0+8d88eef",
+  "version": "7.0.1-console-preview.b278dcb.0+b278dcb",
   "description": "Analytics category of aws-amplify",
   "main": "./lib/index.js",
   "module": "./lib-esm/index.js",
@@ -99,10 +99,11 @@
     "tslib": "^2.5.0"
   },
   "peerDependencies": {
-    "@aws-amplify/core": "6.0.1-console-preview.8d88eef.0+8d88eef"
+    "@aws-amplify/core": "6.0.1-console-preview.b278dcb.0+b278dcb"
   },
   "devDependencies": {
-    "@aws-amplify/core": "6.0.1-console-preview.8d88eef.0+8d88eef",
+    "@aws-amplify/core": "6.0.1-console-preview.b278dcb.0+b278dcb",
+    "@aws-amplify/react-native": "1.0.1-console-preview.b278dcb.0+b278dcb",
     "@aws-sdk/types": "3.398.0",
     "typescript": "5.0.2"
   },
@@ -150,5 +151,5 @@
       "<rootDir>/src/setupTests.ts"
     ]
   },
-  "gitHead": "8d88eef4137cef4fbe03d7d3683b5bec59feb7b8"
+  "gitHead": "b278dcb6dd7334e53d92d22386a22fba3c4a6089"
 }

package/src/errors/validation.ts

@@ -8,6 +8,8 @@ export enum AnalyticsValidationErrorCode {
 	NoCredentials = 'NoCredentials',
 	NoEventName = 'NoEventName',
 	NoRegion = 'NoRegion',
+	InvalidTracker = 'InvalidTracker',
+	UnsupportedPlatform = 'UnsupportedPlatform',
 	NoTrackingId = 'NoTrackingId',
 	InvalidFlushSize = 'InvalidFlushSize',
 }
@@ -26,6 +28,12 @@ export const validationErrorMap: AmplifyErrorMap<AnalyticsValidationErrorCode> =
 		[AnalyticsValidationErrorCode.NoRegion]: {
 			message: 'Missing region.',
 		},
+		[AnalyticsValidationErrorCode.InvalidTracker]: {
+			message: 'Invalid tracker type specified.',
+		},
+		[AnalyticsValidationErrorCode.UnsupportedPlatform]: {
+			message: 'Only session tracking is supported on React Native.',
+		},
 		[AnalyticsValidationErrorCode.InvalidFlushSize]: {
 			message: 'Invalid FlushSize, it should be smaller than BufferSize',
 		},

package/src/index.ts

@@ -4,9 +4,11 @@
 export {
 	record,
 	identifyUser,
+	configureAutoTrack,
+	flushEvents,
 	RecordInput,
 	IdentifyUserInput,
-	flushEvents,
+	ConfigureAutoTrackInput,
 } from './providers/pinpoint';
 export { enable, disable } from './apis';
 export { AnalyticsError } from './errors';

package/src/providers/pinpoint/apis/configureAutoTrack.ts

@@ -0,0 +1,49 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AnalyticsValidationErrorCode } from '../../../errors';
+import {
+	TrackerType,
+	TrackerAttributes,
+	TrackerInterface,
+} from '../../../types/trackers';
+import {
+	updateProviderTrackers,
+	validateTrackerConfiguration,
+} from '../../../utils';
+import { ConfigureAutoTrackInput } from '../types';
+import { record } from './record';
+
+// Configured Tracker instances for Pinpoint
+const configuredTrackers: Partial<Record<TrackerType, TrackerInterface>> = {};
+
+// Callback that will emit an appropriate event to Pinpoint when required by the Tracker
+const emitTrackingEvent = (
+	eventName: string,
+	attributes: TrackerAttributes
+) => {
+	record({
+		name: eventName,
+		attributes,
+	});
+};
+
+/**
+ * Configures automatic event tracking for Pinpoint. This API will automatically transmit an analytic event when
+ * configured events are detected within your application. This can include: DOM element events (via the `event`
+ * tracker), session events (via the `session` tracker), and page view events (via the `pageView` tracker).
+ *
+ * @remark Only session tracking is currently supported on React Native.
+ *
+ * @param {ConfigureAutoTrackInput} params The input object to configure auto track behavior.
+ *
+ * @throws service: {@link UpdateEndpointException} - Thrown when the underlying Pinpoint service returns an error.
+ * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library
+ *  configuration is incorrect.
+ */
+export const configureAutoTrack = (input: ConfigureAutoTrackInput): void => {
+	validateTrackerConfiguration(input);
+
+	// Initialize or update this provider's trackers
+	updateProviderTrackers(input, emitTrackingEvent, configuredTrackers);
+};

package/src/providers/pinpoint/apis/index.ts

@@ -3,4 +3,5 @@
 
 export { record } from './record';
 export { identifyUser } from './identifyUser';
+export { configureAutoTrack } from './configureAutoTrack';
 export { flushEvents } from './flushEvents';

package/src/providers/pinpoint/apis/record.ts

@@ -4,7 +4,7 @@
 import { Hub, ConsoleLogger } from '@aws-amplify/core';
 import {
 	AMPLIFY_SYMBOL,
-	AnalyticsAction
+	AnalyticsAction,
 } from '@aws-amplify/core/internals/utils';
 import { record as recordCore } from '@aws-amplify/core/internals/providers/pinpoint';
 import {

package/src/providers/pinpoint/index.ts

@@ -1,5 +1,9 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export { record, identifyUser, flushEvents } from './apis';
-export { RecordInput, IdentifyUserInput } from './types/inputs';
+export { record, identifyUser, flushEvents, configureAutoTrack } from './apis';
+export {
+	RecordInput,
+	IdentifyUserInput,
+	ConfigureAutoTrackInput,
+} from './types/inputs';

package/src/providers/pinpoint/types/index.ts

@@ -1,5 +1,9 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export { RecordInput, IdentifyUserInput } from './inputs';
+export {
+	RecordInput,
+	IdentifyUserInput,
+	ConfigureAutoTrackInput,
+} from './inputs';
 export { IdentifyUserOptions } from './options';

package/src/providers/pinpoint/types/inputs.ts

@@ -3,7 +3,10 @@
 
 import { PinpointAnalyticsEvent } from '@aws-amplify/core/internals/providers/pinpoint';
 import { IdentifyUserOptions } from '.';
-import { AnalyticsIdentifyUserInput } from '../../../types';
+import {
+	AnalyticsConfigureAutoTrackInput,
+	AnalyticsIdentifyUserInput,
+} from '../../../types';
 
 /**
  * Input type for Pinpoint record API.
@@ -14,3 +17,8 @@ export type RecordInput = PinpointAnalyticsEvent;
  * Input type for Pinpoint identifyUser API.
  */
 export type IdentifyUserInput = AnalyticsIdentifyUserInput<IdentifyUserOptions>;
+
+/**
+ * Input type for Pinpoint configureAutoTrack API.
+ */
+export type ConfigureAutoTrackInput = AnalyticsConfigureAutoTrackInput;

package/src/trackers/EventTracker.ts

@@ -0,0 +1,135 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	EventTrackingOptions,
+	DOMEvent,
+	TrackerEventRecorder,
+	TrackerInterface,
+} from '../types/trackers';
+import { ConsoleLogger } from '@aws-amplify/core';
+import { isBrowser } from '@aws-amplify/core/internals/utils';
+
+const DEFAULT_EVENTS = ['click'] as DOMEvent[];
+const DEFAULT_SELECTOR_PREFIX = 'data-amplify-analytics-';
+const DEFAULT_EVENT_NAME = 'event'; // Default event name as sent to the analytics provider
+
+const logger = new ConsoleLogger('EventTracker');
+
+export class EventTracker implements TrackerInterface {
+	private trackerActive: boolean;
+	private options: EventTrackingOptions;
+	private eventRecorder: TrackerEventRecorder;
+
+	constructor(
+		eventRecorder: TrackerEventRecorder,
+		options?: EventTrackingOptions
+	) {
+		this.options = {};
+		this.trackerActive = false;
+		this.eventRecorder = eventRecorder;
+		this.handleDocEvent = this.handleDocEvent.bind(this);
+
+		this.configure(eventRecorder, options);
+	}
+
+	public configure(
+		eventRecorder: TrackerEventRecorder,
+		options?: EventTrackingOptions
+	) {
+		this.eventRecorder = eventRecorder;
+
+		// Clean up any existing listeners
+		this.cleanup();
+
+		// Apply defaults
+		this.options = {
+			attributes: options?.attributes ?? undefined,
+			events: options?.events ?? DEFAULT_EVENTS,
+			selectorPrefix: options?.selectorPrefix ?? DEFAULT_SELECTOR_PREFIX,
+		};
+
+		// Register event listeners
+		if (isBrowser()) {
+			this.options.events?.forEach(targetEvent => {
+				document.addEventListener(targetEvent, this.handleDocEvent, {
+					capture: true,
+				});
+			});
+
+			this.trackerActive = true;
+		}
+	}
+
+	public cleanup() {
+		// No-op if document listener is not active
+		if (!this.trackerActive) {
+			return;
+		}
+
+		// Clean up event listeners
+		this.options.events?.forEach(targetEvent => {
+			document.removeEventListener(targetEvent, this.handleDocEvent, {
+				capture: true,
+			});
+		});
+	}
+
+	private handleDocEvent(event: Event) {
+		/**
+		 * Example DOM element:
+		 *
+		 * ```
+		 * <button
+		 *   data-amplify-analytics-on="click"
+		 *   data-amplify-analytics-name="click"
+		 *   data-amplify-analytics-attrs="attr1:attr1_value,attr2:attr2_value"
+		 * />
+		 * ```
+		 */
+		const triggerSelector = `[${this.options.selectorPrefix}on]`;
+		const attrSelector = `${this.options.selectorPrefix}attrs`;
+		const eventNameSelector = `${this.options.selectorPrefix}name`;
+		const eventSource = event.target;
+
+		// Validate that the triggering event type is being tracked
+		if (!this.options.events?.includes(event.type as DOMEvent)) {
+			return;
+		}
+
+		if (eventSource instanceof HTMLElement) {
+			const target = eventSource.closest(triggerSelector);
+
+			if (target) {
+				// Parse event name from the element
+				const eventName =
+					target.getAttribute(eventNameSelector) || DEFAULT_EVENT_NAME;
+
+				// Parse attributes from the element
+				const elementAttributes: Record<string, string> = {};
+				const rawElementAttributes = target.getAttribute(attrSelector);
+				rawElementAttributes?.split(/\s*,\s*/).forEach(attr => {
+					const tmp = attr.trim().split(/\s*:\s*/);
+					elementAttributes[tmp[0]] = tmp[1];
+				});
+
+				// Assemble final list of attributes
+				const attributes = Object.assign(
+					{
+						type: event.type,
+						target: `${target.localName} with id ${target.id}`,
+					},
+					this.options.attributes,
+					elementAttributes
+				);
+
+				logger.debug('Recording automatically tracked DOM event', {
+					eventName,
+					attributes,
+				});
+
+				this.eventRecorder(eventName, attributes);
+			}
+		}
+	}
+}

package/src/trackers/PageViewTracker.ts

@@ -0,0 +1,160 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	PageViewTrackingOptions,
+	TrackerEventRecorder,
+	TrackerInterface,
+} from '../types/trackers';
+import { ConsoleLogger } from '@aws-amplify/core';
+import { isBrowser } from '@aws-amplify/core/internals/utils';
+
+const logger = new ConsoleLogger('PageViewTracker');
+
+const DEFAULT_EVENT_NAME = 'pageView';
+const DEFAULT_APP_TYPE = 'singlePage';
+const DEFAULT_URL_PROVIDER = () => {
+	return window.location.origin + window.location.pathname;
+};
+const PREV_URL_STORAGE_KEY = 'aws-amplify-analytics-prevUrl';
+
+export class PageViewTracker implements TrackerInterface {
+	private trackerActive: boolean;
+	private options: PageViewTrackingOptions;
+	private eventRecorder: TrackerEventRecorder;
+
+	// SPA tracking helpers
+	private spaTrackingActive: boolean;
+	private pushStateProxy?: any;
+	private replaceStateProxy?: any;
+	private originalPushState: any;
+	private originalReplaceState: any;
+
+	constructor(
+		eventRecorder: TrackerEventRecorder,
+		options?: PageViewTrackingOptions
+	) {
+		this.options = {};
+		this.trackerActive = true;
+		this.eventRecorder = eventRecorder;
+		this.spaTrackingActive = false;
+		this.handleLocationChange = this.handleLocationChange.bind(this);
+
+		this.configure(eventRecorder, options);
+	}
+
+	public configure(
+		eventRecorder: TrackerEventRecorder,
+		options?: PageViewTrackingOptions
+	) {
+		this.eventRecorder = eventRecorder;
+
+		// Clean up any existing listeners
+		this.cleanup();
+
+		// Apply defaults
+		this.options = {
+			appType: options?.appType ?? DEFAULT_APP_TYPE,
+			attributes: options?.attributes ?? undefined,
+			eventName: this.options?.eventName ?? DEFAULT_EVENT_NAME,
+			urlProvider: this.options?.urlProvider ?? DEFAULT_URL_PROVIDER,
+		};
+
+		// Configure SPA or MPA page view tracking
+		if (isBrowser()) {
+			if (this.options.appType === 'singlePage') {
+				this.setupSPATracking();
+			} else {
+				this.setupMPATracking();
+			}
+
+			this.trackerActive = true;
+		}
+	}
+
+	public cleanup() {
+		// No-op if document listener is not active
+		if (!this.trackerActive) {
+			return;
+		}
+
+		// Clean up SPA page view listeners
+		if (this.spaTrackingActive) {
+			window.history.pushState = this.originalPushState;
+			window.history.replaceState = this.originalReplaceState;
+			this.pushStateProxy?.revoke();
+			this.replaceStateProxy?.revoke();
+			window.removeEventListener('popstate', this.handleLocationChange);
+
+			this.spaTrackingActive = false;
+		}
+	}
+
+	private setupSPATracking() {
+		if (!this.spaTrackingActive) {
+			// Configure proxies on History APIs
+			this.pushStateProxy = Proxy.revocable(window.history.pushState, {
+				apply: (target, thisArg, args) => {
+					const proxiedResult = target.apply(thisArg, args as any);
+
+					this.handleLocationChange();
+
+					return proxiedResult;
+				},
+			});
+			this.replaceStateProxy = Proxy.revocable(window.history.replaceState, {
+				apply: (target, thisArg, args) => {
+					const proxiedResult = target.apply(thisArg, args as any);
+
+					this.handleLocationChange();
+
+					return proxiedResult;
+				},
+			});
+
+			this.originalPushState = window.history.pushState;
+			this.originalReplaceState = window.history.replaceState;
+			window.history.pushState = this.pushStateProxy.proxy;
+			window.history.replaceState = this.replaceStateProxy.proxy;
+			window.addEventListener('popstate', this.handleLocationChange);
+			sessionStorage.removeItem(PREV_URL_STORAGE_KEY);
+
+			this.spaTrackingActive = true;
+		}
+	}
+
+	private setupMPATracking() {
+		this.handleLocationChange();
+	}
+
+	private handleLocationChange() {
+		const currentUrl = this.options.urlProvider!();
+		const eventName = this.options.eventName || DEFAULT_EVENT_NAME;
+
+		if (this.urlHasChanged()) {
+			sessionStorage.setItem(PREV_URL_STORAGE_KEY, currentUrl);
+
+			// Assemble attribute list
+			const attributes = Object.assign(
+				{
+					url: currentUrl,
+				},
+				this.options.attributes
+			);
+
+			logger.debug('Recording automatically tracked page view event', {
+				eventName,
+				attributes,
+			});
+
+			this.eventRecorder(eventName, attributes);
+		}
+	}
+
+	private urlHasChanged() {
+		const prevUrl = sessionStorage.getItem(PREV_URL_STORAGE_KEY);
+		const currUrl = this.options.urlProvider!();
+
+		return currUrl !== prevUrl;
+	}
+}