@aws-amplify/analytics 7.0.1-console-preview.11cf989.0 → 7.0.1-console-preview.4ae78ed.0

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

@@ -0,0 +1,231 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { EventBuffer } from '../../../utils';
+import { PersonalizeBufferEvent, PersonalizeEvent } from '../types';
+import { ConsoleLogger, isBrowser } from '@aws-amplify/core/internals/utils';
+
+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',
+}
+
+interface IRecordEvent {
+	(eventType: string, properties: Record<string, unknown>): void;
+}
+
+type 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));
+
+	// @ts-ignore
+	window.onYouTubeIframeAPIReady = () => {
+		// @ts-ignore
+		delete window.onYouTubeIframeAPIReady;
+
+		// @ts-ignore
+		player = new window.YT.Player(element.id, {
+			events: {
+				onStateChange: (event: any) => {
+					const iframeEventMapping = {
+						0: EVENT_TYPE.ENDED,
+						1: EVENT_TYPE.PLAY,
+						2: EVENT_TYPE.PAUSE,
+					};
+					// @ts-ignore
+					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(r => setTimeout(r, 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 await 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,67 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Cache } from '@aws-amplify/core';
+import { isBrowser } from '@aws-amplify/core/internals/utils';
+import { v4 as uuid } from 'uuid';
+
+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 = (trackingId: string) => {
+	let sessionId: string | undefined = getCache(PERSONALIZE_CACHE_SESSIONID);
+	if (!sessionId) {
+		sessionId = uuid();
+		setCache(PERSONALIZE_CACHE_SESSIONID, sessionId);
+	}
+
+	const userId: string | undefined = 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 = uuid();
+		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,111 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { EventBuffer, groupBy, IAnalyticsClient } from '../../../utils';
+import { PersonalizeBufferConfig, PersonalizeBufferEvent } from '../types';
+import {
+	PersonalizeEventsClient,
+	PutEventsCommand,
+} from '@aws-sdk/client-personalize-events';
+
+/**
+ * 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> = {};
+
+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, events]) => createPutEventsCommand(ids, events))
+		.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 { sessionToken } = credentials;
+	const sessionIdentityKey = [region, sessionToken, identityId]
+		.filter(x => !!x)
+		.join('-');
+
+	if (!eventBufferMap[sessionIdentityKey]) {
+		const getClient = (): IAnalyticsClient<PersonalizeBufferEvent> => {
+			if (!cachedClients[sessionIdentityKey]) {
+				cachedClients[sessionIdentityKey] = new PersonalizeEventsClient({
+					region,
+					credentials,
+					customUserAgent: userAgentValue,
+				});
+			}
+			return events => submitEvents(events, cachedClients[sessionIdentityKey]);
+		};
+
+		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].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,41 @@
+// 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 './';
+
+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,
+	};
+};

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

@@ -0,0 +1,34 @@
+// 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,
+	ConsoleLogger,
+} from '@aws-amplify/core/internals/utils';
+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

@@ -28,7 +28,7 @@ import { resolveConfig, resolveCredentials } from '../utils';
  * await identifyUser({
  *     userId,
  *     userProfile: {
- *         email: [userEmail]
+ *         email: 'userEmail@example.com'
  *         customProperties: {
  *             phoneNumber: ['555-555-5555'],
  *         },
@@ -42,7 +42,7 @@ import { resolveConfig, resolveCredentials } from '../utils';
  * await identifyUser({
  *     userId,
  *     userProfile: {
- *         email: [userEmail]
+ *         email: 'userEmail@example.com'
  *         customProperties: {
  *             phoneNumber: ['555-555-5555'],
  *         },
@@ -70,6 +70,6 @@ export const identifyUser = async ({
 		userAttributes,
 		userId,
 		userProfile,
-		userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.UpdateEndpoint),
+		userAgentValue: getAnalyticsUserAgentString(AnalyticsAction.IdentifyUser),
 	});
 };

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

@@ -3,3 +3,4 @@
 
 export { record } from './record';
 export { identifyUser } from './identifyUser';
+export { flushEvents } from './flushEvents';

package/src/providers/pinpoint/index.ts

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

package/src/types/index.ts

@@ -16,3 +16,5 @@ export {
 export { AnalyticsServiceOptions } from './options';
 
 export { AnalyticsIdentifyUserInput } from './inputs';
+
+export { KinesisStream, KinesisShard, KinesisEventData } from './kinesis';

package/src/types/kinesis.ts

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export type KinesisStream = {
+	region: string;
+	streamName: string;
+};
+
+export type KinesisShard = KinesisStream & {
+	partitionKey: string;
+};
+
+export type KinesisEventData = Record<string, unknown> | Uint8Array;

package/src/utils/eventBuffer/EventBuffer.ts

@@ -0,0 +1,84 @@
+// 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 { EventBufferConfig, IAnalyticsClient } from './';
+
+const logger = new ConsoleLogger('EventBuffer');
+
+export class EventBuffer<T> {
+	private list: T[];
+	private readonly config: EventBufferConfig;
+	private getAnalyticsClient: () => IAnalyticsClient<T>;
+
+	private timer?: ReturnType<typeof setInterval>;
+
+	constructor(
+		config: EventBufferConfig,
+		getAnalyticsClient: () => IAnalyticsClient<T>
+	) {
+		this.list = [];
+		this.config = config;
+		this.getAnalyticsClient = getAnalyticsClient;
+		this.startEventLoop();
+	}
+
+	public append(...events: T[]) {
+		for (const event of events) {
+			if (this.list.length + 1 > this.config.bufferSize) {
+				logger.debug(
+					`Exceed ${typeof event} event buffer limits, event dropped`
+				);
+				continue;
+			}
+			this.list.push(event);
+		}
+	}
+
+	public flushAll(): Promise<void> {
+		return this.submitEvents(this.list.length);
+	}
+
+	public release() {
+		this.list = [];
+		if (this.timer) {
+			clearInterval(this.timer);
+		}
+	}
+
+	public get length() {
+		return this.list.length;
+	}
+
+	private head(count: number) {
+		return this.list.splice(0, count);
+	}
+
+	private insertAtBeginning(...data: T[]) {
+		this.list.unshift(...data);
+	}
+
+	private startEventLoop() {
+		if (this.timer) {
+			clearInterval(this.timer);
+		}
+
+		const { flushSize, flushInterval } = this.config;
+		setInterval(() => {
+			this.submitEvents(flushSize);
+		}, flushInterval);
+	}
+
+	private submitEvents(count: number): Promise<void> {
+		const events = this.head(count);
+		if (events.length === 0) {
+			return Promise.resolve();
+		}
+
+		return this.getAnalyticsClient()(events).then(result => {
+			if (result.length > 0) {
+				this.insertAtBeginning(...result);
+			}
+		});
+	}
+}

package/src/utils/eventBuffer/index.ts

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

package/src/utils/eventBuffer/types.ts

@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export interface IAnalyticsClient<T> {
+	(events: T[]): Promise<T[]>;
+}
+
+export type EventBufferConfig = {
+	flushSize: number;
+	flushInterval: number;
+	bufferSize: number;
+};

package/src/utils/groupBy.ts

@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export const groupBy = <T>(
+	getGroupId: (x: T) => string,
+	list: T[]
+): Record<string, T[]> => {
+	return list.reduce((result, current) => {
+		const groupId = getGroupId(current);
+		return { ...result, [groupId]: [...(result[groupId] ?? []), current] };
+	}, {} as Record<string, T[]>);
+};