feat(sdk-analytics) fix comments

core-web/libs/sdk/analytics/README.md

@@ -26,6 +26,12 @@ Or include the script in your HTML page:
 
 ### Provider Setup
 
+First, import the provider:
+
+```tsx
+import { DotContentAnalyticsProvider } from '@dotcms/analytics';
+```
+
 Wrap your application with the `DotContentAnalyticsProvider`:
 
 ```tsx

core-web/libs/sdk/analytics/package.json

@@ -21,8 +21,7 @@
     "homepage": "https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/analytics/README.md",
     "dependencies": {
         "analytics": "^0.8.14",
-    "react": "^18.2.0",
-    "@dotcms/react": "0.0.1-alpha.38"
+    "react": "^18.2.0"
     },
     "peerDependencies": {
         "vite": "^5.0.0"

core-web/libs/sdk/analytics/src/index.ts

@@ -1,8 +1,2 @@
-// HOC for wrapping a component with content analytics capabilities
-export * from './lib/react/components/withContentAnalytics';
-
-// Hook for tracking analytics events
-export * from './lib/react/hook/useAnalyticTracker';
-
-// Provider for the DotContentAnalytics instance
 export * from './lib/react/components/DotContentAnalyticsProvider';
+export * from './lib/react/hook/useContentAnalytics';

core-web/libs/sdk/analytics/src/lib/dot-content-analytics.ts → core-web/libs/sdk/analytics/src/lib/dotAnalytics/dot-content-analytics.ts

@@ -24,13 +24,29 @@ export class DotContentAnalytics {
 
     private constructor(config: DotContentAnalyticsConfig) {
         this.#config = config;
-        this.logger = new DotLogger(this.#config.debug, 'DotContentAnalytics');
+        this.logger = new DotLogger(config.debug, 'DotContentAnalytics');
+
+        if (!config.apiKey) {
+            this.#initialized = false;
+        }
     }
 
     /**
      * Returns the singleton instance of DotContentAnalytics
      */
     static getInstance(config: DotContentAnalyticsConfig): DotContentAnalytics {
+        if (!config.apiKey) {
+            console.error(
+                `DotContentAnalytics: Missing "apiKey" in configuration - Events will not be sent to Content Analytics`
+            );
+        }
+
+        if (!config.server) {
+            console.error(
+                `DotContentAnalytics: Missing "server" in configuration - Events will not be sent to Content Analytics`
+            );
+        }
+
         if (!DotContentAnalytics.instance) {
             DotContentAnalytics.instance = new DotContentAnalytics(config);
         }
@@ -52,10 +68,12 @@ export class DotContentAnalytics {
             this.logger.group('Initialization');
             this.logger.time('Init');
 
+            const plugins = this.#getPlugins();
+
             this.#analytics = Analytics({
                 app: 'dotAnalytics',
                 debug: this.#config.debug,
-                plugins: [dotAnalyticsEnricherPlugin, dotAnalytics(this.#config)]
+                plugins
             });
 
             this.#initialized = true;
@@ -70,6 +88,19 @@ export class DotContentAnalytics {
         }
     }
 
+    /**
+     * Returns the plugins to be used in the analytics instance
+     */
+    #getPlugins() {
+        const hasRequiredConfig = this.#config.apiKey && this.#config.server;
+
+        if (!hasRequiredConfig) {
+            return [];
+        }
+
+        return [dotAnalyticsEnricherPlugin, dotAnalytics(this.#config)];
+    }
+
     /**
      * Sends a page view event to the analytics instance.
      *

core-web/libs/sdk/analytics/src/lib/plugin/dot-analytics.plugin.ts → core-web/libs/sdk/analytics/src/lib/dotAnalytics/plugin/dot-analytics.plugin.ts

@@ -1,6 +1,6 @@
 import { sendAnalyticsEventToServer } from '../shared/dot-content-analytics.http';
 import {
-    DotAnalyticsPayload,
+    DotAnalyticsParams,
     DotContentAnalyticsConfig
 } from '../shared/dot-content-analytics.model';
 
@@ -23,10 +23,7 @@ export const dotAnalytics = (config: DotContentAnalyticsConfig) => {
         /**
          * Initialize the plugin
          */
-        initialize: (params: {
-            config: DotContentAnalyticsConfig;
-            payload: DotAnalyticsPayload;
-        }) => {
+        initialize: (params: DotAnalyticsParams) => {
             const { config, payload } = params;
             if (config.debug) {
                 console.warn('DotAnalytics: Initialized with config', config);
@@ -50,7 +47,7 @@ export const dotAnalytics = (config: DotContentAnalyticsConfig) => {
         /**
          * Track a page view event
          */
-        page: (params: { config: DotContentAnalyticsConfig; payload: DotAnalyticsPayload }) => {
+        page: (params: DotAnalyticsParams) => {
             const { config, payload } = params;
 
             if (!isInitialized) {
@@ -68,7 +65,7 @@ export const dotAnalytics = (config: DotContentAnalyticsConfig) => {
         /**
          * Track a custom event
          */
-        track: (params: { config: DotContentAnalyticsConfig; payload: DotAnalyticsPayload }) => {
+        track: (params: DotAnalyticsParams) => {
             const { config, payload } = params;
 
             if (!isInitialized) {

core-web/libs/sdk/analytics/src/lib/shared/dot-content-analytics.http.ts → core-web/libs/sdk/analytics/src/lib/dotAnalytics/shared/dot-content-analytics.http.ts

@@ -22,11 +22,17 @@ export const sendAnalyticsEventToServer = async (
     }
 
     try {
-        return await fetch(`${options.server}${ANALYTICS_ENDPOINT}`, {
+        const response = await fetch(`${options.server}${ANALYTICS_ENDPOINT}`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(serverEvent)
         });
+
+        if (response.ok) {
+            return response;
+        } else {
+            throw new Error(`${response.status}`);
+        }
     } catch (error) {
         console.error('DotAnalytics: Error sending event:', error);
         throw error;

core-web/libs/sdk/analytics/src/lib/shared/dot-content-analytics.model.ts → core-web/libs/sdk/analytics/src/lib/dotAnalytics/shared/dot-content-analytics.model.ts

@@ -150,6 +150,14 @@ export interface ServerEvent extends Record<string, unknown> {
 /**
  * Interface for the AnalyticsTracker.
  */
-export interface AnalyticsTracker {
+export interface DotContentAnalyticsCustomHook {
     track: (eventName: string, payload?: Record<string, unknown>) => void;
 }
+
+/**
+ * Params for the DotAnalytics plugin
+ */
+export interface DotAnalyticsParams {
+    config: DotContentAnalyticsConfig;
+    payload: DotAnalyticsPayload;
+}

core-web/libs/sdk/analytics/src/lib/utils/DotLogger.ts → core-web/libs/sdk/analytics/src/lib/dotAnalytics/utils/DotLogger.ts

@@ -2,6 +2,7 @@
  * Logger for the dotCMS SDK
  */
 export class DotLogger {
+    // TODO: Create a logger that can be used in the SDK
     private readonly isDebug: boolean;
     private readonly packageName: string;
 

core-web/libs/sdk/analytics/src/lib/react/components/DotContentAnalyticsProvider.tsx

@@ -1,9 +1,9 @@
-import { ReactElement, ReactNode, useEffect, useState } from 'react';
+import { ReactElement, ReactNode, useEffect, useMemo } from 'react';
 
-import { DotContentAnalytics } from '../../dot-content-analytics';
-import { DotContentAnalyticsConfig } from '../../shared/dot-content-analytics.model';
+import { DotContentAnalytics } from '../../dotAnalytics/dot-content-analytics';
+import { DotContentAnalyticsConfig } from '../../dotAnalytics/shared/dot-content-analytics.model';
 import DotContentAnalyticsContext from '../contexts/DotContentAnalyticsContext';
-import { useContentAnalytics } from '../hook/useContentAnalytics';
+import { useRouteTracker } from '../hook/useRouterTracker';
 
 interface DotContentAnalyticsProviderProps {
     children?: ReactNode;
@@ -25,17 +25,15 @@ export const DotContentAnalyticsProvider = ({
     children,
     config
 }: DotContentAnalyticsProviderProps): ReactElement => {
-    const [instance, setInstance] = useState<DotContentAnalytics | null>(null);
-
-    useContentAnalytics(instance);
+    const instance = useMemo(() => DotContentAnalytics.getInstance(config), [config]);
 
     useEffect(() => {
-        const dotContentAnalyticsInstance = DotContentAnalytics.getInstance(config);
-
-        dotContentAnalyticsInstance.ready().then(() => {
-            setInstance(dotContentAnalyticsInstance);
+        instance.ready().catch((err) => {
+            console.error('Error initializing analytics:', err);
         });
-    }, []);
+    }, [instance]);
+
+    useRouteTracker(instance);
 
     return (
         <DotContentAnalyticsContext.Provider value={instance}>

core-web/libs/sdk/analytics/src/lib/react/contexts/DotContentAnalyticsContext.spec.tsx

@@ -1,10 +1,10 @@
 import { jest } from '@jest/globals';
-import React, { renderHook } from '@testing-library/react-hooks';
+import { renderHook } from '@testing-library/react-hooks';
 import { ReactNode, useContext } from 'react';
 
 import DotContentAnalyticsContext from './DotContentAnalyticsContext';
 
-import { DotContentAnalytics } from '../../dot-content-analytics';
+import { DotContentAnalytics } from '../../dotAnalytics/dot-content-analytics';
 
 jest.mock('../dot-content-analytics', () => {
     return jest.fn().mockImplementation(() => {

core-web/libs/sdk/analytics/src/lib/react/contexts/DotContentAnalyticsContext.tsx

@@ -1,6 +1,6 @@
 import { createContext } from 'react';
 
-import { DotContentAnalytics } from '../../dot-content-analytics';
+import { DotContentAnalytics } from '../../dotAnalytics/dot-content-analytics';
 
 /**
  * `DotContentAnalyticsContext` is a React context that is designed to provide an instance of

core-web/libs/sdk/analytics/src/lib/react/hook/useContentAnalytics.ts

@@ -1,31 +1,33 @@
-import { useEffect } from 'react';
+import { useContext } from 'react';
 
-import { DotContentAnalytics } from '../../dot-content-analytics';
-import { isInsideEditor } from '../../shared/dot-content-analytics.utils';
+import { DotContentAnalyticsCustomHook } from '../../dotAnalytics/shared/dot-content-analytics.model';
+import { isInsideEditor } from '../../dotAnalytics/shared/dot-content-analytics.utils';
+import DotContentAnalyticsContext from '../contexts/DotContentAnalyticsContext';
 
 /**
  * Custom hook that handles analytics page view tracking.
  *
- * @param {DotContentAnalytics | null} instance - The analytics instance used to track page views
- * @returns {void}
+ * @returns {DotContentAnalyticsCustomHook} - The analytics instance used to track page views
  *
  */
-export const useContentAnalytics = (instance: DotContentAnalytics | null): void => {
-    /**
-     * Tracks page view when component mounts, but only if:
-     * - We have a valid analytics instance
-     * - We're in a browser environment
-     * - We're not inside the editor
-     */
-    useEffect(() => {
-        if (!instance || typeof window === 'undefined') {
-            return;
-        }
-
-        const insideEditor = isInsideEditor();
+export const useContentAnalytics = (): DotContentAnalyticsCustomHook => {
+    const instance = useContext(DotContentAnalyticsContext);
+    const insideEditor = isInsideEditor();
 
-        if (!insideEditor) {
-            instance.pageView({ source: 'headless' });
+    return {
+        /**
+         * Track an event with the analytics instance.
+         *
+         * @param {string} eventName - The name of the event to track
+         * @param {object} payload - Additional data to include with the event
+         */
+        track: (eventName: string, payload: Record<string, unknown> = {}) => {
+            if (instance?.track && !insideEditor) {
+                instance.track(eventName, {
+                    ...payload,
+                    timestamp: new Date().toISOString()
+                });
+            }
         }
-    }, [instance]);
+    };
 };