@dotcms/analytics 0.0.1-alpha.58 → 0.0.1-alpha.60

package/README.md

@@ -0,0 +1,159 @@
+# @dotcms/analytics
+
+`@dotcms/analytics` is the official dotCMS JavaScript library for Content Analytics that helps track events and analytics in your webapps. Available for both browser and React applications.
+
+## Features
+
+-   **Simple Browser Integration**: Easy to implement via script tags using IIFE implementation
+-   **React Support**: Built-in React components and hooks for seamless integration
+-   **Event Tracking**: Simple API to track custom events with additional properties
+-   **Automatic PageView**: Option to automatically track page views
+-   **Debug Mode**: Optional debug logging for development
+
+## Installation
+
+```bash
+npm install @dotcms/analytics
+```
+
+Or include the script in your HTML page:
+
+```html
+<script src="ca.min.js"></script>
+```
+
+## React Integration
+
+### Provider Setup
+
+First, import the provider:
+
+```tsx
+import { DotContentAnalyticsProvider } from '@dotcms/analytics/react';
+```
+
+Wrap your application with the `DotContentAnalyticsProvider`:
+
+```tsx
+// Example configuration
+const analyticsConfig = {
+    apiKey: 'your-api-key-from-dotcms-analytics-app',
+    server: 'https://your-dotcms-instance.com'
+};
+
+function App() {
+    return (
+        <DotContentAnalyticsProvider config={analyticsConfig}>
+            <YourApp />
+        </DotContentAnalyticsProvider>
+    );
+}
+```
+
+### Tracking Custom Events
+
+Use the `useContentAnalytics` hook to track custom events:
+
+```tsx
+import { useContentAnalytics } from '@dotcms/analytics/react';
+
+function Activity({ title, urlTitle }) {
+    const { track } = useContentAnalytics();
+
+    // First parameter: custom event name to identify the action
+    // Second parameter: object with properties you want to track
+
+    return <button onClick={() => track('btn-click', { title, urlTitle })}>See Details →</button>;
+}
+```
+
+### Manual Page View Tracking
+
+To manually track page views, first disable automatic tracking in your config:
+
+```tsx
+const analyticsConfig = {
+    apiKey: 'your-api-key-from-dotcms-analytics-app',
+    server: 'https://your-dotcms-instance.com',
+    autoPageView: false // Disable automatic tracking
+};
+```
+
+Then use the `useContentAnalytics` hook in your layout component:
+
+```tsx
+import { useContentAnalytics } from '@dotcms/analytics/react';
+
+function Layout({ children }) {
+    const { pageView } = useContentAnalytics();
+
+    useEffect(() => {
+        pageView({
+            // Add any custom properties you want to track
+            myCustomValue: '2'
+        });
+    }, []);
+
+    return <div>{children}</div>;
+}
+```
+
+## Browser Configuration
+
+The script can be configured using data attributes:
+
+-   **data-analytics-server**: URL of the server where events will be sent. If not provided, the current domain will be used
+-   **data-analytics-debug**: Enables debug logging
+-   **data-analytics-auto-page-view**: Recommended for IIFE implementation. Enables automatic page view tracking
+-   **data-analytics-key**: **(Required)** API key for authentication
+
+```html
+<!-- Example configuration -->
+<script
+    src="ca.min.js"
+    data-analytics-server="http://localhost:8080"
+    data-analytics-key="dev-key-123"
+    data-analytics-auto-page-view
+    data-analytics-debug></script>
+
+<!-- Without automatic tracking - events must be sent manually -->
+<script
+    src="ca.min.js"
+    data-analytics-server="http://localhost:8080"
+    data-analytics-debug
+    data-analytics-key="dev-key-123"></script>
+```
+
+## Roadmap
+
+The following features are planned for future releases:
+
+2. **Headless Support**
+    - Angular integration for event tracking
+
+## Contributing
+
+GitHub pull requests are the preferred method to contribute code to dotCMS. Before any pull requests can be accepted, an automated tool will ask you to agree to the [dotCMS Contributor's Agreement](https://gist.github.com/wezell/85ef45298c48494b90d92755b583acb3).
+
+## Licensing
+
+dotCMS comes in multiple editions and as such is dual licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds a number of enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://dotcms.com/cms-platform/features).
+
+## Support
+
+If you need help or have any questions, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
+
+## Documentation
+
+Always refer to the official [DotCMS documentation](https://www.dotcms.com/docs/latest/) for comprehensive guides and API references.
+
+## Getting Help
+
+| Source          | Location                                                            |
+| --------------- | ------------------------------------------------------------------- |
+| Installation    | [Installation](https://dotcms.com/docs/latest/installation)         |
+| Documentation   | [Documentation](https://dotcms.com/docs/latest/table-of-contents)   |
+| Videos          | [Helpful Videos](http://dotcms.com/videos/)                         |
+| Forums/Listserv | [via Google Groups](https://groups.google.com/forum/#!forum/dotCMS) |
+| Twitter         | @dotCMS                                                             |
+| Main Site       | [dotCMS.com](https://dotcms.com/)                                   |

package/{index.mjs → index.js}

@@ -1,5 +1,5 @@
-import { DotContentAnalyticsProvider as e } from "./lib/react/components/DotContentAnalyticsProvider.mjs";
-import { useContentAnalytics as r } from "./lib/react/hook/useContentAnalytics.mjs";
+import { DotContentAnalyticsProvider as e } from "./lib/react/components/DotContentAnalyticsProvider.js";
+import { useContentAnalytics as r } from "./lib/react/hook/useContentAnalytics.js";
 export {
   e as DotContentAnalyticsProvider,
   r as useContentAnalytics

package/lib/dotAnalytics/{dot-content-analytics.mjs → dot-content-analytics.js}

@@ -1,4 +1,4 @@
-import { createAnalyticsInstance as o } from "./shared/dot-content-analytics.utils.mjs";
+import { createAnalyticsInstance as o } from "./shared/dot-content-analytics.utils.js";
 const i = (r) => {
   const t = o(r);
   return {

package/lib/dotAnalytics/plugin/{dot-analytics.enricher.plugin.mjs → dot-analytics.enricher.plugin.js}

@@ -1,5 +1,5 @@
-import { ANALYTICS_PAGEVIEW_EVENT as n, ANALYTICS_SOURCE_TYPE as r, EventType as o } from "../shared/dot-content-analytics.constants.mjs";
-import { getBrowserEventData as i } from "../shared/dot-content-analytics.utils.mjs";
+import { ANALYTICS_PAGEVIEW_EVENT as n, ANALYTICS_SOURCE_TYPE as r, EventType as o } from "../shared/dot-content-analytics.constants.js";
+import { getBrowserEventData as i } from "../shared/dot-content-analytics.utils.js";
 const p = {
   name: "enrich-dot-analytics",
   "page:dot-analytics": ({ payload: e }) => {

package/lib/dotAnalytics/plugin/{dot-analytics.plugin.mjs → dot-analytics.plugin.js}

@@ -1,4 +1,4 @@
-import { sendAnalyticsEventToServer as r } from "../shared/dot-content-analytics.http.mjs";
+import { sendAnalyticsEventToServer as r } from "../shared/dot-content-analytics.http.js";
 const s = (a) => {
   let n = !1;
   return {

package/lib/dotAnalytics/shared/{dot-content-analytics.http.mjs → dot-content-analytics.http.js}

@@ -1,4 +1,4 @@
-import { ANALYTICS_ENDPOINT as o } from "./dot-content-analytics.constants.mjs";
+import { ANALYTICS_ENDPOINT as o } from "./dot-content-analytics.constants.js";
 const a = async (n, t) => {
   const r = {
     ...n,

package/lib/dotAnalytics/shared/{dot-content-analytics.utils.mjs → dot-content-analytics.utils.js}

@@ -1,7 +1,7 @@
-import { Analytics as i } from "../../../node_modules/analytics/lib/analytics.browser.es.mjs";
-import { EXPECTED_UTM_KEYS as a } from "./dot-content-analytics.constants.mjs";
-import { dotAnalyticsEnricherPlugin as s } from "../plugin/dot-analytics.enricher.plugin.mjs";
-import { dotAnalytics as c } from "../plugin/dot-analytics.plugin.mjs";
+import i from "analytics";
+import { EXPECTED_UTM_KEYS as a } from "./dot-content-analytics.constants.js";
+import { dotAnalyticsEnricherPlugin as s } from "../plugin/dot-analytics.enricher.plugin.js";
+import { dotAnalytics as c } from "../plugin/dot-analytics.plugin.js";
 const h = (e) => ({
   utc_time: (/* @__PURE__ */ new Date()).toISOString(),
   local_tz_offset: (/* @__PURE__ */ new Date()).getTimezoneOffset(),

package/lib/react/components/{DotContentAnalyticsProvider.mjs → DotContentAnalyticsProvider.js}

@@ -1,8 +1,8 @@
 import { jsx as e } from "react/jsx-runtime";
 import { useMemo as i } from "react";
-import { initializeContentAnalytics as n } from "../../dotAnalytics/dot-content-analytics.mjs";
-import a from "../contexts/DotContentAnalyticsContext.mjs";
-import { useRouterTracker as m } from "../hook/useRouterTracker.mjs";
+import { initializeContentAnalytics as n } from "../../dotAnalytics/dot-content-analytics.js";
+import a from "../contexts/DotContentAnalyticsContext.js";
+import { useRouterTracker as m } from "../hook/useRouterTracker.js";
 const f = ({
   children: r,
   config: t

package/lib/react/hook/{useContentAnalytics.mjs → useContentAnalytics.js}

@@ -1,6 +1,6 @@
 import { useContext as i, useRef as s } from "react";
-import { isInsideEditor as r } from "../../dotAnalytics/shared/dot-content-analytics.utils.mjs";
-import a from "../contexts/DotContentAnalyticsContext.mjs";
+import { isInsideEditor as r } from "../../dotAnalytics/shared/dot-content-analytics.utils.js";
+import a from "../contexts/DotContentAnalyticsContext.js";
 const f = () => {
   const t = i(a), o = s(null);
   if (!t)

package/lib/react/hook/{useRouterTracker.mjs → useRouterTracker.js}

@@ -1,5 +1,5 @@
 import { useRef as r, useEffect as i } from "react";
-import { isInsideEditor as u } from "../../dotAnalytics/shared/dot-content-analytics.utils.mjs";
+import { isInsideEditor as u } from "../../dotAnalytics/shared/dot-content-analytics.utils.js";
 function s(t) {
   const n = r(null);
   i(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/analytics",
-  "version": "0.0.1-alpha.58",
+  "version": "0.0.1-alpha.60",
   "description": "Official JavaScript library for Content Analytics with DotCMS.",
   "repository": {
     "type": "git",
@@ -20,13 +20,13 @@
   },
   "homepage": "https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/analytics/README.md",
   "dependencies": {
-    "analytics": "^0.8.14",
-    "vite": "~5.0.0"
+    "analytics": "^0.8.14"
   },
   "peerDependencies": {
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "vite": "~5.0.0",
     "@testing-library/jest-dom": "^6.1.6",
     "@testing-library/react": "^14.0.0"
   },

package/react/{index.mjs → index.js}

@@ -1,5 +1,5 @@
-import { DotContentAnalyticsProvider as e } from "../lib/react/components/DotContentAnalyticsProvider.mjs";
-import { useContentAnalytics as r } from "../lib/react/hook/useContentAnalytics.mjs";
+import { DotContentAnalyticsProvider as e } from "../lib/react/components/DotContentAnalyticsProvider.js";
+import { useContentAnalytics as r } from "../lib/react/hook/useContentAnalytics.js";
 export {
   e as DotContentAnalyticsProvider,
   r as useContentAnalytics