@aws-amplify/analytics 0.0.0-unstable-1ca644b-20260128091132

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

@@ -0,0 +1,130 @@
+// 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 { ConsoleLogger } from '@aws-amplify/core';
+
+import { RecordInput } from '../types';
+import {
+	autoTrackMedia,
+	getEventBuffer,
+	resolveCachedSession,
+	resolveConfig,
+	updateCachedSession,
+} from '../utils';
+import {
+	getAnalyticsUserAgentString,
+	isAnalyticsEnabled,
+	resolveCredentials,
+} from '../../../utils';
+import {
+	IDENTIFY_EVENT_TYPE,
+	MEDIA_AUTO_TRACK_EVENT_TYPE,
+} from '../utils/constants';
+import { AnalyticsValidationErrorCode } from '../../../errors';
+
+const logger = new ConsoleLogger('Personalize');
+
+/**
+ * Record one analytic event and send it to Personalize. Events will be buffered and periodically sent to Amazon
+ * Personalize.
+ *
+ * For more examples, you can refer to {@link https://docs.amplify.aws/javascript/build-a-backend/more-features/analytics/personalize-recommendations/#working-with-the-api the API usage guidance.}
+ *
+ * @param input The input object used to construct the request.
+ *
+ * @throws validation: {@link AnalyticsValidationErrorCode} - Thrown when the provided parameters or library
+ *  configuration is incorrect.
+ *
+ * @example
+ * ```ts
+ * // Record an `Identify` event to Personalize.
+ * record({
+ *   eventType: "Identify",
+ *   properties: {
+ *     userId: "<USER_ID>"
+ *   }
+ * });
+ * ```
+ * @param input - The event to record.
+ *
+ * @returns void
+ */
+export const record = ({
+	userId,
+	eventId,
+	eventType,
+	properties,
+}: RecordInput): void => {
+	if (!isAnalyticsEnabled()) {
+		logger.debug('Analytics is disabled, event will not be recorded.');
+
+		return;
+	}
+
+	const { region, trackingId, bufferSize, flushSize, flushInterval } =
+		resolveConfig();
+	resolveCredentials()
+		.then(async ({ credentials, identityId }) => {
+			const timestamp = Date.now();
+			const { sessionId: cachedSessionId, userId: cachedUserId } =
+				await resolveCachedSession();
+			if (eventType === IDENTIFY_EVENT_TYPE) {
+				updateCachedSession(
+					typeof properties.userId === 'string' ? properties.userId : '',
+					cachedSessionId,
+					cachedUserId,
+				);
+			} else if (userId) {
+				updateCachedSession(userId, cachedSessionId, cachedUserId);
+			}
+
+			const { sessionId: updatedSessionId, userId: updatedUserId } =
+				await resolveCachedSession();
+
+			const eventBuffer = getEventBuffer({
+				region,
+				flushSize,
+				flushInterval,
+				bufferSize,
+				credentials,
+				identityId,
+				userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.Record),
+			});
+
+			if (eventType === MEDIA_AUTO_TRACK_EVENT_TYPE) {
+				autoTrackMedia(
+					{
+						trackingId,
+						sessionId: updatedSessionId,
+						userId: updatedUserId,
+						event: {
+							eventId,
+							eventType,
+							properties,
+						},
+					},
+					eventBuffer,
+				);
+			} else {
+				eventBuffer.append({
+					trackingId,
+					sessionId: updatedSessionId,
+					userId: updatedUserId,
+					event: {
+						eventId,
+						eventType,
+						properties,
+					},
+					timestamp,
+				});
+			}
+
+			if (eventBuffer.length >= bufferSize) {
+				eventBuffer.flushAll();
+			}
+		})
+		.catch(e => {
+			logger.warn('Failed to record event.', e);
+		});
+};

package/src/providers/personalize/index.ts

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

package/src/providers/personalize/types/buffer.ts

@@ -0,0 +1,23 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AWSCredentials } from '@aws-amplify/core/internals/utils';
+
+import { EventBufferConfig } from '../../../utils';
+
+import { PersonalizeEvent } from './';
+
+export interface PersonalizeBufferEvent {
+	trackingId: string;
+	sessionId?: string;
+	userId?: string;
+	event: PersonalizeEvent;
+	timestamp: number;
+}
+
+export type PersonalizeBufferConfig = EventBufferConfig & {
+	region: string;
+	credentials: AWSCredentials;
+	identityId?: string;
+	userAgentValue?: string;
+};

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

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { RecordInput, PersonalizeEvent } from './inputs';
+export { PersonalizeBufferEvent, PersonalizeBufferConfig } from './buffer';

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

