@aws-amplify/analytics 7.0.1-api-v6-models.8035dfc.0 → 7.0.1-api-v6-models.3eb7748.0

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;
+	}
+}

package/src/trackers/SessionTracker.native.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	sessionListener,
+	SessionState,
+} from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+import {
+	SessionTrackingOptions,
+	TrackerEventRecorder,
+	TrackerInterface,
+} from '../types/trackers';
+
+const SESSION_START_EVENT = '_session.start';
+const SESSION_STOP_EVENT = '_session.stop';
+
+const logger = new ConsoleLogger('SessionTracker');
+
+export class SessionTracker implements TrackerInterface {
+	private options: SessionTrackingOptions;
+	private eventRecorder: TrackerEventRecorder;
+	private initialEventSent: boolean;
+	private sessionTrackingActive: boolean;
+
+	constructor(
+		eventRecorder: TrackerEventRecorder,
+		options?: SessionTrackingOptions
+	) {
+		this.options = {};
+		this.eventRecorder = eventRecorder;
+		this.initialEventSent = false;
+		this.sessionTrackingActive = false;
+		this.handleStateChange = this.handleStateChange.bind(this);
+
+		this.configure(eventRecorder, options);
+	}
+
+	public configure(
+		eventRecorder: TrackerEventRecorder,
+		options?: SessionTrackingOptions
+	) {
+		this.eventRecorder = eventRecorder;
+
+		// Clean up any existing listeners
+		this.cleanup();
+
+		// Apply defaults
+		this.options = {
+			attributes: options?.attributes ?? {},
+		};
+
+		// Setup state listeners
+		if (!this.sessionTrackingActive) {
+			sessionListener.addStateChangeListener(
+				this.handleStateChange,
+				!this.initialEventSent
+			);
+
+			this.sessionTrackingActive = true;
+		}
+	}
+
+	public cleanup() {
+		if (this.sessionTrackingActive) {
+			sessionListener.removeStateChangeListener(this.handleStateChange);
+		}
+
+		this.sessionTrackingActive = false;
+	}
+
+	private handleStateChange(state: SessionState) {
+		if (state === 'started') {
+			this.sessionStarted();
+		} else {
+			this.sessionStopped();
+		}
+	}
+
+	private sessionStarted() {
+		const attributes = this.options.attributes ?? {};
+
+		logger.debug('Recording automatically tracked page view event', {
+			SESSION_START_EVENT,
+			attributes,
+		});
+
+		this.eventRecorder(SESSION_START_EVENT, attributes);
+
+		// NOTE: The initial event will not be re-sent on re-configuration (e.g. to add additional custom attributes)
+		if (!this.initialEventSent) {
+			this.initialEventSent = true;
+		}
+	}
+
+	private sessionStopped() {
+		const attributes = this.options.attributes ?? {};
+
+		logger.debug('Recording automatically tracked page view event', {
+			SESSION_STOP_EVENT,
+			attributes,
+		});
+
+		this.eventRecorder(SESSION_STOP_EVENT, attributes);
+	}
+}

package/src/trackers/SessionTracker.ts

