coveo.analytics 2.20.1 → 2.20.2

package/dist/definitions/insight/insightClient.d.ts

@@ -0,0 +1,43 @@
+import { AnalyticsClient, ClientOptions } from '../client/analytics';
+import { SearchEventRequest } from '../events';
+import { FacetBaseMeta, FacetMetadata, FacetSortMeta, FacetStateMetadata, QueryErrorMeta, SearchPageEvents } from '../searchPage/searchPageEvents';
+export interface InsightClientProvider {
+    getSearchEventRequestPayload: () => Omit<SearchEventRequest, 'actionCause' | 'searchQueryUid'>;
+    getSearchUID: () => string;
+    getBaseMetadata: () => Record<string, any>;
+    getPipeline: () => string;
+    getOriginContext?: () => string;
+    getOriginLevel1: () => string;
+    getOriginLevel2: () => string;
+    getOriginLevel3: () => string;
+    getLanguage: () => string;
+    getIsAnonymous: () => boolean;
+    getFacetState?: () => FacetStateMetadata[];
+}
+export interface InsightClientOptions extends ClientOptions {
+    enableAnalytics: boolean;
+}
+export declare class CoveoInsightClient {
+    private opts;
+    private provider;
+    coveoAnalyticsClient: AnalyticsClient;
+    constructor(opts: Partial<InsightClientOptions>, provider: InsightClientProvider);
+    disable(): void;
+    enable(): void;
+    logInterfaceLoad(): Promise<void | import("../events").SearchEventResponse>;
+    logFetchMoreResults(): Promise<void | import("../events").CustomEventResponse>;
+    logFacetSelect(meta: FacetMetadata): Promise<void | import("../events").SearchEventResponse>;
+    logFacetDeselect(meta: FacetMetadata): Promise<void | import("../events").SearchEventResponse>;
+    logFacetUpdateSort(meta: FacetSortMeta): Promise<void | import("../events").SearchEventResponse>;
+    logFacetClearAll(meta: FacetBaseMeta): Promise<void | import("../events").SearchEventResponse>;
+    logFacetShowMore(meta: FacetBaseMeta): Promise<void | import("../events").CustomEventResponse>;
+    logFacetShowLess(meta: FacetBaseMeta): Promise<void | import("../events").CustomEventResponse>;
+    logQueryError(meta: QueryErrorMeta): Promise<void | import("../events").CustomEventResponse>;
+    logCustomEvent(event: SearchPageEvents, metadata?: Record<string, any>): Promise<void | import("../events").CustomEventResponse>;
+    logSearchEvent(event: SearchPageEvents, metadata?: Record<string, any>): Promise<void | import("../events").SearchEventResponse>;
+    private getBaseCustomEventRequest;
+    private getBaseSearchEventRequest;
+    private getBaseEventRequest;
+    private getOrigins;
+    private getClientId;
+}

package/dist/definitions/src/insight/insightClient.d.ts