@@ -0,0 +1,11 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export interface PersonalizeEvent {
+	userId?: string;
+	eventId?: string;
+	eventType: string;
+	properties: Record<string, unknown>;
+}
+
+export type RecordInput = PersonalizeEvent;

package/src/providers/personalize/utils/autoTrackMedia.ts

@@ -0,0 +1,240 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { isBrowser } from '@aws-amplify/core/internals/utils';
+import { ConsoleLogger } from '@aws-amplify/core';
+
+import { EventBuffer } from '../../../utils';
+import { PersonalizeBufferEvent, PersonalizeEvent } from '../types';
+
+enum HTML5_MEDIA_EVENT {
+	'PLAY' = 'play',
+	'PAUSE' = 'pause',
+	'ENDED' = 'Ended',
+}
+
+enum MEDIA_TYPE {
+	'IFRAME' = 'IFRAME',
+	'VIDEO' = 'VIDEO',
+	'AUDIO' = 'AUDIO',
+}
+
+enum EVENT_TYPE {
+	'PLAY' = 'Play',
+	'ENDED' = 'Ended',
+	'PAUSE' = 'Pause',
+	'TIME_WATCHED' = 'TimeWatched',
+}
+
+type IRecordEvent = (
+	eventType: string,
+	properties: Record<string, unknown>,
+) => void;
+
+interface MediaAutoTrackConfig {
+	trackingId: string;
+	sessionId: string;
+	userId?: string;
+	event: PersonalizeEvent;
+}
+
+const logger = new ConsoleLogger('MediaAutoTrack');
+
+const startIframeAutoTracking = (
+	element: HTMLElement,
+	recordEvent: IRecordEvent,
+) => {
+	let isPlaying = false;
+	let player: any;
+	const mediaProperties = (): Record<string, unknown> => {
+		const duration = Number(parseFloat(player.getDuration()).toFixed(4));
+		const currentTime = Number(parseFloat(player.getCurrentTime()).toFixed(4));
+
+		return {
+			duration,
+			eventValue: Number((currentTime / duration).toFixed(4)),
+		};
+	};
+
+	const scriptElement = document.createElement('script');
+	scriptElement.type = 'text/javascript';
+	scriptElement.src = 'https://www.youtube.com/iframe_api';
+	document.body.append(scriptElement);
+
+	const timer = setInterval(() => {
+		if (isPlaying && player) {
+			recordEvent(EVENT_TYPE.TIME_WATCHED, mediaProperties());
+		}
+	}, 3_000);
+
+	element.addEventListener('unload', () => {
+		clearInterval(timer);
+	});
+
+	(window as any).onYouTubeIframeAPIReady = () => {
+		delete (window as any).onYouTubeIframeAPIReady;
+
+		player = new (window as any).YT.Player(element.id, {
+			events: {
+				onStateChange: (event: any) => {
+					const iframeEventMapping: Record<number, EVENT_TYPE> = {
+						0: EVENT_TYPE.ENDED,
+						1: EVENT_TYPE.PLAY,
+						2: EVENT_TYPE.PAUSE,
+					};
+
+					const eventType = iframeEventMapping[event.data];
+					switch (eventType) {
+						case EVENT_TYPE.ENDED:
+						case EVENT_TYPE.PAUSE:
+							isPlaying = false;
+							break;
+						case EVENT_TYPE.PLAY:
+							isPlaying = true;
+							break;
+					}
+
+					if (eventType) {
+						recordEvent(eventType, mediaProperties());
+					}
+				},
+			},
+		});
+	};
+};
+
+const startHTMLMediaAutoTracking = (
+	element: HTMLMediaElement,
+	recordEvent: IRecordEvent,
+) => {
+	let isPlaying = false;
+	const mediaProperties = (): Record<string, unknown> => ({
+		duration: element.duration,
+		eventValue: Number((element.currentTime / element.duration).toFixed(4)),
+	});
+
+	const timer = setInterval(() => {
+		if (isPlaying) {
+			recordEvent(EVENT_TYPE.TIME_WATCHED, mediaProperties());
+		}
+	}, 3_000);
+
+	element.addEventListener('unload', () => {
+		clearInterval(timer);
+	});
+
+	element.addEventListener(HTML5_MEDIA_EVENT.PLAY, () => {
+		isPlaying = true;
+		recordEvent(EVENT_TYPE.PLAY, mediaProperties());
+	});
+
+	element.addEventListener(HTML5_MEDIA_EVENT.PAUSE, () => {
+		isPlaying = false;
+		recordEvent(EVENT_TYPE.PAUSE, mediaProperties());
+	});
+
+	element.addEventListener(HTML5_MEDIA_EVENT.ENDED, () => {
+		isPlaying = false;
+		recordEvent(EVENT_TYPE.ENDED, mediaProperties());
+	});
+};
+
+const checkElementLoaded = (interval: number, maxTries: number) => {
+	let retryCount = 0;
+	const wait = () => new Promise(resolve => setTimeout(resolve, interval));
+	const check = async (elementId: string): Promise<boolean> => {
+		if (retryCount >= maxTries) {
+			return false;
+		}
+
+		const domElement = document.getElementById(elementId);
+		if (domElement && domElement.clientHeight) {
+			return true;
+		} else {
+			retryCount += 1;
+			await wait();
+
+			return check(elementId);
+		}
+	};
+
+	return check;
+};
+
+const recordEvent =
+	(
+		config: MediaAutoTrackConfig,
+		eventBuffer: EventBuffer<PersonalizeBufferEvent>,
+	): IRecordEvent =>
+	(eventType: string, properties: Record<string, unknown>) => {
+		// override eventType and merge properties
+		eventBuffer.append({
+			...config,
+			event: {
+				...config.event,
+				eventType,
+				properties: {
+					...config.event.properties,
+					...properties,
+				},
+			},
+			timestamp: Date.now(),
+		});
+	};
+
+export const autoTrackMedia = async (
+	config: MediaAutoTrackConfig,
+	eventBuffer: EventBuffer<PersonalizeBufferEvent>,
+) => {
+	const { eventType, properties } = config.event;
+	const { domElementId, ...otherProperties } = properties;
+	if (!isBrowser()) {
+		logger.debug(`${eventType} only for browser`);
+
+		return;
+	}
+
+	if (typeof domElementId === 'string' && !domElementId) {
+		logger.debug(
+			"Missing domElementId field in 'properties' for MediaAutoTrack event type.",
+		);
+
+		return;
+	}
+
+	const elementId = domElementId as string;
+	const isElementLoaded = await checkElementLoaded(500, 5)(elementId);
+	if (isElementLoaded) {
+		const autoTrackConfigWithoutDomElementId = {
+			...config,
+			event: {
+				...config.event,
+				properties: otherProperties,
+			},
+		};
+
+		const element = document.getElementById(elementId);
+		switch (element?.tagName) {
+			case MEDIA_TYPE.IFRAME:
+				startIframeAutoTracking(
+					element,
+					recordEvent(autoTrackConfigWithoutDomElementId, eventBuffer),
+				);
+				break;
+			case MEDIA_TYPE.VIDEO:
+			case MEDIA_TYPE.AUDIO:
+				if (element instanceof HTMLMediaElement) {
+					startHTMLMediaAutoTracking(
+						element,
+						recordEvent(autoTrackConfigWithoutDomElementId, eventBuffer),
+					);
+				}
+				break;
+			default:
+				logger.debug(`Unsupported DOM element tag: ${element?.tagName}`);
+				break;
+		}
+	} else {
+		logger.debug('Cannot find the media element.');
+	}
+};

