Merge pull request #3 from dotCMS/feature/rest-endpoint

Add REST endpoint for headless Google Analytics queries

Author: fmontes

CONTRIBUTING.md

@@ -136,7 +136,7 @@ Before submitting a PR, verify:
 - [ ] Plugin builds without errors: `./gradlew clean jar`
 - [ ] JAR uploads successfully to dotCMS
 - [ ] OSGi bundle starts without errors (check logs for "Starting Google Analytics OSGI plugin")
-- [ ] Viewtool is available in Velocity (`$analytics`)
+- [ ] Viewtool is available in Velocity (`$googleanalytics`)
 - [ ] Can create analytics request and query GA4 data
 - [ ] No breaking changes to existing Velocity code (or documented if necessary)
 - [ ] Works with dotCMS 23.01.10 and newer

README.md

@@ -6,7 +6,7 @@ OSGi plugin that integrates Google Analytics 4 (GA4) Data API with dotCMS, enabl
 
 ## What It Does
 
-This plugin provides a `$analytics` viewtool in Velocity templates for querying Google Analytics 4 data directly from your dotCMS pages. Retrieve metrics like sessions, active users, page views, and more—filtered by dimensions like date, page path, device category, etc.
+This plugin provides a `$googleanalytics` viewtool in Velocity templates for querying Google Analytics 4 data directly from your dotCMS pages. Retrieve metrics like sessions, active users, page views, and more—filtered by dimensions like date, page path, device category, etc.
 
 **Note:** This plugin *fetches* analytics data from Google Analytics. It does NOT add tracking code to your site.
 
@@ -46,14 +46,14 @@ This plugin provides a `$analytics` viewtool in Velocity templates for querying
 #set($propertyId = "123456789")
 
 ## Create and configure request
-#set($gaRequest = $analytics.createAnalyticsRequest($propertyId))
+#set($gaRequest = $googleanalytics.createAnalyticsRequest($propertyId))
 $gaRequest.setStartDate("2026-02-09")
 $gaRequest.setEndDate("2026-02-16")
 $gaRequest.setMetrics("sessions,activeUsers")
 $gaRequest.setDimensions("date")
 
 ## Execute query
-#set($gaResponse = $analytics.query($gaRequest))
+#set($gaResponse = $googleanalytics.query($gaRequest))
 
 ## Display results
 <table>
@@ -72,6 +72,58 @@ $gaRequest.setDimensions("date")
 </table>
 ```
 
+### REST API Usage
+
+Query Google Analytics data via REST endpoint:
+
+```bash
+curl -X POST http://localhost:8080/api/v1/googleanalytics/query \
+  -H "Content-Type: application/json" \
+  -u admin@dotcms.com:admin \
+  -d '{
+    "propertyId": "123456789",
+    "startDate": "2026-02-09",
+    "endDate": "2026-02-16",
+    "metrics": ["sessions", "activeUsers"],
+    "dimensions": ["date", "pagePath"],
+    "filters": {
+      "dimension": [
+        {"field": "pagePath", "value": "/products", "operator": "CONTAINS"}
+      ]
+    },
+    "sort": "sessions",
+    "maxResults": 100
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "rowCount": 7,
+  "dimensions": ["date", "pagePath"],
+  "metrics": ["sessions", "activeUsers"],
+  "rows": [
+    {
+      "date": "20260209",
+      "pagePath": "/products",
+      "sessions": "150",
+      "activeUsers": "120"
+    },
+    {
+      "date": "20260210",
+      "pagePath": "/home",
+      "sessions": "200",
+      "activeUsers": "180"
+    }
+  ],
+  "metadata": {
+    "currencyCode": "USD",
+    "timeZone": "America/New_York"
+  }
+}
+```
+
 ## Documentation
 
 For complete setup instructions including Google Cloud configuration, Google Analytics permissions, advanced usage, and troubleshooting:
@@ -86,16 +138,46 @@ For complete setup instructions including Google Cloud configuration, Google Ana
 - **Troubleshooting** - OSGi issues, metric errors, variable name conflicts
 - **Available Metrics & Dimensions** - GA4 API schema reference
 
-## Available Metrics
+## Understanding Dimensions and Metrics
+
+When querying Google Analytics, you combine **dimensions** and **metrics** to get the data you need:
+
+### Dimensions (What to group by)
 
-Common GA4 metrics you can query:
-- `sessions` - Number of sessions
+Dimensions are categorical attributes that describe your data—they answer "what are we breaking this down by?"
+
+Common dimensions:
+- `date` - When the activity happened (e.g., "20260209")
+- `pagePath` - Which page was viewed (e.g., "/products")
+- `country` - Where users are located (e.g., "United States")
+- `deviceCategory` - Device type (e.g., "desktop", "mobile", "tablet")
+- `browser` - Browser used (e.g., "Chrome", "Safari")
+- `city` - User's city (e.g., "New York")
+- `source` - Traffic source (e.g., "google", "facebook", "direct")
+
+### Metrics (What to measure)
+
+Metrics are the numerical measurements you want to analyze:
+- `sessions` - Number of sessions (visits)
 - `activeUsers` - Number of distinct users
-- `screenPageViews` - Total page and screen views
+- `screenPageViews` - Total page views
 - `bounceRate` - Percentage of single-page sessions
 - `averageSessionDuration` - Average session duration in seconds
 
-See the [GA4 API Schema](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema) for the full list.
+### Example Query
+
+"Show me sessions and active users, broken down by date and page path"
+
+```json
+{
+  "dimensions": ["date", "pagePath"],
+  "metrics": ["sessions", "activeUsers"]
+}
+```
+
+Each row in the response represents one unique combination of dimension values with its associated metrics.
+
+See the [GA4 API Schema](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema) for the complete list of available dimensions and metrics.
 
 ## Version History
 

build.gradle

@@ -8,7 +8,7 @@ plugins {
 
 
 sourceCompatibility = JavaVersion.VERSION_11
-version = '0.4.1'
+version = '0.5.0'
 
 
 repositories {
@@ -36,6 +36,7 @@ dependencies {
     //compileOnly('org.apache.httpcomponents:httpclient:4.5.9')
     // https://mvnrepository.com/artifact/javax.servlet/servlet-api
     compileOnly group: 'javax.servlet', name: 'servlet-api', version: '2.5'
+    compileOnly group: 'javax.ws.rs', name: 'javax.ws.rs-api', version: '2.1.1'
 
 }
 

src/main/java/com/dotcms/google/analytics/osgi/Activator.java

@@ -1,6 +1,7 @@
 package com.dotcms.google.analytics.osgi;
 
 import com.dotcms.google.analytics.app.AnalyticsAppService;
+import com.dotcms.google.analytics.rest.GoogleAnalyticsResource;
 import com.dotcms.google.analytics.view.AnalyticsToolInfo;
 import com.dotmarketing.business.CacheLocator;
 import com.dotmarketing.loggers.Log4jUtil;
@@ -45,6 +46,9 @@ public final void start(final BundleContext bundleContext) throws Exception {
         // copy the yaml
         copyAppYml();
 
+        // Register REST resources
+        publishBundleServices(bundleContext);
+
         // Register all ViewTool services
         registerViewToolService(bundleContext, new AnalyticsToolInfo());