@@ -0,0 +1,43 @@
+import { AnalyticsClient, ClientOptions } from '../client/analytics';
+import { SearchEventRequest } from '../events';
+import { FacetBaseMeta, FacetMetadata, FacetSortMeta, FacetStateMetadata, QueryErrorMeta, SearchPageEvents } from '../searchPage/searchPageEvents';
+export interface InsightClientProvider {
+    getSearchEventRequestPayload: () => Omit<SearchEventRequest, 'actionCause' | 'searchQueryUid'>;
+    getSearchUID: () => string;
+    getBaseMetadata: () => Record<string, any>;
+    getPipeline: () => string;
+    getOriginContext?: () => string;
+    getOriginLevel1: () => string;
+    getOriginLevel2: () => string;
+    getOriginLevel3: () => string;
+    getLanguage: () => string;
+    getIsAnonymous: () => boolean;
+    getFacetState?: () => FacetStateMetadata[];
+}
+export interface InsightClientOptions extends ClientOptions {
+    enableAnalytics: boolean;
+}
+export declare class CoveoInsightClient {
+    private opts;
+    private provider;
+    coveoAnalyticsClient: AnalyticsClient;
+    constructor(opts: Partial<InsightClientOptions>, provider: InsightClientProvider);
+    disable(): void;
+    enable(): void;
+    logInterfaceLoad(): Promise<void | import("../events").SearchEventResponse>;
+    logFetchMoreResults(): Promise<void | import("../events").CustomEventResponse>;
+    logFacetSelect(meta: FacetMetadata): Promise<void | import("../events").SearchEventResponse>;
+    logFacetDeselect(meta: FacetMetadata): Promise<void | import("../events").SearchEventResponse>;
+    logFacetUpdateSort(meta: FacetSortMeta): Promise<void | import("../events").SearchEventResponse>;
+    logFacetClearAll(meta: FacetBaseMeta): Promise<void | import("../events").SearchEventResponse>;
+    logFacetShowMore(meta: FacetBaseMeta): Promise<void | import("../events").CustomEventResponse>;
+    logFacetShowLess(meta: FacetBaseMeta): Promise<void | import("../events").CustomEventResponse>;
+    logQueryError(meta: QueryErrorMeta): Promise<void | import("../events").CustomEventResponse>;
+    logCustomEvent(event: SearchPageEvents, metadata?: Record<string, any>): Promise<void | import("../events").CustomEventResponse>;
+    logSearchEvent(event: SearchPageEvents, metadata?: Record<string, any>): Promise<void | import("../events").SearchEventResponse>;
+    private getBaseCustomEventRequest;
+    private getBaseSearchEventRequest;
+    private getBaseEventRequest;
+    private getOrigins;
+    private getClientId;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "coveo.analytics",
-    "version": "2.20.1",
+    "version": "2.20.2",
     "description": "📈 Coveo analytics client (node and browser compatible) ",
     "main": "dist/library.js",
     "module": "dist/library.es.js",

package/src/insight/insightClient.spec.ts

@@ -0,0 +1,223 @@
+import {mockFetch} from '../../tests/fetchMock';
+import CoveoAnalyticsClient from '../client/analytics';
+import {NoopAnalytics} from '../client/noopAnalytics';
+import {CustomEventsTypes, SearchPageEvents} from '../searchPage/searchPageEvents';
+import {CoveoInsightClient, InsightClientProvider} from './insightClient';
+import doNotTrack from '../donottrack';
+
+jest.mock('../donottrack', () => {
+    return {
+        default: jest.fn(),
+        doNotTrack: jest.fn(),
+    };
+});
+
+const {fetchMock, fetchMockBeforeEach} = mockFetch();
+describe('InsightClient', () => {
+    const fakeFacetState = [
+        {
+            valuePosition: 0,
+            value: 'foo',
+            state: 'selected' as const,
+            facetPosition: 1,
+            displayValue: 'foobar',
+            facetType: 'specific' as const,
+            field: '@foo',
+            id: 'bar',
+            title: 'title',
+        },
+    ];
+
+    let client: CoveoInsightClient;
+
+    const provider: InsightClientProvider = {
+        getBaseMetadata: () => ({foo: 'bar'}),
+        getSearchEventRequestPayload: () => ({
+            queryText: 'queryText',
+            responseTime: 123,
+        }),
+        getSearchUID: () => 'my-uid',
+        getPipeline: () => 'my-pipeline',
+        getOriginContext: () => 'origin-context',
+        getOriginLevel1: () => 'origin-level-1',
+        getOriginLevel2: () => 'origin-level-2',
+        getOriginLevel3: () => 'origin-level-3',
+        getLanguage: () => 'en',
+        getFacetState: () => fakeFacetState,
+        getIsAnonymous: () => false,
+    };
+
+    const initClient = () => {
+        return new CoveoInsightClient({}, provider);
+    };
+
+    const expectOrigins = () => ({
+        originContext: 'origin-context',
+        originLevel1: 'origin-level-1',
+        originLevel2: 'origin-level-2',
+        originLevel3: 'origin-level-3',
+    });
+
+    const expectMatchPayload = (actionCause: SearchPageEvents, meta = {}) => {
+        const [, {body}] = fetchMock.lastCall();
+        const customData = {foo: 'bar', ...meta};
+        expect(JSON.parse(body.toString())).toMatchObject({
+            queryText: 'queryText',
+            responseTime: 123,
+            queryPipeline: 'my-pipeline',
+            actionCause,
+            customData,
+            facetState: fakeFacetState,
+            language: 'en',
+            clientId: 'visitor-id',
+            ...expectOrigins(),
+        });
+    };
+
+    const expectMatchCustomEventPayload = (actionCause: SearchPageEvents, meta = {}) => {
+        const [, {body}] = fetchMock.lastCall();
+        const customData = {foo: 'bar', ...meta};
+        expect(JSON.parse(body.toString())).toMatchObject({
+            eventValue: actionCause,
+            eventType: CustomEventsTypes[actionCause],
+            lastSearchQueryUid: 'my-uid',
+            customData,
+            language: 'en',
+            clientId: 'visitor-id',
+            ...expectOrigins(),
+        });
+    };
+
+    beforeEach(() => {
+        fetchMockBeforeEach();
+
+        client = initClient();
+        client.coveoAnalyticsClient.runtime.storage.setItem('visitorId', 'visitor-id');
+        fetchMock.mock(/.*/, {
+            visitId: 'visit-id',
+        });
+    });
+
+    afterEach(() => {
+        fetchMock.reset();
+    });
+
+    it('should send proper payload for #interfaceLoad', async () => {
+        await client.logInterfaceLoad();
+        expectMatchPayload(SearchPageEvents.interfaceLoad);
+    });
+
+    it('should send proper payload for #fetchMoreResults', async () => {
+        await client.logFetchMoreResults();
+        expectMatchCustomEventPayload(SearchPageEvents.pagerScrolling, {type: 'getMoreResults'});
+    });
+
+    it('should send proper payload for #logFacetSelect', async () => {
+        const meta = {
+            facetField: '@foo',
+            facetId: 'bar',
+            facetTitle: 'title',
+            facetValue: 'qwerty',
+        };
+
+        await client.logFacetSelect(meta);
+        expectMatchPayload(SearchPageEvents.facetSelect, meta);
+    });
+
+    it('should send proper payload for #logFacetDeselect', async () => {
+        const meta = {
+            facetField: '@foo',
+            facetId: 'bar',
+            facetTitle: 'title',
+            facetValue: 'qwerty',
+        };
+
+        await client.logFacetDeselect(meta);
+        expectMatchPayload(SearchPageEvents.facetDeselect, meta);
+    });
+
+    it('should send proper payload for #logFacetUpdateSort', async () => {
+        const meta = {
+            facetField: '@foo',
+            facetId: 'bar',
+            facetTitle: 'title',
+            criteria: 'bazz',
+        };
+        await client.logFacetUpdateSort(meta);
+        expectMatchPayload(SearchPageEvents.facetUpdateSort, meta);
+    });
+
+    it('should send proper payload for #logFacetClearAll', async () => {
+        const meta = {
+            facetField: '@foo',
+            facetId: 'bar',
+            facetTitle: 'title',
+        };
+        await client.logFacetClearAll(meta);
+        expectMatchPayload(SearchPageEvents.facetClearAll, meta);
+    });
+
+    it('should send proper payload for #logFacetShowMore', async () => {
+        const meta = {
+            facetField: '@foo',
+            facetId: 'bar',
+            facetTitle: 'title',
+        };
+        await client.logFacetShowMore(meta);
+        expectMatchCustomEventPayload(SearchPageEvents.facetShowMore, meta);
+    });
+
+    it('should send proper payload for #logFacetShowLess', async () => {
+        const meta = {
+            facetField: '@foo',
+            facetId: 'bar',
+            facetTitle: 'title',
+        };
+        await client.logFacetShowLess(meta);
+        expectMatchCustomEventPayload(SearchPageEvents.facetShowLess, meta);
+    });
+
+    it('should send proper payload for #logQueryError', async () => {
+        const meta = {
+            query: 'q',
+            aq: 'aq',
+            cq: 'cq',
+            dq: 'dq',
+            errorMessage: 'boom',
+            errorType: 'a bad one',
+        };
+        await client.logQueryError(meta);
+        expectMatchCustomEventPayload(SearchPageEvents.queryError, meta);
+    });
+
+    it('should enable analytics tracking by default', () => {
+        const c = new CoveoInsightClient({}, provider);
+        expect(c.coveoAnalyticsClient instanceof CoveoAnalyticsClient).toBe(true);
+    });
+
+    it('should allow disabling analytics on initialization', () => {
+        const c = new CoveoInsightClient({enableAnalytics: false}, provider);
+        expect(c.coveoAnalyticsClient instanceof NoopAnalytics).toBe(true);
+    });
+
+    it('should allow disabling analytics after initialization', () => {
+        const c = new CoveoInsightClient({enableAnalytics: true}, provider);
+        expect(c.coveoAnalyticsClient instanceof CoveoAnalyticsClient).toBe(true);
+        c.disable();
+        expect(c.coveoAnalyticsClient instanceof NoopAnalytics).toBe(true);
+    });
+
+    it('should disable analytics when doNotTrack is enabled', async () => {
+        (doNotTrack as jest.Mock).mockImplementationOnce(() => true);
+
+        const c = new CoveoInsightClient({}, provider);
+        expect(c.coveoAnalyticsClient instanceof NoopAnalytics).toBe(true);
+    });
+
+    it('should allow enabling analytics after initialization', () => {
+        const c = new CoveoInsightClient({enableAnalytics: false}, provider);
+        expect(c.coveoAnalyticsClient instanceof NoopAnalytics).toBe(true);
+        c.enable();
+        expect(c.coveoAnalyticsClient instanceof CoveoAnalyticsClient).toBe(true);
+    });
+});

package/src/insight/insightClient.ts

@@ -0,0 +1,150 @@
+import CoveoAnalyticsClient, {AnalyticsClient, ClientOptions} from '../client/analytics';
+import {NoopAnalytics} from '../client/noopAnalytics';
+import doNotTrack from '../donottrack';
+import {CustomEventRequest, SearchEventRequest} from '../events';
+import {
+    CustomEventsTypes,
+    FacetBaseMeta,
+    FacetMetadata,
+    FacetSortMeta,
+    FacetStateMetadata,
+    QueryErrorMeta,
+    SearchPageEvents,
+} from '../searchPage/searchPageEvents';
+
+export interface InsightClientProvider {
+    getSearchEventRequestPayload: () => Omit<SearchEventRequest, 'actionCause' | 'searchQueryUid'>;
+    getSearchUID: () => string;
+    getBaseMetadata: () => Record<string, any>;
+    getPipeline: () => string;
+    getOriginContext?: () => string;
+    getOriginLevel1: () => string;
+    getOriginLevel2: () => string;
+    getOriginLevel3: () => string;
+    getLanguage: () => string;
+    getIsAnonymous: () => boolean;
+    getFacetState?: () => FacetStateMetadata[];
+}
+
+export interface InsightClientOptions extends ClientOptions {
+    enableAnalytics: boolean;
+}
+
+export class CoveoInsightClient {
+    public coveoAnalyticsClient: AnalyticsClient;
+
+    constructor(private opts: Partial<InsightClientOptions>, private provider: InsightClientProvider) {
+        const shouldDisableAnalytics = opts.enableAnalytics === false || doNotTrack();
+        this.coveoAnalyticsClient = shouldDisableAnalytics ? new NoopAnalytics() : new CoveoAnalyticsClient(opts);
+    }
+
+    public disable() {
+        if (this.coveoAnalyticsClient instanceof CoveoAnalyticsClient) {
+            this.coveoAnalyticsClient.clear();
+        }
+        this.coveoAnalyticsClient = new NoopAnalytics();
+    }
+
+    public enable() {
+        this.coveoAnalyticsClient = new CoveoAnalyticsClient(this.opts);
+    }
+
+    public logInterfaceLoad() {
+        return this.logSearchEvent(SearchPageEvents.interfaceLoad);
+    }
+
+    public logFetchMoreResults() {
+        return this.logCustomEvent(SearchPageEvents.pagerScrolling, {type: 'getMoreResults'});
+    }
+
+    public logFacetSelect(meta: FacetMetadata) {
+        return this.logSearchEvent(SearchPageEvents.facetSelect, meta);
+    }
+
+    public logFacetDeselect(meta: FacetMetadata) {
+        return this.logSearchEvent(SearchPageEvents.facetDeselect, meta);
+    }
+
+    public logFacetUpdateSort(meta: FacetSortMeta) {
+        return this.logSearchEvent(SearchPageEvents.facetUpdateSort, meta);
+    }
+
+    public logFacetClearAll(meta: FacetBaseMeta) {
+        return this.logSearchEvent(SearchPageEvents.facetClearAll, meta);
+    }
+
+    public logFacetShowMore(meta: FacetBaseMeta) {
+        return this.logCustomEvent(SearchPageEvents.facetShowMore, meta);
+    }
+
+    public logFacetShowLess(meta: FacetBaseMeta) {
+        return this.logCustomEvent(SearchPageEvents.facetShowLess, meta);
+    }
+
+    public logQueryError(meta: QueryErrorMeta) {
+        return this.logCustomEvent(SearchPageEvents.queryError, meta);
+    }
+
+    public async logCustomEvent(event: SearchPageEvents, metadata?: Record<string, any>) {
+        const customData = {...this.provider.getBaseMetadata(), ...metadata};
+
+        const payload: CustomEventRequest = {
+            ...(await this.getBaseCustomEventRequest(customData)),
+            eventType: CustomEventsTypes[event]!,
+            eventValue: event,
+        };
+
+        return this.coveoAnalyticsClient.sendCustomEvent(payload);
+    }
+
+    public async logSearchEvent(event: SearchPageEvents, metadata?: Record<string, any>) {
+        return this.coveoAnalyticsClient.sendSearchEvent(await this.getBaseSearchEventRequest(event, metadata));
+    }
+
+    private async getBaseCustomEventRequest(metadata?: Record<string, any>) {
+        return {
+            ...(await this.getBaseEventRequest(metadata)),
+            lastSearchQueryUid: this.provider.getSearchUID(),
+        };
+    }
+
+    private async getBaseSearchEventRequest(
+        event: SearchPageEvents,
+        metadata?: Record<string, any>
+    ): Promise<SearchEventRequest> {
+        return {
+            ...(await this.getBaseEventRequest(metadata)),
+            ...this.provider.getSearchEventRequestPayload(),
+            searchQueryUid: this.provider.getSearchUID(),
+            queryPipeline: this.provider.getPipeline(),
+            actionCause: event,
+        };
+    }
+
+    private async getBaseEventRequest(metadata?: Record<string, any>) {
+        const customData = {...this.provider.getBaseMetadata(), ...metadata};
+        return {
+            ...this.getOrigins(),
+            customData,
+            language: this.provider.getLanguage(),
+            facetState: this.provider.getFacetState ? this.provider.getFacetState() : [],
+            anonymous: this.provider.getIsAnonymous(),
+            clientId: await this.getClientId(),
+        };
+    }
+
+    private getOrigins() {
+        return {
+            originContext: this.provider.getOriginContext?.(),
+            originLevel1: this.provider.getOriginLevel1(),
+            originLevel2: this.provider.getOriginLevel2(),
+            originLevel3: this.provider.getOriginLevel3(),
+        };
+    }
+
+    private getClientId() {
+        return this.coveoAnalyticsClient instanceof CoveoAnalyticsClient
+            ? this.coveoAnalyticsClient.getCurrentVisitorId()
+            : undefined;
+    }
+}