package/src/providers/personalize/utils/cachedSession.ts

@@ -0,0 +1,68 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Cache } from '@aws-amplify/core';
+import { amplifyUuid, isBrowser } from '@aws-amplify/core/internals/utils';
+
+const PERSONALIZE_CACHE_USERID = '_awsct_uid';
+const PERSONALIZE_CACHE_SESSIONID = '_awsct_sid';
+const DEFAULT_CACHE_PREFIX = 'personalize';
+const DELIMITER = '.';
+const CACHE_EXPIRY_IN_DAYS = 7;
+
+const normalize = (key: string): string =>
+	[key, isBrowser() ? window.location.host : DEFAULT_CACHE_PREFIX].join(
+		DELIMITER,
+	);
+
+const getCache = (key: string) => Cache.getItem(normalize(key));
+
+const setCache = (key: string, value: unknown) => {
+	const expiredAt = new Date(
+		Date.now() + 3_600_000 * 24 * CACHE_EXPIRY_IN_DAYS,
+	);
+	Cache.setItem(normalize(key), value, {
+		expires: expiredAt.getTime(),
+	});
+};
+
+export const resolveCachedSession = async () => {
+	let sessionId: string | undefined = await getCache(
+		PERSONALIZE_CACHE_SESSIONID,
+	);
+	if (!sessionId) {
+		sessionId = amplifyUuid();
+		setCache(PERSONALIZE_CACHE_SESSIONID, sessionId);
+	}
+
+	const userId: string | undefined = await getCache(PERSONALIZE_CACHE_USERID);
+
+	return {
+		sessionId,
+		userId,
+	};
+};
+
+export const updateCachedSession = (
+	newUserId?: string,
+	currentSessionId?: string,
+	currentUserId?: string,
+) => {
+	const isNoCachedSession = !currentSessionId;
+	const isSignOutCase = !newUserId && !currentUserId;
+	const isSwitchUserCase =
+		!!newUserId && !!currentUserId && newUserId !== currentUserId;
+
+	const isRequireNewSession =
+		isNoCachedSession || isSignOutCase || isSwitchUserCase;
+	const isRequireUpdateSession =
+		!!currentSessionId && !currentUserId && !!newUserId;
+
+	if (isRequireNewSession) {
+		const newSessionId = amplifyUuid();
+		setCache(PERSONALIZE_CACHE_SESSIONID, newSessionId);
+		setCache(PERSONALIZE_CACHE_USERID, newUserId);
+	} else if (isRequireUpdateSession) {
+		setCache(PERSONALIZE_CACHE_USERID, newUserId);
+	}
+};