@@ -0,0 +1,106 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	sessionListener,
+	SessionState,
+} from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+import {
+	SessionTrackingOptions,
+	TrackerEventRecorder,
+	TrackerInterface,
+} from '../types/trackers';
+
+const SESSION_START_EVENT = '_session.start';
+const SESSION_STOP_EVENT = '_session.stop';
+
+const logger = new ConsoleLogger('SessionTracker');
+
+export class SessionTracker implements TrackerInterface {
+	private options: SessionTrackingOptions;
+	private eventRecorder: TrackerEventRecorder;
+	private sessionTrackingActive: boolean;
+	private initialEventSent: boolean;
+
+	constructor(
+		eventRecorder: TrackerEventRecorder,
+		options?: SessionTrackingOptions
+	) {
+		this.options = {};
+		this.eventRecorder = eventRecorder;
+		this.sessionTrackingActive = false;
+		this.initialEventSent = false;
+		this.handleStateChange = this.handleStateChange.bind(this);
+
+		this.configure(eventRecorder, options);
+	}
+
+	public configure(
+		eventRecorder: TrackerEventRecorder,
+		options?: SessionTrackingOptions
+	) {
+		this.eventRecorder = eventRecorder;
+
+		// Clean up any existing listeners
+		this.cleanup();
+
+		// Apply defaults
+		this.options = {
+			attributes: options?.attributes ?? {},
+		};
+
+		// Setup state listeners
+		if (!this.sessionTrackingActive) {
+			sessionListener.addStateChangeListener(
+				this.handleStateChange,
+				!this.initialEventSent
+			);
+
+			this.sessionTrackingActive = true;
+		}
+	}
+
+	public cleanup() {
+		if (this.sessionTrackingActive) {
+			sessionListener.removeStateChangeListener(this.handleStateChange);
+		}
+
+		this.sessionTrackingActive = false;
+	}
+
+	private handleStateChange(state: SessionState) {
+		if (state === 'started') {
+			this.sessionStarted();
+		} else {
+			this.sessionStopped();
+		}
+	}
+
+	private sessionStarted() {
+		const attributes = this.options.attributes ?? {};
+
+		logger.debug('Recording automatically tracked page view event', {
+			SESSION_START_EVENT,
+			attributes,
+		});
+
+		this.eventRecorder(SESSION_START_EVENT, attributes);
+
+		// NOTE: The initial event will not be re-sent on re-configuration (e.g. to add additional custom attributes)
+		if (!this.initialEventSent) {
+			this.initialEventSent = true;
+		}
+	}
+
+	private sessionStopped() {
+		const attributes = this.options.attributes ?? {};
+
+		logger.debug('Recording automatically tracked page view event', {
+			SESSION_STOP_EVENT,
+			attributes,
+		});
+
+		this.eventRecorder(SESSION_STOP_EVENT, attributes);
+	}
+}

package/src/trackers/index.ts

@@ -0,0 +1,6 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { EventTracker } from './EventTracker';
+export { PageViewTracker } from './PageViewTracker';
+export { SessionTracker } from './SessionTracker';

package/src/types/index.ts

@@ -1,20 +1,11 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-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/src/types/inputs.ts

@@ -3,6 +3,11 @@
 
 import { UserProfile } from '@aws-amplify/core';
 import { AnalyticsServiceOptions } from '.';
+import {
+	SessionTrackingOptions,
+	PageViewTrackingOptions,
+	EventTrackingOptions,
+} from './trackers';
 
 /**
  * Input type for `identifyUser`.
@@ -23,7 +28,25 @@ export type AnalyticsIdentifyUserInput<
 	/**
 	 * Options to be passed to the API.
 	 */
-	options?: {
-		serviceOptions?: ServiceOptions;
-	};
+	options?: ServiceOptions;
 };
+
+/**
+ * Input type for `configureAutoTrack`.
+ */
+export type AnalyticsConfigureAutoTrackInput = {
+	enable: boolean;
+} & (
+	| {
+			type: 'session';
+			options?: SessionTrackingOptions;
+	  }
+	| {
+			type: 'pageView';
+			options?: PageViewTrackingOptions;
+	  }
+	| {
+			type: 'event';
+			options?: EventTrackingOptions;
+	  }
+);

package/src/types/options.ts

@@ -4,4 +4,4 @@
 /**
  * Base type for service options.
  */
-export type AnalyticsServiceOptions = any;
+export type AnalyticsServiceOptions = Record<string, unknown>;

package/src/types/trackers.ts

@@ -0,0 +1,35 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+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/src/utils/eventBuffer/EventBuffer.ts

@@ -1,7 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { ConsoleLogger } from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
 import { EventBufferConfig, IAnalyticsClient } from './';
 
 const logger = new ConsoleLogger('EventBuffer');

package/src/utils/index.ts

@@ -17,3 +17,5 @@ export {
 	getAnalyticsUserAgent,
 	getAnalyticsUserAgentString,
 } from './userAgent';
+export { updateProviderTrackers } from './trackerHelpers';
+export { validateTrackerConfiguration } from './trackerConfigHelpers';

package/src/utils/trackerConfigHelpers.native.ts

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

package/src/utils/trackerConfigHelpers.ts

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