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

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`.
@@ -25,3 +30,23 @@ export type AnalyticsIdentifyUserInput<
 	 */
 	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/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/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
+	);
+};

package/src/utils/trackerHelpers.ts

@@ -0,0 +1,57 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	TrackerAttributes,
+	TrackerEventRecorder,
+	TrackerInterface,
+	TrackerType,
+} from '../types/trackers';
+import { EventTracker, PageViewTracker, SessionTracker } from '../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 const updateProviderTrackers = (
+	input: ConfigureAutoTrackInput,
+	providerEventRecorder: TrackerEventRecorder,
+	providerTrackers: Partial<Record<TrackerType, TrackerInterface>>
+) => {
+	let trackerInstance;
+	const trackerType = input.type;
+	const 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/lib/types/analytics.d.ts

@@ -1,50 +0,0 @@
-/**
- * Analytics instance options
- */
-export interface EventAttributes {
-    [key: string]: string;
-}
-export interface EventMetrics {
-    [key: string]: number;
-}
-export interface PageViewTrackOpts {
-    enable: boolean;
-    type?: string;
-    eventName?: string;
-    provider?: string;
-    attributes?: EventAttributes | (() => EventAttributes | Promise<EventAttributes>);
-    getUrl?: () => string;
-}
-export interface EventTrackOpts {
-    enable: boolean;
-    events?: Array<string>;
-    selectorPrefix?: string;
-    provider?: string;
-    attributes?: EventAttributes | (() => EventAttributes | Promise<EventAttributes>);
-}
-export interface SessionTrackOpts {
-    enable: boolean;
-    attributes?: EventAttributes | (() => EventAttributes | Promise<EventAttributes>);
-    provider?: string;
-}
-export type AutoTrackAttributes = (() => EventAttributes | Promise<EventAttributes>) | EventAttributes;
-export interface AutoTrackSessionOpts {
-    enable: boolean;
-    attributes?: AutoTrackAttributes;
-    provider?: string;
-}
-export interface AutoTrackPageViewOpts {
-    enable: boolean;
-    eventName?: string;
-    attributes?: AutoTrackAttributes;
-    type?: 'SPA' | 'multiPageApp';
-    provider?: string;
-    getUrl?: () => string;
-}
-export interface AutoTrackEventOpts {
-    enable: boolean;
-    events?: string[];
-    selectorPrefix?: string;
-    provider?: string;
-    attributes?: AutoTrackAttributes;
-}

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

@@ -1,50 +0,0 @@
-/**
- * Analytics instance options
- */
-export interface EventAttributes {
-    [key: string]: string;
-}
-export interface EventMetrics {
-    [key: string]: number;
-}
-export interface PageViewTrackOpts {
-    enable: boolean;
-    type?: string;
-    eventName?: string;
-    provider?: string;
-    attributes?: EventAttributes | (() => EventAttributes | Promise<EventAttributes>);
-    getUrl?: () => string;
-}
-export interface EventTrackOpts {
-    enable: boolean;
-    events?: Array<string>;
-    selectorPrefix?: string;
-    provider?: string;
-    attributes?: EventAttributes | (() => EventAttributes | Promise<EventAttributes>);
-}
-export interface SessionTrackOpts {
-    enable: boolean;
-    attributes?: EventAttributes | (() => EventAttributes | Promise<EventAttributes>);
-    provider?: string;
-}
-export type AutoTrackAttributes = (() => EventAttributes | Promise<EventAttributes>) | EventAttributes;
-export interface AutoTrackSessionOpts {
-    enable: boolean;
-    attributes?: AutoTrackAttributes;
-    provider?: string;
-}
-export interface AutoTrackPageViewOpts {
-    enable: boolean;
-    eventName?: string;
-    attributes?: AutoTrackAttributes;
-    type?: 'SPA' | 'multiPageApp';
-    provider?: string;
-    getUrl?: () => string;
-}
-export interface AutoTrackEventOpts {
-    enable: boolean;
-    events?: string[];
-    selectorPrefix?: string;
-    provider?: string;
-    attributes?: AutoTrackAttributes;
-}

package/src/types/analytics.ts

@@ -1,70 +0,0 @@
-// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * Analytics instance options
- */
-
-export interface EventAttributes {
-	[key: string]: string;
-}
-
-export interface EventMetrics {
-	[key: string]: number;
-}
-
-export interface PageViewTrackOpts {
-	enable: boolean;
-	type?: string;
-	eventName?: string;
-	provider?: string;
-	attributes?:
-		| EventAttributes
-		| (() => EventAttributes | Promise<EventAttributes>);
-	getUrl?: () => string;
-}
-
-export interface EventTrackOpts {
-	enable: boolean;
-	events?: Array<string>;
-	selectorPrefix?: string;
-	provider?: string;
-	attributes?:
-		| EventAttributes
-		| (() => EventAttributes | Promise<EventAttributes>);
-}
-
-export interface SessionTrackOpts {
-	enable: boolean;
-	attributes?:
-		| EventAttributes
-		| (() => EventAttributes | Promise<EventAttributes>);
-	provider?: string;
-}
-
-export type AutoTrackAttributes =
-	| (() => EventAttributes | Promise<EventAttributes>)
-	| EventAttributes;
-
-export interface AutoTrackSessionOpts {
-	enable: boolean;
-	attributes?: AutoTrackAttributes;
-	provider?: string;
-}
-
-export interface AutoTrackPageViewOpts {
-	enable: boolean;
-	eventName?: string;
-	attributes?: AutoTrackAttributes;
-	type?: 'SPA' | 'multiPageApp';
-	provider?: string;
-	getUrl?: () => string;
-}
-
-export interface AutoTrackEventOpts {
-	enable: boolean;
-	events?: string[];
-	selectorPrefix?: string;
-	provider?: string;
-	attributes?: AutoTrackAttributes;
-}