Skip to content

Commit 6bec826

Browse files
fmontesfmontes
authored
Merge pull request #2 from dotCMS/fix/ga4-compatibility
Fix GA4 compatibility and add automation
2 parents 3597003 + 768a0ca commit 6bec826

5 files changed

Lines changed: 418 additions & 5 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Build and Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths-ignore:
8+
- '**.md'
9+
- '.gitignore'
10+
11+
jobs:
12+
build-and-release:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
19+
- name: Set up JDK 21
20+
uses: actions/setup-java@v4
21+
with:
22+
java-version: '21'
23+
distribution: 'microsoft'
24+
25+
- name: Grant execute permission for gradlew
26+
run: chmod +x gradlew
27+
28+
- name: Build with Gradle
29+
run: ./gradlew clean jar
30+
31+
- name: Get version from build.gradle
32+
id: get_version
33+
run: |
34+
VERSION=$(grep "^version = " build.gradle | cut -d "'" -f 2)
35+
echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
36+
echo "Building version $VERSION"
37+
38+
- name: Check if release exists
39+
id: check_release
40+
run: |
41+
RELEASE_EXISTS=$(gh release view "v${{ steps.get_version.outputs.VERSION }}" > /dev/null 2>&1 && echo "true" || echo "false")
42+
echo "EXISTS=$RELEASE_EXISTS" >> $GITHUB_OUTPUT
43+
env:
44+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
45+
46+
- name: Create GitHub Release
47+
if: steps.check_release.outputs.EXISTS == 'false'
48+
uses: softprops/action-gh-release@v1
49+
with:
50+
tag_name: v${{ steps.get_version.outputs.VERSION }}
51+
name: Release ${{ steps.get_version.outputs.VERSION }}
52+
body: |
53+
## Google Analytics Plugin v${{ steps.get_version.outputs.VERSION }}
54+
55+
### Installation
56+
1. Download `google-analytics-${{ steps.get_version.outputs.VERSION }}.jar`
57+
2. Upload to dotCMS via System → Dynamic Plugins
58+
3. Configure via System → Apps → Google Analytics
59+
60+
### What's Changed
61+
See commit history for details.
62+
63+
**Full Changelog**: https://github.com/${{ github.repository }}/commits/v${{ steps.get_version.outputs.VERSION }}
64+
files: |
65+
build/libs/google-analytics-*.jar
66+
draft: false
67+
prerelease: false
68+
env:
69+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎CONTRIBUTING.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Contributing to Google Analytics Plugin for dotCMS
2+
3+
Thank you for your interest in contributing! We welcome pull requests that improve the plugin.
4+
5+
## Pull Requests
6+
7+
#### Before You Start
8+
9+
1. **Keep changes focused** - One feature/fix per PR
10+
2. **Fork the repository** - Work on your own fork
11+
12+
#### Development Setup
13+
14+
1. **Fork and clone the repository**
15+
```bash
16+
git fork https://github.com/dotCMS/google-analytics.git
17+
cd google-analytics
18+
```
19+
20+
2. **Create a feature branch**
21+
```bash
22+
git checkout -b feature/your-feature-name
23+
# or
24+
git checkout -b fix/issue-description
25+
```
26+
27+
3. **Set up your development environment**
28+
- JDK 11 or higher
29+
- Gradle (included via wrapper)
30+
- A running dotCMS instance for testing (local or Docker)
31+
32+
4. **Build the plugin**
33+
```bash
34+
./gradlew clean jar
35+
```
36+
37+
The JAR will be in `build/libs/google-analytics-X.X.X.jar`
38+
39+
#### Making Changes
40+
41+
1. **Write clean, readable code**
42+
- Follow existing code style and patterns
43+
- Add comments for complex logic
44+
- Keep methods focused and concise
45+
46+
2. **Test your changes**
47+
- Build the plugin: `./gradlew jar`
48+
- Upload to a dotCMS instance
49+
- Test with real Google Analytics data
50+
- Verify OSGi bundle loads without errors
51+
- Test Velocity viewtool functionality
52+
53+
3. **Update documentation**
54+
- Update README.md if you changed functionality
55+
- Add/update code comments
56+
- Document new viewtool methods or parameters
57+
58+
4. **Commit your changes**
59+
```bash
60+
git add .
61+
git commit -m "Brief description of changes
62+
63+
Longer explanation of what changed and why.
64+
Include any breaking changes or migration notes."
65+
```
66+
67+
**Commit message guidelines:**
68+
- Use present tense ("Add feature" not "Added feature")
69+
- Be concise but descriptive
70+
- Reference issues when applicable (`Fixes #123`)
71+
72+
#### Submitting Your PR
73+
74+
1. **Push to your fork**
75+
```bash
76+
git push origin feature/your-feature-name
77+
```
78+
79+
2. **Create a Pull Request**
80+
- Go to the [repository](https://github.com/dotCMS/google-analytics)
81+
- Click "New Pull Request"
82+
- Select your fork and branch
83+
- Fill out the PR template with:
84+
- **What changed** - Clear description of changes
85+
- **Why** - The problem this solves
86+
- **Testing** - How you tested the changes
87+
- **Breaking changes** - Any compatibility issues
88+
- **Related issues** - Link to related issues
89+
90+
3. **Address review feedback**
91+
- Be responsive to comments
92+
- Make requested changes in new commits
93+
- Ask questions if feedback is unclear
94+
95+
## Development Guidelines
96+
97+
### Code Style
98+
99+
- **Java**: Follow standard Java conventions
100+
- **Indentation**: 4 spaces (no tabs)
101+
- **Braces**: Opening brace on same line
102+
- **Naming**:
103+
- Classes: `PascalCase`
104+
- Methods/variables: `camelCase`
105+
- Constants: `UPPER_SNAKE_CASE`
106+
107+
### OSGi Considerations
108+
109+
When adding dependencies:
110+
111+
1. **Check if dotCMS already provides it** - Use `compileOnly` if yes
112+
2. **Bundle third-party libraries** - Add to `osgiLibs` configuration
113+
3. **Update Import-Package** - Exclude bundled packages from imports
114+
4. **Test OSGi wiring** - Verify bundle loads in clean dotCMS instance
115+
116+
Example from `build.gradle`:
117+
```gradle
118+
dependencies {
119+
compileOnly('com.dotcms:dotcms:23.01.10') { transitive = true }
120+
implementation (group: 'your.library', name: 'artifact', version: '1.0.0')
121+
osgiLibs (group: 'your.library', name: 'artifact', version: '1.0.0')
122+
}
123+
124+
'Import-Package': '''
125+
!your.library.*,
126+
javax.*,
127+
com.dotcms.*,
128+
...
129+
'''
130+
```
131+
132+
### Testing Checklist
133+
134+
Before submitting a PR, verify:
135+
136+
- [ ] Plugin builds without errors: `./gradlew clean jar`
137+
- [ ] JAR uploads successfully to dotCMS
138+
- [ ] OSGi bundle starts without errors (check logs for "Starting Google Analytics OSGI plugin")
139+
- [ ] Viewtool is available in Velocity (`$analytics`)
140+
- [ ] Can create analytics request and query GA4 data
141+
- [ ] No breaking changes to existing Velocity code (or documented if necessary)
142+
- [ ] Works with dotCMS 23.01.10 and newer
143+
144+
## Versioning
145+
146+
This plugin follows [Semantic Versioning](https://semver.org/):
147+
148+
- **Major (X.0.0)**: Breaking changes
149+
- **Minor (0.X.0)**: New features, backward compatible
150+
- **Patch (0.0.X)**: Bug fixes, backward compatible
151+
152+
**IMPORTANT:** Bump the version in `build.gradle` for each PR that should trigger a new release:
153+
154+
```gradle
155+
version = '0.4.2' // Increment for your changes
156+
```
157+
158+
When merged to main, GitHub Actions will:
159+
1. Check if release `v0.4.2` exists
160+
2. If not, build the JAR and create the release
161+
3. If yes, skip release creation (no duplicates)
162+
163+
**Always bump the version** to ensure your changes are trackable in releases.
164+
165+
## Release Process
166+
167+
Releases are automated via GitHub Actions:
168+
169+
1. PR is merged to `main`
170+
2. GitHub Actions builds the plugin
171+
3. Creates a GitHub release with the JAR attached
172+
4. Tags the release with version from `build.gradle`
173+
174+
Only maintainers can merge to `main` and trigger releases.
175+
176+
## Questions?
177+
178+
- **General questions**: [dotCMS Community Forums](https://dotcms.com/forums)
179+
- **dotCMS development**: [dotCMS Developer Docs](https://dotcms.com/docs)
180+
181+
## License
182+
183+
By contributing, you agree that your contributions will be licensed under the same terms as the project.
184+
185+
---
186+
187+
Thank you for contributing to make dotCMS better! 🎉

‎README.md‎

Lines changed: 138 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,138 @@
1-
# google-analytics
2-
Provides an integration with google analytics
1+
# Google Analytics Plugin for dotCMS
2+
3+
OSGi plugin that integrates Google Analytics 4 (GA4) Data API with dotCMS, enabling you to fetch analytics data programmatically via Velocity viewtools.
4+
5+
[![Build and Release](https://github.com/dotCMS/google-analytics/actions/workflows/release.yml/badge.svg)](https://github.com/dotCMS/google-analytics/releases)
6+
7+
## What It Does
8+
9+
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.
10+
11+
**Note:** This plugin *fetches* analytics data from Google Analytics. It does NOT add tracking code to your site.
12+
13+
## Quick Start
14+
15+
### Prerequisites
16+
17+
- dotCMS 23.01.10 or higher
18+
- Google Cloud Platform account with billing enabled
19+
- Google Analytics 4 property with data to query
20+
- Service account JSON credentials from Google Cloud
21+
22+
### Installation
23+
24+
1. **Download the latest release**
25+
- Go to [Releases](https://github.com/dotCMS/google-analytics/releases)
26+
- Download `google-analytics-X.X.X.jar`
27+
28+
2. **Upload to dotCMS**
29+
- Log into dotCMS as admin
30+
- Go to **System → Dynamic Plugins**
31+
- Click **Upload Plugin**
32+
- Select the JAR file
33+
34+
3. **Configure the App**
35+
- Go to **System → Apps → Google Analytics**
36+
- **Application Name**: Any name (e.g., "My GA4 Property")
37+
- **Json Key File**: Paste your Google Cloud service account JSON credentials
38+
- Click **Save**
39+
40+
### Basic Usage
41+
42+
```velocity
43+
<h2>Last 7 Days Analytics</h2>
44+
45+
## Your GA4 property ID (just the number)
46+
#set($propertyId = "488595222")
47+
48+
## Create and configure request
49+
#set($gaRequest = $analytics.createAnalyticsRequest($propertyId))
50+
$gaRequest.setStartDate("2026-02-09")
51+
$gaRequest.setEndDate("2026-02-16")
52+
$gaRequest.setMetrics("sessions,activeUsers")
53+
$gaRequest.setDimensions("date")
54+
55+
## Execute query
56+
#set($gaResponse = $analytics.query($gaRequest))
57+
58+
## Display results
59+
<table>
60+
<thead>
61+
<tr><th>Date</th><th>Sessions</th><th>Active Users</th></tr>
62+
</thead>
63+
<tbody>
64+
#foreach($row in $gaResponse.getRowsList())
65+
<tr>
66+
<td>$row.getDimensionValues(0).getValue()</td>
67+
<td>$row.getMetricValues(0).getValue()</td>
68+
<td>$row.getMetricValues(1).getValue()</td>
69+
</tr>
70+
#end
71+
</tbody>
72+
</table>
73+
```
74+
75+
## Documentation
76+
77+
For complete setup instructions including Google Cloud configuration, Google Analytics permissions, advanced usage, and troubleshooting:
78+
79+
**📖 [Full Integration Guide](https://www.dotcms.com/integrations/google-analytics)**
80+
81+
### Key Topics Covered
82+
83+
- **Google Cloud Platform Setup** - Creating service accounts and enabling the Analytics Data API
84+
- **Google Analytics Configuration** - Granting access and finding your property ID
85+
- **Advanced Queries** - Filters, dimensions, metrics, and data processing
86+
- **Troubleshooting** - OSGi issues, metric errors, variable name conflicts
87+
- **Available Metrics & Dimensions** - GA4 API schema reference
88+
89+
## Available Metrics
90+
91+
Common GA4 metrics you can query:
92+
- `sessions` - Number of sessions
93+
- `activeUsers` - Number of distinct users
94+
- `screenPageViews` - Total page and screen views
95+
- `bounceRate` - Percentage of single-page sessions
96+
- `averageSessionDuration` - Average session duration in seconds
97+
98+
See the [GA4 API Schema](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema) for the full list.
99+
100+
## Version History
101+
102+
### 0.4.1 (Current)
103+
- ✅ GA4 compatibility - Changed default metric from `ga:visits` to `sessions`
104+
- ✅ Fixed OSGi dependency resolution for local/Docker deployments
105+
- ✅ Added proper Import-Package whitelist for dotCMS classes
106+
- ✅ Bundle all Google Analytics Data API dependencies inside plugin JAR
107+
- Compatible with dotCMS 23.01.10+
108+
109+
## Building from Source
110+
111+
```bash
112+
git clone https://github.com/dotCMS/google-analytics.git
113+
cd google-analytics
114+
./gradlew jar
115+
```
116+
117+
The JAR will be in `build/libs/google-analytics-0.4.1.jar`
118+
119+
## Contributing
120+
121+
Contributions are welcome! Please:
122+
123+
1. Fork the repository
124+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
125+
3. Make your changes
126+
4. Commit with clear messages
127+
5. Push to your branch
128+
6. Open a Pull Request
129+
130+
## Support
131+
132+
- **Issues & Bugs:** [GitHub Issues](https://github.com/dotCMS/google-analytics/issues)
133+
- **Documentation:** [dotCMS Integration Guide](https://www.dotcms.com/integrations/google-analytics)
134+
- **dotCMS Docs:** [www.dotcms.com/docs](https://www.dotcms.com/docs)
135+
136+
## License
137+
138+
This plugin is provided as-is by dotCMS.

0 commit comments

Comments
 (0)