@aws-amplify/analytics 6.5.6-api-v6-models.b3abc9b.0 → 7.0.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

@@ -0,0 +1,78 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AnalyticsAction } from '@aws-amplify/core/internals/utils';
+import {
+	updateEndpoint,
+	UpdateEndpointException,
+} from '@aws-amplify/core/internals/providers/pinpoint';
+import { AnalyticsValidationErrorCode } from '../../../errors';
+import { getAnalyticsUserAgentString } from '../../../utils';
+import { IdentifyUserInput } from '../types';
+import { resolveConfig, resolveCredentials } from '../utils';
+
+/**
+ * Sends information about a user to Pinpoint. Sending user information allows you to associate a user to their user
+ * profile and activities or actions in your application. Activity can be tracked across devices & platforms by using
+ * the same `userId`.
+ *
+ * @param {IdentifyUserParameters} params The input object used to construct requests sent to Pinpoint's UpdateEndpoint
+ *  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
+ *  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: {
+ *         email: 'userEmail@example.com'
+ *         customProperties: {
+ *             phoneNumber: ['555-555-5555'],
+ *         },
+ *     }
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Identify a user with Pinpoint with some additional demographics
+ * await identifyUser({
+ *     userId,
+ *     userProfile: {
+ *         email: 'userEmail@example.com'
+ *         customProperties: {
+ *             phoneNumber: ['555-555-5555'],
+ *         },
+ *         demographic: {
+ *             platform: 'ios',
+ *             timezone: 'America/Los_Angeles'
+ *         }
+ *     }
+ * });
+ */
+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.IdentifyUser),
+	});
+};

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

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { record } from './record';
+export { identifyUser } from './identifyUser';
+export { configureAutoTrack } from './configureAutoTrack';
+export { flushEvents } from './flushEvents';

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

@@ -0,0 +1,83 @@
+// 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,
+} from '@aws-amplify/core/internals/utils';
+import { record as recordCore } from '@aws-amplify/core/internals/providers/pinpoint';
+import {
+	AnalyticsValidationErrorCode,
+	assertValidationError,
+} from '../../../errors';
+import {
+	getAnalyticsUserAgentString,
+	isAnalyticsEnabled,
+} from '../../../utils';
+import { RecordInput } from '../types';
+import { resolveConfig, resolveCredentials } from '../utils';
+
+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
+ *  configuration is incorrect.
+ *
+ * @example
+ * ```ts
+ * // Send an event to Pinpoint
+ * record({ name: eventName })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Send an event to Pinpoint with metrics & custom attributes
+ * record({
+ *     name: eventName,
+ *     attributes: {
+ *         'my-attribute': attributeValue
+ *     },
+ *     metrics: {
+ *         'my-metric': metricValue
+ *     }
+ * })
+ * ```
+ */
+export const record = (input: RecordInput): void => {
+	const { appId, region } = resolveConfig();
+
+	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: input,
+				identityId,
+				region,
+				userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.Record),
+			});
+		})
+		.catch(e => {
+			// An error occured while fetching credentials or persisting the event to the buffer
+			logger.warn('Failed to record event.', e);
+		});
+};

package/src/providers/pinpoint/index.ts

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

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

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

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

@@ -0,0 +1,24 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+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 = PinpointAnalyticsEvent;
+
+/**
+ * Input type for Pinpoint identifyUser API.
+ */
+export type IdentifyUserInput = AnalyticsIdentifyUserInput<IdentifyUserOptions>;
+
+/**
+ * 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/providers/pinpoint/utils/index.ts

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

package/src/providers/pinpoint/utils/resolveConfig.ts

@@ -0,0 +1,18 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Amplify } from '@aws-amplify/core';
+import {
+	AnalyticsValidationErrorCode,
+	assertValidationError,
+} from '../../../errors';
+
+/**
+ * @internal
+ */
+export const resolveConfig = () => {
+	const { appId, region } = Amplify.getConfig().Analytics?.Pinpoint ?? {};
+	assertValidationError(!!appId, AnalyticsValidationErrorCode.NoAppId);
+	assertValidationError(!!region, AnalyticsValidationErrorCode.NoRegion);
+	return { appId, region };
+};