package/src/providers/personalize/utils/constants.ts

@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const DEFAULT_PERSONALIZE_CONFIG = {
+	flushSize: 5,
+	flushInterval: 5_000,
+};
+
+export const PERSONALIZE_FLUSH_SIZE_MAX = 10;
+
+export const IDENTIFY_EVENT_TYPE = 'Identify';
+export const MEDIA_AUTO_TRACK_EVENT_TYPE = 'MediaAutoTrack';

package/src/providers/personalize/utils/getEventBuffer.ts

@@ -0,0 +1,135 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	AWSCredentials,
+	haveCredentialsChanged,
+} from '@aws-amplify/core/internals/utils';
+import {
+	PersonalizeEventsClient,
+	PutEventsCommand,
+} from '@aws-sdk/client-personalize-events';
+
+import { EventBuffer, IAnalyticsClient, groupBy } from '../../../utils';
+import { PersonalizeBufferConfig, PersonalizeBufferEvent } from '../types';
+
+/**
+ * These Records hold cached event buffers and AWS clients.
+ * The hash key is determined by the region and session,
+ * consisting of a combined value comprising [region, sessionToken, identityId].
+ *
+ * Only one active session should exist at any given moment.
+ * When a new session is initiated, the previous ones should be released.
+ * */
+const eventBufferMap: Record<string, EventBuffer<PersonalizeBufferEvent>> = {};
+const cachedClients: Record<string, [PersonalizeEventsClient, AWSCredentials]> =
+	{};
+
+const DELIMITER = '#';
+
+const createPutEventsCommand = (
+	ids: string,
+	events: PersonalizeBufferEvent[],
+): PutEventsCommand => {
+	const [trackingId, sessionId, userId] = ids.split(DELIMITER);
+
+	return new PutEventsCommand({
+		trackingId,
+		sessionId,
+		userId,
+		eventList: events.map(event => ({
+			eventId: event.event.eventId,
+			eventType: event.event.eventType,
+			properties: JSON.stringify(event.event.properties),
+			sentAt: new Date(event.timestamp),
+		})),
+	});
+};
+
+const submitEvents = async (
+	events: PersonalizeBufferEvent[],
+	client: PersonalizeEventsClient,
+): Promise<PersonalizeBufferEvent[]> => {
+	const groupedByIds = Object.entries(
+		groupBy(
+			event =>
+				[event.trackingId, event.sessionId, event.userId]
+					.filter(id => !!id)
+					.join(DELIMITER),
+			events,
+		),
+	);
+
+	const requests = groupedByIds
+		.map(([ids, groupedEvents]) => createPutEventsCommand(ids, groupedEvents))
+		.map(command => client.send(command));
+
+	await Promise.allSettled(requests);
+
+	return Promise.resolve([]);
+};
+
+export const getEventBuffer = ({
+	region,
+	flushSize,
+	flushInterval,
+	bufferSize,
+	credentials,
+	identityId,
+	userAgentValue,
+}: PersonalizeBufferConfig): EventBuffer<PersonalizeBufferEvent> => {
+	const sessionIdentityKey = [region, identityId].filter(x => !!x).join('-');
+	const [cachedClient, cachedCredentials] =
+		cachedClients[sessionIdentityKey] ?? [];
+	let credentialsHaveChanged = false;
+
+	// Check if credentials have changed for the cached client
+	if (cachedClient) {
+		credentialsHaveChanged = haveCredentialsChanged(
+			cachedCredentials,
+			credentials,
+		);
+	}
+
+	if (!eventBufferMap[sessionIdentityKey] || credentialsHaveChanged) {
+		const getClient = (): IAnalyticsClient<PersonalizeBufferEvent> => {
+			if (!cachedClient || credentialsHaveChanged) {
+				cachedClients[sessionIdentityKey] = [
+					new PersonalizeEventsClient({
+						region,
+						credentials,
+						customUserAgent: userAgentValue,
+					}),
+					credentials,
+				];
+			}
+
+			const [personalizeClient] = cachedClients[sessionIdentityKey];
+
+			return events => submitEvents(events, personalizeClient);
+		};
+
+		eventBufferMap[sessionIdentityKey] =
+			new EventBuffer<PersonalizeBufferEvent>(
+				{
+					bufferSize,
+					flushSize,
+					flushInterval,
+				},
+				getClient,
+			);
+
+		const releaseSessionKeys = Object.keys(eventBufferMap).filter(
+			key => key !== sessionIdentityKey,
+		);
+		for (const releaseSessionKey of releaseSessionKeys) {
+			eventBufferMap[releaseSessionKey].flushAll().finally(() => {
+				eventBufferMap[releaseSessionKey].release();
+				delete eventBufferMap[releaseSessionKey];
+				delete cachedClients[releaseSessionKey];
+			});
+		}
+	}
+
+	return eventBufferMap[sessionIdentityKey];
+};

