@aws-amplify/analytics 7.0.1-preview-testing.034e780.0 → 7.0.1-server-generate-client.1e317a1.0

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

@@ -0,0 +1,32 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { resolveConfig, resolveCredentials } from '../utils';
+import { flushEvents as flushEventsCore } from '@aws-amplify/core/internals/providers/pinpoint';
+import { AnalyticsAction } from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+import { getAnalyticsUserAgentString } from '../../../utils';
+
+const logger = new ConsoleLogger('Analytics');
+
+/**
+ * Flushes all buffered Pinpoint events to the service.
+ *
+ * @note
+ * This API will make a best-effort attempt to flush events from the buffer. Events recorded immediately after invoking
+ * this API may not be included in the flush.
+ */
+export const flushEvents = () => {
+	const { appId, region } = resolveConfig();
+	resolveCredentials()
+		.then(({ credentials, identityId }) =>
+			flushEventsCore(
+				appId,
+				region,
+				credentials,
+				identityId,
+				getAnalyticsUserAgentString(AnalyticsAction.Record)
+			)
+		)
+		.catch(e => logger.warn('Failed to flush events', e));
+};

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

@@ -2,10 +2,13 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { AnalyticsAction } from '@aws-amplify/core/internals/utils';
-import { updateEndpoint } from '@aws-amplify/core/internals/providers/pinpoint';
+import {
+	updateEndpoint,
+	UpdateEndpointException,
+} from '@aws-amplify/core/internals/providers/pinpoint';
 import { AnalyticsValidationErrorCode } from '../../../errors';
-import { getAnalyticsUserAgentString } from '../../../utils/userAgent';
-import { IdentifyUserInput, UpdateEndpointException } from '../types';
+import { getAnalyticsUserAgentString } from '../../../utils';
+import { IdentifyUserInput } from '../types';
 import { resolveConfig, resolveCredentials } from '../utils';
 
 /**
@@ -17,32 +20,34 @@ import { resolveConfig, resolveCredentials } from '../utils';
  *  API.
  *
  * @throws service: {@link UpdateEndpointException} - Thrown when the underlying Pinpoint service returns an error.
- * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library 
+ * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library
  *  configuration is incorrect.
- * 
+ *
  * @returns A promise that will resolve when the operation is complete.
- * 
+ *
  * @example
  * ```ts
  * // Identify a user with Pinpoint
  * await identifyUser({
  *     userId,
  *     userProfile: {
- *         attributes: {
- *             email: [userEmail],
+ *         email: 'userEmail@example.com'
+ *         customProperties: {
+ *             phoneNumber: ['555-555-5555'],
  *         },
  *     }
  * });
  * ```
- * 
+ *
  * @example
  * ```ts
  * // Identify a user with Pinpoint with some additional demographics
  * await identifyUser({
  *     userId,
  *     userProfile: {
- *         attributes: {
- *             email: [userEmail],
+ *         email: 'userEmail@example.com'
+ *         customProperties: {
+ *             phoneNumber: ['555-555-5555'],
  *         },
  *         demographic: {
  *             platform: 'ios',
@@ -54,17 +59,20 @@ import { resolveConfig, resolveCredentials } from '../utils';
 export const identifyUser = async ({
 	userId,
 	userProfile,
+	options,
 }: IdentifyUserInput): Promise<void> => {
 	const { credentials, identityId } = await resolveCredentials();
 	const { appId, region } = resolveConfig();
+	const { userAttributes } = options ?? {};
 	updateEndpoint({
 		appId,
 		category: 'Analytics',
 		credentials,
 		identityId,
 		region,
+		userAttributes,
 		userId,
 		userProfile,
-		userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.UpdateEndpoint),
+		userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.IdentifyUser),
 	});
 };

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

@@ -3,3 +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

@@ -1,68 +1,76 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { Hub, ConsoleLogger } from '@aws-amplify/core';
 import {
+	AMPLIFY_SYMBOL,
 	AnalyticsAction,
-	ConsoleLogger as Logger,
 } from '@aws-amplify/core/internals/utils';
 import { record as recordCore } from '@aws-amplify/core/internals/providers/pinpoint';
 import {
 	AnalyticsValidationErrorCode,
 	assertValidationError,
 } from '../../../errors';
-import { getAnalyticsUserAgentString } from '../../../utils/userAgent';
+import {
+	getAnalyticsUserAgentString,
+	isAnalyticsEnabled,
+} from '../../../utils';
 import { RecordInput } from '../types';
 import { resolveConfig, resolveCredentials } from '../utils';
 
-const logger = new Logger('Analytics');
+const logger = new ConsoleLogger('Analytics');
 
 /**
  * Records an Analytic event to Pinpoint. Events will be buffered and periodically sent to Pinpoint.
  *
  * @param {RecordInput} params The input object used to construct the request.
  *
- * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library 
+ * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library
  *  configuration is incorrect.
- * 
+ *
  * @example
  * ```ts
  * // Send an event to Pinpoint
- * record({
- *     event: {
- * 	       name: eventName,
- *     }
- * })
+ * record({ name: eventName })
  * ```
- * 
+ *
  * @example
  * ```ts
  * // Send an event to Pinpoint with metrics & custom attributes
  * record({
- *     event: {
- *         name: eventName,
- *         attributes: {
- *             'my-attribute': attributeValue
- *         },
- *         metrics: {
- *             'my-metric': metricValue
- *         }
+ *     name: eventName,
+ *     attributes: {
+ *         'my-attribute': attributeValue
+ *     },
+ *     metrics: {
+ *         'my-metric': metricValue
  *     }
  * })
  * ```
  */
