@maestro_io/maestro-web-sdk 5.0.0 → 5.1.1

package/dist/src/services/InsightsService/InsightsPayloadBuilder.d.ts

@@ -0,0 +1,279 @@
+import { ICacheManager } from '@/external/ports/cacheManager';
+import InsightsService from './InsightsService';
+import { PageConfig } from '../StaticService/types';
+type EventData = {
+    metadata?: Record<string, unknown>;
+    ontology: {
+        kingdom: string;
+        phylum: string;
+        class?: string;
+        order?: string;
+        family?: string;
+        genus?: string;
+        species?: string;
+    };
+};
+export default class InsightsPayloadBuilder {
+    currentTime: number;
+    serverOffsetTime: number;
+    insightsService: InsightsService;
+    cacheManager: ICacheManager;
+    pageConfig: PageConfig | null;
+    constructor();
+    getPayload(event: EventData): Promise<{
+        /**
+         * @description Event Domain. NAMESPACE env var.
+         * @example maestro
+         */
+        e_d: string;
+        /**
+         * @description Event stringified metadata. defaults to null.
+         * @example "{\"key\":\"value\"}"
+         */
+        e_m: string | null;
+        /**
+         * @description Event time accounting for offset.
+         */
+        e_t: number;
+        /**
+         * @description Event URL. defaults to undefined.
+         */
+        e_u: string;
+        /**
+         * @description Event ontology kingdom. This is the highest level of the ontology and can be used to identify the event type.
+         * @example 'panel', 'engage', 'espn_key_plays'
+         */
+        e0: string;
+        /**
+         * @description Event phylum.
+         * @example 'view', 'click', 'play clip'
+         */
+        e1: string;
+        /**
+         * @description Event class.
+         * @example 'panel_type'
+         */
+        e2: string | undefined;
+        /**
+         * @description Event order.
+         * @example 'panel_id'
+         */
+        e3: string | undefined;
+        /**
+         * @description Event family.
+         * @example 'panel_name'
+         */
+        e4: string | undefined;
+        /**
+         * @description Event genus. This is a more specific level of the ontology and can be used to identify the event type.
+         */
+        e5: string | undefined;
+        /**
+         * @description Event species. This is the most specific level of the ontology and can be used to identify the event type.
+         */
+        e6: string | undefined;
+        /**
+         * @description Current timestamp.
+         */
+        t: number;
+        /**
+         * @description User avatar URL. Stored in user profile. defaults to null
+         * @example GET 'https://api.maestro.io/userprofile/v1'
+         */
+        u_a: null;
+        /**
+         * @description User account created date in milliseconds since epoch. defaults to null
+         * @example account.created
+         */
+        u_c: null;
+        /**
+         * @description Logged User email. defaults to null
+         * @example account.email
+         */
+        u_e: null;
+        /**
+         * @description Logged User ID. defaults to null
+         * @example account._id
+         */
+        u_id: null;
+        /**
+         * @description Logged User is logged in or not. defaults to false
+         */
+        u_li: boolean;
+        /**
+         * @description Logged User name. defaults to null
+         * @example account.name
+         */
+        u_n: null;
+        /**
+         * @description Logged User new user or not. Usually we compare server time and account.created. If it was created less than 1 day ago it's a new user. defaults to false
+         * @example Math.abs((serverTime || Date.now()) - account.created) < msIn.day
+         */
+        u_nu: boolean;
+        /**
+         * @description Logged User service. defaults to null
+         * @example account.service
+         */
+        u_s: null;
+        /**
+         * @description Logged User UID. defaults to null
+         * @example account.uid
+         */
+        u_u: null;
+        /**
+         * @description Logged User name. defaults to null
+         * @example account.name
+         */
+        u_un: null;
+        /**
+         * @description Site domain.
+         * @example site.settings.domain.url. 'maestro.tv/site_slug'
+         */
+        si_d: string | undefined;
+        /**
+         * @description Site ID.
+         * @example site._id
+         */
+        si_id: string | undefined;
+        /**
+         * @description Site package ID.
+         * @example `${site.package.id}-sapphire`
+         */
+        si_pid: string;
+        /**
+         * @description Site package version.
+         * @example `${site.package.version}-sapphire`
+         */
+        si_pv: string;
+        /**
+         * @description Site slug.
+         * @example site.slug
+         */
+        si_s: string | undefined;
+        /**
+         * @description Session ID, which can be used to track the session across requests. You might wanna keep this fixed for the session you're in using a local storage or something related.
+         */
+        se_id: string;
+        /**
+         * @description Session created timestamp. Usually set when the first event is fired
+         * @example new Date().getTime()
+         */
+        se_s: number;
+        /**
+         * @description Referrer domain, which can be used to track the domain from which the user came. Defaults to "$direct"
+         * @example 'example.com'.
+         */
+        r_d: string;
+        /**
+         * @description Referrer source, which can be used to track the source from which the user came (queryParam.r). Defaults to null
+         * @example const urlParams = new URLSearchParams(window.location.search);
+         *              urlParams.get('r') || null
+         */
+        r_s: null;
+        /**
+         * @description Referrer URL, which can be used to track the full URL from which the user came. Defaults to "$direct"
+         * @example document.referrer
+         */
+        r_u: string;
+        /**
+         * @description Metadata version, used to track changes in the metadata structure.
+         * @example '1.00.0'
+         */
+        m_iv: string;
+        /**
+         * @description Unique identifier for the insights ID. Stored in site's document.
+         * @example site.settings.services.insights_id
+         */
+        i_id: string | null | undefined;
+        /**
+         * @description Device created timestamp. You might wanna keep this fixed for the device you're in using a local storage or something related
+         * @example new Date().getTime()
+         */
+        d_ct: number;
+        /**
+         * @description New device or not. If you want to keep track of new devices, you can use a local storage or something related
+         * @example localStorage.getItem('isNewDevice') === 'true'
+         */
+        d_nd: boolean;
+        /**
+         * @description Navigator Platform (more Web API specific).
+         * @example 'MacIntel', 'Win32', 'Linux x86_64'
+         * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/platform
+         */
+        d_np: string;
+        /**
+         * @description A unique identifier for the device, which can be used to track the device across sessions. You might wanna save this into a local storage or something related.
+         * @example localStorage.getItem('devicePermanentId') || generateUniqueId()
+         */
+        d_pid: string;
+        /**
+         * @description Device screen height in pixels.
+         * @example window.screen.height
+         */
+        d_sh: number;
+        /**
+         * @description Device screen width in pixels.
+         * @example window.screen.width
+         */
+        d_sw: number;
+        /**
+         * @description Device tab ID, which can be used to track the device across tabs.
+         */
+        d_tid: string;
+        /**
+         * @description Device time in milliseconds since epoch.
+         */
+        d_tim: number;
+        /**
+         * @description Device time offset in milliseconds. You might wanna keep this fixed for the device you're in using a local storage or something related.
+         */
+        d_tof: number;
+        /**
+         * @description Device user agent string.
+         * @example navigator.userAgent ('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3')
+         * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent
+         */
+        d_ua: string;
+        /**
+         * @description MongoDB page collection name (e.g. 'pages')
+         * @example object.collection
+         */
+        p_c: string;
+        /**
+         * @description MongoDB page document ID (e.g. 'pageId')
+         * @example object._id
+         */
+        p_id: string | undefined;
+        /**
+         * @description MongoDB page name (e.g. 'Home', 'Product Page')
+         * @example object.data.name || object.seo.title
+         */
+        p_n: string | undefined;
+        /**
+         * @description MongoDB page slug (e.g. 'home', 'product-page')
+         * @example object.slug
+         */
+        p_s: string | undefined;
+        /**
+         * @description MongoDB page type (e.g. 'landing', 'channel')
+         * @example object.type
+         */
+        p_t: string | undefined;
+    }>;
+    private getEventInsights;
+    private getPageInsights;
+    getDevicePermanentID(): string;
+    private getDeviceCreated;
+    private getTabID;
+    private getDeviceInsights;
+    private randomId;
+    private getDeviceOffset;
+    private getInsightsInsights;
+    private getMetadataInsights;
+    private getReferrerInsights;
+    private getSessionID;
+    private getSessionInsights;
+    private getSiteInsights;
+    private getUserInsights;
+}
+export {};

