@24i/bigscreen-sdk 1.0.7-alpha.2159-1 → 1.0.7-alpha.2161

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@24i/bigscreen-sdk",
-    "version": "1.0.7-alpha.2159-1",
+    "version": "1.0.7-alpha.2161",
     "description": "SmartApps BIGscreen SDK monorepo",
     "main": "index.js",
     "scripts": {
@@ -40,6 +40,7 @@
         "@24i/player-base": "6.10.0",
         "@24i/smartapps-datalayer": "3.0.3",
         "@sentry/browser": "^7.12.1",
+        "@types/gtag.js": "^0.0.12",
         "@types/prop-types": "^15.7.5",
         "@types/scheduler": "^0.16.2",
         "csstype": "^3.1.1",
@@ -80,6 +81,10 @@
     },
     "exports": {
         "./adobe-heartbeat": "./packages/adobe-heartbeat/src/index.ts",
+        "./analytics/interface": "./packages/analytics/src/interface.ts",
+        "./analytics/ConsoleAnalytics": "./packages/analytics/src/clients/ConsoleAnalytics/index.ts",
+        "./analytics/GoogleAnalytics": "./packages/analytics/src/clients/GoogleAnalytics/index.ts",
+        "./analytics": "./packages/analytics/src/index.ts",
         "./animations/mock": "./packages/animations/src/__mocks__/JSAnimations.ts",
         "./animations": "./packages/animations/src/index.ts",
         "./announcement-banner": "./packages/announcement-banner/src/index.ts",

package/packages/analytics/README.md

@@ -0,0 +1,65 @@
+---
+id: README
+title: Analytics
+hide_title: true
+sidebar_label: Analytics
+---
+
+# Analytics
+This package contains general implementation of analytics and implementation for these clients:
+- ConsoleAnalytics - debugging analytics that dump triggers to the console.
+
+## analytics
+Single instance `analytics` is a general manager for analytics clients. It provides a unified
+interface for use by the app without it needing to know any specific analytics client implementation.
+It also adds some general app info to each trigger call (e.g. resolution, language, etc.)
+
+## A
+`A` is a shorthand utility function to simplify sending analytics information. It allows setting
+a basic payload that is sent with each trigger call and shallowly merged with trigger payload.
+Trigger payload can override values inside this basic payload.
+
+### Usage
+```typescript
+import { A } from '@24i/bigscreen-sdk/analytics';
+
+class DetailScene {
+    a = A.of({ sceneType: SceneType.DETAIL });
+
+    activate(params: RouteParams) {
+        this.a.addToPayload({
+            sceneId: `/detail/${params.assetType}/${params.id}`,
+            sceneName: `Detail - ${data.type} - [unknown]`,
+            asset: undefined,
+        });
+        // ...
+    }
+
+    async loadAndRenderData() {
+        this.a('buffering_start');
+        const data = await dataProvider();
+        this.a.addToPayload({
+            sceneName: `Detail - ${data.type} - ${data.name}`,
+            asset: data,
+        });
+        this.a('buffering_stop');
+        // render
+        this.a('screen_view');
+    }
+}
+```
+It is better to store shorthand `a` function inside the component instance. Some scenes can be
+instantiated multiple times by the router (e.g. Browse in WL). Therefore it cannot use a single
+instance from a local `./analytics'` import for example.
+
+## Clients
+Analytics client is the integration to the specific analytics provider (e.g. Google Analytics).
+It needs to implement `AnalyticsClient` interface and register its instance to receive the events.
+
+Clients have to opt-in to events they wish to listen to. This can be done by listing all events or by
+using a regular expression.
+
+```typescript
+analytics.addClient(new GoogleAnalytics(), ['screen_view', 'buffering_start', 'buffering_stop']);
+analytics.addClient(new ConsoleAnalytics(), /.*/);
+```

package/packages/analytics/src/A.ts

@@ -0,0 +1,51 @@
+import { analytics } from './Analytics';
+import { AnalyticsEventsMap, AnalyticsEventsNames, AnyPayload, AFunction } from './interface';
+
+interface PrivateAFunction extends AFunction {
+    payload: AnyPayload,
+}
+
+export class A {
+    /**
+     * Creates an analytics 'a' function for easy triggering of events.
+     * @param payload basic payload that is added to each payload of the returned
+     * function call.
+     * @returns a function for triggering analytics events
+     * @example
+     * ```typescript
+     * // Creates a function and sets the basic payload.
+     * const a = A.of({ sceneType: 'HOME', sceneId: 'home' });
+     *
+     * // Sends 'screen_view' event with the basic payload.
+     * a('screen_view');
+     *
+     * // Sends 'buffering_stop' with shallow merge of the basic payload and { asset } object.
+     * a('buffering_stop', { asset });
+     * ```
+     */
+    static of(payload: AnyPayload) {
+        const a: PrivateAFunction = (<
+            EventName extends AnalyticsEventsNames,
+            P extends Partial<Parameters<AnalyticsEventsMap[EventName]>[0]>,
+        >(eventName: EventName, eventPayload: P) => {
+            analytics.triggerEvent(eventName, {
+                ...a.payload,
+                ...eventPayload,
+            } as unknown as Parameters<AnalyticsEventsMap[EventName]>[0]);
+        }) as unknown as PrivateAFunction;
+        a.payload = payload;
+        a.addToPayload = (extendedPayload: AnyPayload) => {
+            a.payload = {
+                ...a.payload,
+                ...extendedPayload,
+            };
+        };
+        a.setPayload = (newPayload: AnyPayload) => {
+            a.payload = newPayload;
+        };
+        a.clearPayload = () => {
+            a.payload = {};
+        };
+        return a as AFunction;
+    }
+}

package/packages/analytics/src/Analytics.ts

@@ -0,0 +1,114 @@
+import { EventsManager } from '@24i/bigscreen-sdk/events-manager';
+import { i18n } from '@24i/bigscreen-sdk/i18n';
+import type {
+    AnalyticsEventsMap,
+    AnalyticsEventsNames,
+    AnalyticsClient,
+    GeneralAppData,
+    AppInfo,
+    UserInfo,
+} from './interface';
+import { EVENT_NAMES, ONLY_ONCE_EVENTS, UNREPEATABLE_EVENTS } from './constants';
+
+class Analytics {
+    private events = new EventsManager<AnalyticsEventsMap>();
+
+    private onlyOnceAlreadySent: string[] = [];
+
+    private lastPayloadForEvent: Partial<Record<AnalyticsEventsNames, string>> = {};
+
+    private clients: Record<string, {
+        client: AnalyticsClient
+        registeredEvents: Partial<Record<AnalyticsEventsNames, Function>>,
+    }> = {};
+
+    private generalAppData: Partial<GeneralAppData> = {
+        language: i18n.getLanguage(),
+        resolution: `${window.innerWidth}x${window.innerHeight}`,
+    };
+
+    private appInfo: Partial<AppInfo> = {};
+
+    private userInfo: Partial<UserInfo> = {};
+
+    constructor() {
+        i18n.addEventListener('languagechange', this.onLanguageChange);
+    }
+
+    addClient(client: AnalyticsClient, events: AnalyticsEventsNames[] | RegExp) {
+        if (this.clients[client.name]) {
+            throw new Error(`${client.name} analytics client is already registered.`);
+        }
+        const eventsToRegister = Array.isArray(events)
+            ? events
+            : EVENT_NAMES.filter(events.test.bind(events));
+        const registeredEvents: Partial<Record<AnalyticsEventsNames, Function>> = {};
+        eventsToRegister.forEach((eventName) => {
+            const listener = (payload: any) => {
+                client.onEvent(eventName, payload);
+            };
+            this.events.addEventListener(eventName, listener);
+            registeredEvents[eventName] = listener;
+        });
+        this.clients[client.name] = {
+            client: client,
+            registeredEvents,
+        };
+    }
+
+    removeClient(client: AnalyticsClient) {
+        if (this.clients[client.name]) {
+            const { registeredEvents } = this.clients[client.name];
+            Object.keys(registeredEvents).forEach((eventName) => {
+                // @ts-ignore - specific payload typing
+                this.events.removeEventListener(eventName, registeredEvents[eventName]!);
+            });
+            delete this.clients[client.name];
+        }
+    }
+
+    triggerEvent<Event extends AnalyticsEventsNames>(
+        event: Event,
+        triggerPayload: Parameters<AnalyticsEventsMap[Event]>[0] = undefined,
+    ) {
+        const fullPayload = {
+            ...this.generalAppData,
+            ...this.appInfo,
+            ...this.userInfo,
+            ...triggerPayload,
+        };
+        if (ONLY_ONCE_EVENTS.includes(event)) {
+            const serializedPayload = `${event} - ${JSON.stringify(fullPayload)}`;
+            if (this.onlyOnceAlreadySent.includes(serializedPayload)) return;
+            this.onlyOnceAlreadySent.push(serializedPayload);
+        }
+        if (UNREPEATABLE_EVENTS.includes(event)) {
+            const serializedPayload = JSON.stringify(fullPayload);
+            if (this.lastPayloadForEvent[event] === serializedPayload) return;
+            this.lastPayloadForEvent[event] = serializedPayload;
+        }
+        this.tryFillUpMissingData();
+        // @ts-ignore - payload typing
+        this.events.triggerEvent(event, fullPayload);
+    }
+
+    setAppInfo(data: Partial<AppInfo>) {
+        this.appInfo = data;
+    }
+
+    setUserInfo(data: Partial<UserInfo>) {
+        this.userInfo = data;
+    }
+
+    private onLanguageChange = () => {
+        this.generalAppData.language = i18n.getLanguage();
+    };
+
+    private tryFillUpMissingData() {
+        if (!this.generalAppData.language) {
+            this.generalAppData.language = i18n.getLanguage();
+        }
+    }
+}
+
+export const analytics = new Analytics();

package/packages/analytics/src/analyticsOnScroll.ts

@@ -0,0 +1,11 @@
+import { AFunction } from './interface';
+
+export const analyticsOnScroll = (a: AFunction, itemsTotal: number) => (_: any, index: number) => {
+    const percent = (index + 1) / itemsTotal;
+    /* eslint-disable no-magic-numbers */
+    if (percent >= 0.9) a('scroll_90');
+    else if (percent >= 0.75) a('scroll_75');
+    else if (percent >= 0.50) a('scroll_50');
+    else if (percent >= 0.25) a('scroll_25');
+    /* eslint-enable no-magic-numbers */
+};

package/packages/analytics/src/clients/ConsoleAnalytics/ConsoleAnalytics.ts

@@ -0,0 +1,12 @@
+import { AnalyticsClient } from '../../interface';
+
+/**
+ * Simple debugging client that dumps all triggers to the console.
+ */
+export class ConsoleAnalytics implements AnalyticsClient {
+    name = 'ConsoleAnalytics';
+
+    onEvent(eventName: string, payload: any) {
+        console.info('CA: ', eventName, payload);
+    }
+}

package/packages/analytics/src/clients/ConsoleAnalytics/index.ts

@@ -0,0 +1 @@
+export { ConsoleAnalytics } from './ConsoleAnalytics';

package/packages/analytics/src/clients/GoogleAnalytics/GoogleAnalytics.ts

@@ -0,0 +1,84 @@
+import { Storage } from '@24i/bigscreen-sdk/storage';
+import { debounce } from '@24i/bigscreen-sdk/utils/debounce';
+import { generateUuid } from '@24i/bigscreen-sdk/utils/generateUuid';
+import type { AnalyticsClient, AnalyticsEventsMap } from '../../interface';
+import { mapPayload } from './mapPayload';
+import { TRIGGER_NAME_TO_GA_EVENTS } from './constants';
+import { GAEventsNames } from './interface';
+
+const SEND_DEBOUNCE_MS = 5000;
+const MAX_QUEUE_LENGTH = 10;
+
+const GA_CLIENT_ID = 'GA_client_id';
+
+const getGAUrl = (id: string, secret: string) => (
+    // You can use the following URL for debugging if the events are not getting collected.
+    // `https://www.google-analytics.com/debug/mp/collect?measurement_id=${id}&api_secret=${secret}`
+    `https://www.google-analytics.com/mp/collect?measurement_id=${id}&api_secret=${secret}`
+);
+
+export class GoogleAnalytics implements AnalyticsClient {
+    name = 'GoogleAnalytics';
+
+    clientId = '';
+
+    sessionId = generateUuid();
+
+    a24iOperational = false;
+
+    eventsQueue: { name: GAEventsNames, params: Record<string, any> }[] = [];
+
+    constructor(private id: string, private secret: string) {
+        this.init();
+    }
+
+    async init() {
+        this.clientId = await Storage.getItem(GA_CLIENT_ID) ?? '';
+        if (!this.clientId) {
+            this.clientId = generateUuid();
+            await Storage.setItem(GA_CLIENT_ID, this.clientId);
+        }
+    }
+
+    onEvent<Event extends keyof AnalyticsEventsMap>(
+        triggerName: Event,
+        payload: Parameters<AnalyticsEventsMap[Event]>,
+    ): void {
+        const events = TRIGGER_NAME_TO_GA_EVENTS[triggerName];
+        events.forEach(async (event) => {
+            if (event === 'a24i_operational' && !this.shouldContinueWithA24iOperational()) return;
+            const gtagPayload = mapPayload(event, triggerName, this.sessionId, payload);
+            this.send(event, gtagPayload);
+        });
+    }
+
+    private send(name: GAEventsNames, params: Record<string, any>) {
+        this.eventsQueue.push({ name, params });
+        if (this.eventsQueue.length >= MAX_QUEUE_LENGTH) {
+            this.sendQueue();
+        } else {
+            this.sendQueueWithDelay();
+        }
+    }
+
+    private sendQueue = () => {
+        const body = JSON.stringify({
+            client_id: this.clientId,
+            events: this.eventsQueue,
+        });
+        this.eventsQueue.length = 0;
+        try {
+            fetch(getGAUrl(this.id, this.secret), { method: 'POST', body });
+        } catch (e) {
+            // Effort to send was made.
+        }
+    };
+
+    private sendQueueWithDelay = debounce(this.sendQueue, SEND_DEBOUNCE_MS);
+
+    private shouldContinueWithA24iOperational() {
+        const { a24iOperational } = this;
+        if (!a24iOperational) this.a24iOperational = true;
+        return !a24iOperational;
+    }
+}

package/packages/analytics/src/clients/GoogleAnalytics/constants.ts

@@ -0,0 +1,40 @@
+import { AnalyticsEventsNames } from '../../interface';
+import { GAEventsNames } from './interface';
+
+export const TRIGGER_NAME_TO_GA_EVENTS: Record<AnalyticsEventsNames, GAEventsNames[]> = {
+    // App
+    'app_close': ['app_close', 'video_progress'],
+
+    // Data loading / Player buffering
+    'buffering_start': ['buffering_start'],
+    'buffering_stop': ['buffering_start'],
+
+    // Heartbeat
+    'heartbeat_5': ['a24i_content'],
+
+    // Playback
+    'playback_10': ['video_progress'],
+    'playback_25': ['video_progress'],
+    'playback_50': ['video_progress'],
+    'playback_75': ['video_progress'],
+    'playback_90': ['video_progress'],
+    'playback_pause': ['video_progress'],
+    'playback_start': ['video_start'],
+    'playback_stop': ['video_progress'],
+
+    // Player
+    'player_close': ['a24i_content', 'video_progress'],
+    'player_open': ['a24i_content'],
+
+    // Scenes
+    'screen_view': [
+        'page_view',
+        'a24i_operational',
+    ],
+
+    // Scrolling in scene
+    'scroll_25': ['scroll'],
+    'scroll_50': ['scroll'],
+    'scroll_75': ['scroll'],
+    'scroll_90': ['scroll'],
+};

package/packages/analytics/src/clients/GoogleAnalytics/index.ts

@@ -0,0 +1 @@
+export { GoogleAnalytics } from './GoogleAnalytics';

package/packages/analytics/src/clients/GoogleAnalytics/interface.ts

@@ -0,0 +1,10 @@
+export type GAEventsNames = (
+    | 'a24i_content'
+    | 'a24i_operational'
+    | 'app_close'
+    | 'buffering_start'
+    | 'page_view'
+    | 'scroll'
+    | 'video_progress'
+    | 'video_start'
+);

package/packages/analytics/src/clients/GoogleAnalytics/mapPayload.ts

@@ -0,0 +1,76 @@
+import type {
+    AnalyticsEventsNames,
+    GeneralAppData,
+    SceneInfo,
+    AppInfo,
+    UserInfo,
+} from '../../interface';
+import type { GAEventsNames } from './interface';
+
+const MILI_TO_MICRO = 10;
+
+const camelToSnake = (name: string) => (
+    name.replace(/[A-Z]/g, (match) => `_${match.toLowerCase()}`)
+);
+
+const addKeyIfExists = <T extends string>(
+    keyName: T,
+    payload: { [key in typeof keyName]?: any },
+    gtagPayload: Record<string, any>,
+) => {
+    if (payload[keyName]) gtagPayload[camelToSnake(keyName)] = payload[keyName];
+};
+
+const mapGeneralData = (payload: Partial<GeneralAppData>) => {
+    const gtagPayloadGeneralData: Partial<GeneralAppData> = {};
+    addKeyIfExists('language', payload, gtagPayloadGeneralData);
+    addKeyIfExists('resolution', payload, gtagPayloadGeneralData);
+    return gtagPayloadGeneralData;
+};
+
+const mapSceneInfo = (payload: Partial<SceneInfo>) => {
+    const gtagPayloadSceneInfo: Partial<SceneInfo> = {};
+    addKeyIfExists('sceneId', payload, gtagPayloadSceneInfo);
+    addKeyIfExists('sceneType', payload, gtagPayloadSceneInfo);
+    addKeyIfExists('sceneName', payload, gtagPayloadSceneInfo);
+    return gtagPayloadSceneInfo;
+};
+
+const mapAppData = (payload: Partial<AppInfo>) => {
+    const gtagPayloadAppInfo: Partial<AppInfo> = {};
+    addKeyIfExists('applicationId', payload, gtagPayloadAppInfo);
+    addKeyIfExists('serviceId', payload, gtagPayloadAppInfo);
+    return gtagPayloadAppInfo;
+};
+
+const mapUserData = (payload: Partial<UserInfo>) => {
+    const gtagPayloadUserInfo: Partial<UserInfo> = {};
+    addKeyIfExists('userId', payload, gtagPayloadUserInfo);
+    return gtagPayloadUserInfo;
+};
+
+export const mapPayload = (
+    eventName: GAEventsNames,
+    triggerName: AnalyticsEventsNames,
+    sessionId: string,
+    payload: Record<string, any>,
+) => {
+    let gtagPayload: Record<string, any> = {
+        session_id: sessionId,
+        event_trigger: triggerName,
+        timestamp_micros: Date.now() * MILI_TO_MICRO,
+        ...mapGeneralData(payload),
+        ...mapAppData(payload),
+        ...mapUserData(payload),
+    };
+    if (eventName === 'page_view' || eventName === 'buffering_start') {
+        gtagPayload = {
+            ...gtagPayload,
+            ...mapSceneInfo(payload),
+        };
+    }
+    if (eventName === 'scroll') {
+        gtagPayload.percent_scroll = parseInt(triggerName.split('_')[1], 10);
+    }
+    return gtagPayload;
+};

package/packages/analytics/src/constants.ts

@@ -0,0 +1,56 @@
+import { AnalyticsEventsNames } from './interface';
+
+export const EVENT_NAMES = [
+    // App
+    'app_close',
+
+    // Data loading / Player buffering
+    'buffering_start',
+    'buffering_stop',
+
+    // Heartbeat
+    'heartbeat_5',
+
+    // Playback
+    'playback_10',
+    'playback_25',
+    'playback_50',
+    'playback_75',
+    'playback_90',
+    'playback_pause',
+    'playback_start',
+    'playback_stop',
+
+    // Player
+    'player_close',
+    'player_open',
+
+    // Scenes
+    'screen_view',
+
+    // Scrolling in scene
+    'scroll_25',
+    'scroll_50',
+    'scroll_75',
+    'scroll_90',
+] as const;
+
+export const ONLY_ONCE_EVENTS: AnalyticsEventsNames[] = [
+    // Playback
+    'playback_10',
+    'playback_25',
+    'playback_50',
+    'playback_75',
+    'playback_90',
+
+    // Scrolling in scene
+    'scroll_25',
+    'scroll_50',
+    'scroll_75',
+    'scroll_90',
+];
+
+export const UNREPEATABLE_EVENTS: AnalyticsEventsNames[] = [
+    // Scenes
+    'screen_view',
+];

package/packages/analytics/src/index.ts

@@ -0,0 +1,3 @@
+export { analytics } from './Analytics';
+export { A } from './A';
+export { analyticsOnScroll } from './analyticsOnScroll';

package/packages/analytics/src/interface.ts

@@ -0,0 +1,82 @@
+export type SceneInfo = {
+    sceneId: string,
+    sceneType: string,
+    sceneName: string,
+};
+
+export type AppInfo = {
+    applicationId: string,
+    serviceId: string,
+};
+
+export type UserInfo = {
+    userId: string,
+};
+
+export type GeneralAppData = {
+    language: string,
+    resolution: string,
+};
+
+/**
+ * List of all tracked events.
+ */
+export type AnalyticsEventsMap = {
+    // App
+    'app_close': (payload: void) => void,
+
+    // Data loading / Player buffering
+    'buffering_start': (payload: SceneInfo) => void,
+    'buffering_stop': (payload: SceneInfo) => void,
+
+    // Heartbeat
+    'heartbeat_5': (payload: void) => void,
+
+    // Playback
+    'playback_10': (payload: void) => void,
+    'playback_25': (payload: void) => void,
+    'playback_50': (payload: void) => void,
+    'playback_75': (payload: void) => void,
+    'playback_90': (payload: void) => void,
+    'playback_pause': (payload: void) => void,
+    'playback_start': (payload: void) => void,
+    'playback_stop': (payload: void) => void,
+
+    // Player
+    'player_close': (payload: void) => void,
+    'player_open': (payload: void) => void,
+
+    // Scenes
+    'screen_view': (payload: SceneInfo) => void,
+
+    // Scrolling in scene
+    'scroll_25': (payload: SceneInfo) => void,
+    'scroll_50': (payload: SceneInfo) => void,
+    'scroll_75': (payload: SceneInfo) => void,
+    'scroll_90': (payload: SceneInfo) => void,
+};
+
+export type AnalyticsEventsNames = keyof AnalyticsEventsMap;
+
+export interface AnalyticsClient {
+    name: string,
+    onEvent<Event extends keyof AnalyticsEventsMap>(
+        eventName: Event,
+        payload: Parameters<AnalyticsEventsMap[Event]>,
+    ): void;
+}
+
+export type AnyPayload = Record<string, any>;
+
+export interface AFunction {
+    <
+        EventName extends AnalyticsEventsNames,
+        P extends Partial<Parameters<AnalyticsEventsMap[EventName]>[0]>,
+    >(eventName: EventName, payload?: P): void,
+
+    addToPayload(payload: AnyPayload): void,
+
+    setPayload(payload: AnyPayload): void,
+
+    clearPayload(): void,
+}