package/src/providers/pinpoint/utils/resolveCredentials.ts

@@ -0,0 +1,20 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { fetchAuthSession } from '@aws-amplify/core';
+import {
+	AnalyticsValidationErrorCode,
+	assertValidationError,
+} from '../../../errors';
+
+/**
+ * @internal
+ */
+export const resolveCredentials = async () => {
+	const { credentials, identityId } = await fetchAuthSession();
+	assertValidationError(
+		!!credentials,
+		AnalyticsValidationErrorCode.NoCredentials
+	);
+	return { credentials, identityId };
+};

package/src/trackers/EventTracker.ts

@@ -1,115 +1,135 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { delegate } from '../vendor/dom-utils';
-import { EventTrackOpts } from '../types';
-import { ConsoleLogger as Logger, browserOrNode } from '@aws-amplify/core';
-
-const logger = new Logger('EventTracker');
-
-const defaultOpts: EventTrackOpts = {
-	enable: false,
-	events: ['click'],
-	selectorPrefix: 'data-amplify-analytics-',
-	provider: 'AWSPinpoint',
-};
-
-export class EventTracker {
-	private _tracker;
-	private _config: EventTrackOpts;
-	private _delegates;
-
-	constructor(tracker, opts) {
-		if (!browserOrNode().isBrowser || !window.addEventListener) {
-			logger.debug('not in the supported web environment');
-			return;
-		}
-
-		this._config = Object.assign({}, defaultOpts, opts);
-		this._tracker = tracker;
-		this._delegates = {};
-		this._trackFunc = this._trackFunc.bind(this);
-
-		logger.debug('initialize pageview tracker with opts', this._config);
-
-		this.configure(this._config);
+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);
 	}
 
-	configure(opts?: EventTrackOpts) {
-		Object.assign(this._config, opts);
-
-		if (!this._config.enable) {
-			Object.keys(this._delegates).forEach(key => {
-				if (typeof this._delegates[key].destroy === 'function')
-					this._delegates[key].destroy();
+	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._delegates = {};
-		} else if (
-			this._config.enable &&
-			Object.keys(this._delegates).length === 0
-		) {
-			const selector = '[' + this._config.selectorPrefix + 'on]';
-			this._config.events.forEach(evt => {
-				this._delegates[evt] = delegate(
-					document,
-					evt,
-					selector,
-					this._trackFunc,
-					{ composed: true, useCapture: true }
-				);
-			});
-		}
 
-		return this._config;
+			this.trackerActive = true;
+		}
 	}
 
-	private async _trackFunc(event, element) {
-		// the events specifed in 'amplify-analytics-on' selector
-		const customAttrs = {};
-		const events = element
-			.getAttribute(this._config.selectorPrefix + 'on')
-			.split(/\s*,\s*/);
-		const eventName = element.getAttribute(
-			this._config.selectorPrefix + 'name'
-		);
-
-		const attrs = element.getAttribute(this._config.selectorPrefix + 'attrs');
-		if (attrs) {
-			attrs.split(/\s*,\s*/).forEach(attr => {
-				const tmp = attr.trim().split(/\s*:\s*/);
-				customAttrs[tmp[0]] = tmp[1];
-			});
+	public cleanup() {
+		// No-op if document listener is not active
+		if (!this.trackerActive) {
+			return;
 		}
 
-		const defaultAttrs =
-			typeof this._config.attributes === 'function'
-				? await this._config.attributes()
-				: this._config.attributes;
-
-		const attributes = Object.assign(
-			{
-				type: event.type,
-				target: `${event.target.localName} with id ${event.target.id}`,
-			},
-			defaultAttrs,
-			customAttrs
-		);
-
-		logger.debug('events needed to be recorded', events);
-		logger.debug('attributes needed to be attached', customAttrs);
-		if (events.indexOf(event.type) < 0) {
-			logger.debug(`event ${event.type} is not selected to be recorded`);
+		// 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;
 		}
 
-		this._tracker(
-			{
-				name: eventName || 'event',
-				attributes,
-			},
-			this._config.provider
-		).catch(e => {
-			logger.debug(`Failed to record the ${event.type} event', ${e}`);
-		});
+		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);
+			}
+		}
 	}
 }