package/dist/src/services/InsightsService/InsightsPayloadBuilder.js

@@ -0,0 +1,385 @@
+import InsightsService from './InsightsService';
+import LocalStorageCacheManager from '@/external/LocalStorageCacheManager';
+import SDK from '@/index';
+export default class InsightsPayloadBuilder {
+    constructor() {
+        Object.defineProperty(this, "currentTime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "serverOffsetTime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "insightsService", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "cacheManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pageConfig", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.insightsService = new InsightsService();
+        this.cacheManager = new LocalStorageCacheManager();
+    }
+    async getPayload(event) {
+        this.currentTime = Date.now();
+        this.serverOffsetTime = await this.getDeviceOffset();
+        this.pageConfig = SDK.getPageConfig();
+        return {
+            ...this.getPageInsights(),
+            ...this.getDeviceInsights(),
+            ...this.getInsightsInsights(),
+            ...this.getMetadataInsights(),
+            ...this.getReferrerInsights(),
+            ...this.getSessionInsights(),
+            ...this.getSiteInsights(),
+            ...this.getUserInsights(),
+            ...this.getEventInsights(event),
+        };
+    }
+    getEventInsights(eventData) {
+        const ontology = eventData.ontology;
+        return {
+            /**
+             * @description Event Domain. NAMESPACE env var.
+             * @example maestro
+             */
+            e_d: 'maestro',
+            /**
+             * @description Event stringified metadata. defaults to null.
+             * @example "{\"key\":\"value\"}"
+             */
+            e_m: Object.values(eventData.metadata || {}).length > 0
+                ? JSON.stringify(eventData.metadata)
+                : null,
+            /**
+             * @description Event time accounting for offset.
+             */
+            e_t: this.currentTime + this.serverOffsetTime,
+            /**
+             * @description Event URL. defaults to undefined.
+             */
+            e_u: window.location.href,
+            /**
+             * @description Event ontology kingdom. This is the highest level of the ontology and can be used to identify the event type.
+             * @example 'panel', 'engage', 'espn_key_plays'
+             */
+            e0: ontology.kingdom,
+            /**
+             * @description Event phylum.
+             * @example 'view', 'click', 'play clip'
+             */
+            e1: ontology.phylum,
+            /**
+             * @description Event class.
+             * @example 'panel_type'
+             */
+            e2: ontology.class,
+            /**
+             * @description Event order.
+             * @example 'panel_id'
+             */
+            e3: ontology.order,
+            /**
+             * @description Event family.
+             * @example 'panel_name'
+             */
+            e4: ontology.family,
+            /**
+             * @description Event genus. This is a more specific level of the ontology and can be used to identify the event type.
+             */
+            e5: ontology.genus,
+            /**
+             * @description Event species. This is the most specific level of the ontology and can be used to identify the event type.
+             */
+            e6: ontology.species,
+            /**
+             * @description Current timestamp.
+             */
+            t: this.currentTime,
+        };
+    }
+    getPageInsights() {
+        const config = SDK.getPageConfig();
+        return {
+            /**
+             * @description MongoDB page collection name (e.g. 'pages')
+             * @example object.collection
+             */
+            p_c: 'pages',
+            /**
+             * @description MongoDB page document ID (e.g. 'pageId')
+             * @example object._id
+             */
+            p_id: config?.page._id,
+            /**
+             * @description MongoDB page name (e.g. 'Home', 'Product Page')
+             * @example object.data.name || object.seo.title
+             */
+            p_n: config?.page.name,
+            /**
+             * @description MongoDB page slug (e.g. 'home', 'product-page')
+             * @example object.slug
+             */
+            p_s: config?.page.slug,
+            /**
+             * @description MongoDB page type (e.g. 'landing', 'channel')
+             * @example object.type
+             */
+            p_t: config?.page.type,
+        };
+    }
+    getDevicePermanentID() {
+        const devicePermanentId = localStorage.getItem('mio:device:permanentId');
+        if (devicePermanentId) {
+            return devicePermanentId;
+        }
+        const newDevicePermanentId = this.randomId();
+        localStorage.setItem('mio:device:permanentId', newDevicePermanentId);
+        return newDevicePermanentId;
+    }
+    getDeviceCreated() {
+        const deviceCreated = this.cacheManager.getCache('mio:device:created');
+        if (deviceCreated) {
+            return Number(deviceCreated);
+        }
+        const now = new Date().getTime();
+        this.cacheManager.setCache('mio:device:created', now.toString());
+        return now;
+    }
+    getTabID() {
+        const tabId = sessionStorage.getItem('mio:device:tabId');
+        if (tabId) {
+            return tabId;
+        }
+        const newTabId = this.randomId();
+        sessionStorage.setItem('mio:device:tabId', newTabId);
+        return newTabId;
+    }
+    getDeviceInsights() {
+        return {
+            /**
+             * @description Device created timestamp. You might wanna keep this fixed for the device you're in using a local storage or something related
+             * @example new Date().getTime()
+             */
+            d_ct: this.getDeviceCreated(),
+            /**
+             * @description New device or not. If you want to keep track of new devices, you can use a local storage or something related
+             * @example localStorage.getItem('isNewDevice') === 'true'
+             */
+            d_nd: false,
+            /**
+             * @description Navigator Platform (more Web API specific).
+             * @example 'MacIntel', 'Win32', 'Linux x86_64'
+             * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/platform
+             */
+            d_np: window.navigator.platform,
+            /**
+             * @description A unique identifier for the device, which can be used to track the device across sessions. You might wanna save this into a local storage or something related.
+             * @example localStorage.getItem('devicePermanentId') || generateUniqueId()
+             */
+            d_pid: this.getDevicePermanentID(),
+            /**
+             * @description Device screen height in pixels.
+             * @example window.screen.height
+             */
+            d_sh: window.screen.height,
+            /**
+             * @description Device screen width in pixels.
+             * @example window.screen.width
+             */
+            d_sw: window.screen.width,
+            /**
+             * @description Device tab ID, which can be used to track the device across tabs.
+             */
+            d_tid: this.getTabID(),
+            /**
+             * @description Device time in milliseconds since epoch.
+             */
+            d_tim: this.currentTime,
+            /**
+             * @description Device time offset in milliseconds. You might wanna keep this fixed for the device you're in using a local storage or something related.
+             */
+            d_tof: this.serverOffsetTime,
+            /**
+             * @description Device user agent string.
+             * @example navigator.userAgent ('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3')
+             * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent
+             */
+            d_ua: window.navigator.userAgent,
+        };
+    }
+    randomId() {
+        return (Math.random().toString(36).substring(2, 15) +
+            Math.random().toString(36).substring(2, 15));
+    }
+    async getDeviceOffset() {
+        const responseStart = Date.now();
+        const { diff: serverOffset, time: serverTime, } = await this.insightsService.getServerTime();
+        const responseEnd = Date.now();
+        const queryTime = responseEnd - responseStart;
+        const clientOffset = responseEnd - serverTime;
+        // from NTP algo: https://en.wikipedia.org/wiki/Network_Time_Protocol
+        // JS example: https://stackoverflow.com/questions/1638337
+        // /the-best-way-to-synchronize-client-side-javascript-clock-with-server-date
+        // will account for latent response times back to client
+        return (serverOffset - queryTime - clientOffset) / 2;
+    }
+    getInsightsInsights() {
+        return {
+            /**
+             * @description Unique identifier for the insights ID. Stored in site's document.
+             * @example site.settings.services.insights_id
+             */
+            i_id: this.pageConfig?.insights._id,
+        };
+    }
+    getMetadataInsights() {
+        return {
+            /**
+             * @description Metadata version, used to track changes in the metadata structure.
+             * @example '1.00.0'
+             */
+            m_iv: '1.00.0',
+        };
+    }
+    getReferrerInsights() {
+        return {
+            /**
+             * @description Referrer domain, which can be used to track the domain from which the user came. Defaults to "$direct"
+             * @example 'example.com'.
+             */
+            r_d: '$direct',
+            /**
+             * @description Referrer source, which can be used to track the source from which the user came (queryParam.r). Defaults to null
+             * @example const urlParams = new URLSearchParams(window.location.search);
+             *              urlParams.get('r') || null
+             */
+            r_s: null,
+            /**
+             * @description Referrer URL, which can be used to track the full URL from which the user came. Defaults to "$direct"
+             * @example document.referrer
+             */
+            r_u: '$direct',
+        };
+    }
+    getSessionID() {
+        const sessionId = sessionStorage.getItem('mio:session:id');
+        if (sessionId) {
+            return sessionId;
+        }
+        const newSessionId = this.randomId();
+        sessionStorage.setItem('mio:session:id', newSessionId);
+        return newSessionId;
+    }
+    getSessionInsights() {
+        return {
+            /**
+             * @description Session ID, which can be used to track the session across requests. You might wanna keep this fixed for the session you're in using a local storage or something related.
+             */
+            se_id: this.getSessionID(),
+            /**
+             * @description Session created timestamp. Usually set when the first event is fired
+             * @example new Date().getTime()
+             */
+            se_s: this.currentTime,
+        };
+    }
+    getSiteInsights() {
+        return {
+            /**
+             * @description Site domain.
+             * @example site.settings.domain.url. 'maestro.tv/site_slug'
+             */
+            si_d: this.pageConfig?.site.domainUrl,
+            /**
+             * @description Site ID.
+             * @example site._id
+             */
+            si_id: this.pageConfig?.site._id,
+            /**
+             * @description Site package ID.
+             * @example `${site.package.id}-sapphire`
+             */
+            si_pid: `${this.pageConfig?.site.package.id}-sapphire`,
+            /**
+             * @description Site package version.
+             * @example `${site.package.version}-sapphire`
+             */
+            si_pv: `${this.pageConfig?.site.package.version}-sapphire`,
+            /**
+             * @description Site slug.
+             * @example site.slug
+             */
+            si_s: this.pageConfig?.site.slug,
+        };
+    }
+    getUserInsights() {
+        return {
+            /**
+             * @description User avatar URL. Stored in user profile. defaults to null
+             * @example GET 'https://api.maestro.io/userprofile/v1'
+             */
+            u_a: null,
+            /**
+             * @description User account created date in milliseconds since epoch. defaults to null
+             * @example account.created
+             */
+            u_c: null,
+            /**
+             * @description Logged User email. defaults to null
+             * @example account.email
+             */
+            u_e: null,
+            /**
+             * @description Logged User ID. defaults to null
+             * @example account._id
+             */
+            u_id: null,
+            /**
+             * @description Logged User is logged in or not. defaults to false
+             */
+            u_li: false,
+            /**
+             * @description Logged User name. defaults to null
+             * @example account.name
+             */
+            u_n: null,
+            /**
+             * @description Logged User new user or not. Usually we compare server time and account.created. If it was created less than 1 day ago it's a new user. defaults to false
+             * @example Math.abs((serverTime || Date.now()) - account.created) < msIn.day
+             */
+            u_nu: false,
+            /**
+             * @description Logged User service. defaults to null
+             * @example account.service
+             */
+            u_s: null,
+            /**
+             * @description Logged User UID. defaults to null
+             * @example account.uid
+             */
+            u_u: null,
+            /**
+             * @description Logged User name. defaults to null
+             * @example account.name
+             */
+            u_un: null,
+        };
+    }
+}

package/dist/src/services/InsightsService/InsightsService.d.ts

@@ -0,0 +1,11 @@
+export default class InsightsService {
+    private client;
+    constructor();
+    private isEnabled;
+    action(payload: Record<string, unknown>): Promise<void>;
+    getServerTime(): Promise<{
+        time: number;
+        diff: number;
+    }>;
+    private randomId;
+}