package/src/providers/personalize/utils/index.ts

@@ -0,0 +1,11 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { getEventBuffer } from './getEventBuffer';
+export { resolveConfig } from './resolveConfig';
+export { autoTrackMedia } from './autoTrackMedia';
+export { resolveCachedSession, updateCachedSession } from './cachedSession';
+export {
+	DEFAULT_PERSONALIZE_CONFIG,
+	PERSONALIZE_FLUSH_SIZE_MAX,
+} from './constants';

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

@@ -0,0 +1,46 @@
+// 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';
+
+import {
+	DEFAULT_PERSONALIZE_CONFIG,
+	PERSONALIZE_FLUSH_SIZE_MAX,
+} from './constants';
+
+export const resolveConfig = () => {
+	const config = Amplify.getConfig().Analytics?.Personalize;
+	const {
+		region,
+		trackingId,
+		flushSize = DEFAULT_PERSONALIZE_CONFIG.flushSize,
+		flushInterval = DEFAULT_PERSONALIZE_CONFIG.flushInterval,
+	} = {
+		...DEFAULT_PERSONALIZE_CONFIG,
+		...config,
+	};
+
+	assertValidationError(!!region, AnalyticsValidationErrorCode.NoRegion);
+	assertValidationError(
+		!!trackingId,
+		AnalyticsValidationErrorCode.NoTrackingId,
+	);
+	assertValidationError(
+		flushSize <= PERSONALIZE_FLUSH_SIZE_MAX,
+		AnalyticsValidationErrorCode.InvalidFlushSize,
+		`FlushSize for Personalize should be less or equal than ${PERSONALIZE_FLUSH_SIZE_MAX}`,
+	);
+
+	return {
+		region,
+		trackingId,
+		bufferSize: flushSize + 1,
+		flushSize,
+		flushInterval,
+	};
+};