-export const record = ({ event }: RecordInput): void => {
+export const record = (input: RecordInput): void => {
 	const { appId, region } = resolveConfig();
 
-	assertValidationError(!!event, AnalyticsValidationErrorCode.NoEvent);
-	assertValidationError(!!event.name, AnalyticsValidationErrorCode.NoEventName);
+	if (!isAnalyticsEnabled()) {
+		logger.debug('Analytics is disabled, event will not be recorded.');
+		return;
+	}
+
+	assertValidationError(!!input.name, AnalyticsValidationErrorCode.NoEventName);
 
 	resolveCredentials()
 		.then(({ credentials, identityId }) => {
+			Hub.dispatch(
+				'analytics',
+				{ event: 'record', data: input, message: 'Recording Analytics event' },
+				'Analytics',
+				AMPLIFY_SYMBOL
+			);
 			recordCore({
 				appId,
 				category: 'Analytics',
 				credentials,
-				event,
+				event: input,
 				identityId,
 				region,
 				userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.Record),

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 } 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 { UpdateEndpointException } from './errors';
-export { RecordInput, IdentifyUserInput } from './inputs';
+export {
+	RecordInput,
+	IdentifyUserInput,
+	ConfigureAutoTrackInput,
+} from './inputs';
+export { IdentifyUserOptions } from './options';

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

@@ -1,30 +1,24 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { UserProfile } from '@aws-amplify/core';
 import { PinpointAnalyticsEvent } from '@aws-amplify/core/internals/providers/pinpoint';
+import { IdentifyUserOptions } from '.';
+import {
+	AnalyticsConfigureAutoTrackInput,
+	AnalyticsIdentifyUserInput,
+} from '../../../types';
 
 /**
  * Input type for Pinpoint record API.
  */
-export type RecordInput = {
-	/**
-	 * An event to send to the default Analytics provider.
-	 */
-	event: PinpointAnalyticsEvent;
-};
+export type RecordInput = PinpointAnalyticsEvent;
 
 /**
  * Input type for Pinpoint identifyUser API.
  */
-export type IdentifyUserInput = {
-	/**
-	 * A User ID associated to the current device.
-	 */
-	userId: string;
+export type IdentifyUserInput = AnalyticsIdentifyUserInput<IdentifyUserOptions>;
 
-	/**
-	 * Additional information about the user and their device.
-	 */
-	userProfile: UserProfile;
-};
+/**
+ * Input type for Pinpoint configureAutoTrack API.
+ */
+export type ConfigureAutoTrackInput = AnalyticsConfigureAutoTrackInput;

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

@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { PinpointServiceOptions } from '@aws-amplify/core/internals/providers/pinpoint';
+
+/**
+ * Options specific to Pinpoint identityUser.
+ */
+export type IdentifyUserOptions = Pick<
+	PinpointServiceOptions,
+	'userAttributes'
+>;

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