Skip to content

Commit de2fea8

Browse files
MantisCloneMantisClone
committed
Add Google Analytics 4 integration for beta docs
- Add GA4 measurement ID to docs.json for unified tracking across website and docs - Add setup guide (GOOGLE_ANALYTICS_SETUP.md) documenting single-stream approach - Add quick reference (GET_GA4_MEASUREMENT_ID.md) for finding GA4 measurement ID - Uses same GA4 property as main website for seamless path exploration
1 parent d60b5b2 commit de2fea8

File tree

3 files changed

+273
-0
lines changed

3 files changed

+273
-0
lines changed

‎GET_GA4_MEASUREMENT_ID.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# How to Find Your GA4 Measurement ID
2+
3+
## Quick Steps
4+
5+
1. **Go to Google Analytics**
6+
- Visit [analytics.google.com](https://analytics.google.com)
7+
- Sign in with your Google account
8+
9+
2. **Navigate to Admin Settings**
10+
- Click the **gear icon (⚙️)** in the bottom left corner
11+
- This opens the Admin panel
12+
13+
3. **Select Your Property**
14+
- In the middle column under **Property**, make sure your website property is selected
15+
- If you have multiple properties, select the one for your main website (request.network)
16+
17+
4. **Open Data Streams**
18+
- Under the **Property** column, click **Data Streams**
19+
- You'll see a list of all data streams (web, iOS, Android)
20+
21+
5. **Select Your Web Stream**
22+
- Click on your web data stream (usually shows your website URL)
23+
- This opens the stream details
24+
25+
6. **Copy the Measurement ID**
26+
- At the top right, you'll see **Measurement ID**
27+
- Format: `G-XXXXXXXXXX` (starts with "G-")
28+
- Click the copy icon next to it
29+
30+
## Visual Path
31+
32+
```
33+
Google Analytics Dashboard
34+
└─ Admin (⚙️ bottom left)
35+
└─ Property Column (middle)
36+
└─ Data Streams
37+
└─ Web Stream (your website)
38+
└─ Measurement ID: G-XXXXXXXXXX
39+
```
40+
41+
## What You're Looking For
42+
43+
The Measurement ID looks like this:
44+
- **Format**: `G-XXXXXXXXXX`
45+
- **Example**: `G-1A2B3C4D5E`
46+
- **Starts with**: `G-` (not UA- which is old Universal Analytics)
47+
48+
## Common Issues
49+
50+
### Can't Find Admin Button
51+
- Make sure you have Editor or Administrator access to the GA4 property
52+
- If you only see "Account Access Management" in Admin, you don't have property access
53+
54+
### See "UA-" Instead of "G-"
55+
- You're looking at Universal Analytics (old version)
56+
- Make sure you're in a **GA4 property**, not a Universal Analytics property
57+
- GA4 properties show "GA4" badge next to the property name
58+
59+
### Multiple Properties Listed
60+
- Look for the one associated with `request.network` (your main website)
61+
- If unsure, check the website URL shown in the data stream
62+
63+
### No Data Streams Listed
64+
- Click "Add Stream" → "Web"
65+
- Follow the setup wizard to create one
66+
- You'll get a new Measurement ID
67+
68+
## After You Get the ID
69+
70+
1. Open `/Users/mantisclone/projects/mintlify-docs/docs.json`
71+
2. Find the `integrations` section:
72+
```json
73+
"integrations": {
74+
"ga4": {
75+
"measurementId": "G-XXXXXXXXXX"
76+
}
77+
}
78+
```
79+
3. Replace `G-XXXXXXXXXX` with your actual Measurement ID
80+
4. Save the file
81+
5. Commit and push to deploy
82+
83+
## Verification
84+
85+
After deploying:
86+
1. Install [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna) Chrome extension
87+
2. Visit your deployed docs site
88+
3. Open Chrome DevTools (F12) → Console tab
89+
4. Enable the GA Debugger extension
90+
5. Reload the page
91+
6. Look for "Running command: event" messages - this confirms GA4 is working
92+
93+
## Need Help?
94+
95+
If you can't find your Measurement ID or don't have access:
96+
- Ask your Google Analytics administrator for the Measurement ID
97+
- Or request Editor access to the GA4 property
98+
- The ID is safe to share (it's public in your website's HTML anyway)

‎GOOGLE_ANALYTICS_SETUP.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Google Analytics 4 Setup for Mintlify Docs
2+
3+
## Overview
4+
5+
This document outlines the recommended approach for tracking your beta Mintlify documentation using the same Google Analytics 4 property as your main website.
6+
7+
## Configuration Approach
8+
9+
### Strategy: Single GA4 Property, Single Data Stream
10+
11+
**Why this approach:**
12+
- Enables seamless path exploration across website → docs
13+
- Simplifies reporting and analysis
14+
- No need for cross-domain tracking (docs are on a subdomain)
15+
- Maintains unified user journey tracking
16+
17+
## Setup Steps
18+
19+
### 1. Get Your GA4 Measurement ID
20+
21+
1. Go to [Google Analytics](https://analytics.google.com)
22+
2. Navigate to **Admin** (bottom left)
23+
3. Under **Property**, select your website property
24+
4. Click **Data Streams**
25+
5. Select your web data stream
26+
6. Copy the **Measurement ID** (format: `G-XXXXXXXXXX`)
27+
28+
### 2. Add to Mintlify Configuration
29+
30+
In `docs.json`, the measurement ID has been added:
31+
32+
```json
33+
"integrations": {
34+
"ga4": {
35+
"measurementId": "G-XXXXXXXXXX"
36+
}
37+
}
38+
```
39+
40+
**Replace `G-XXXXXXXXXX` with your actual measurement ID.**
41+
42+
### 3. Deploy and Verify
43+
44+
1. Commit and push changes to your repository
45+
2. Wait 2-3 minutes for Mintlify to deploy
46+
3. Visit your docs site
47+
4. Use [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger) Chrome extension
48+
5. Open browser console - you should see GA4 events being logged
49+
50+
### 4. Configure GA4 for Subdomain Tracking (Optional but Recommended)
51+
52+
In Google Analytics:
53+
54+
1. Go to **Admin** → **Data Streams** → Select your stream
55+
2. Click **Configure tag settings**
56+
3. Click **Show all** under "Settings"
57+
4. Under **Domains**, verify your subdomain is included
58+
5. Enable **Enhanced measurement** for automatic event tracking
59+
60+
## Expected Behavior
61+
62+
### What Gets Tracked
63+
64+
- **Page views** on both website and docs
65+
- **User journeys** from website → docs (and vice versa)
66+
- **Engagement metrics**: scroll depth, outbound clicks, site search
67+
- **Custom events**: Can be configured later if needed
68+
69+
### Path Exploration
70+
71+
In GA4, navigate to:
72+
- **Reports** → **Engagement** → **Pages and screens**
73+
- Use the **Path exploration** template
74+
- Filter or segment by hostname to separate website vs. docs traffic
75+
76+
### Filtering Beta vs. Production
77+
78+
Create custom segments or filters:
79+
1. **Admin** → **Data Settings** → **Data Filters**
80+
2. Or use **Explore** → **Segments** to create audience segments
81+
3. Filter by hostname, page path, or custom dimensions
82+
83+
## Important Notes
84+
85+
### Timeline
86+
- Google Analytics takes **2-3 days** to show data in reports
87+
- Real-time reporting shows data immediately for verification
88+
89+
### Preview Links
90+
- Mintlify preview links have analytics **disabled by default**
91+
- Only production/deployed docs will send analytics data
92+
93+
### Cross-Domain vs. Subdomain
94+
- **You do NOT need cross-domain measurement** for subdomains
95+
- Cross-domain is only for different root domains (e.g., `example.com` and `partner.com`)
96+
- Your docs subdomain will automatically track user sessions from the main site
97+
98+
## Recommended GA4 Configuration
99+
100+
### Custom Dimensions (Optional)
101+
102+
Consider adding these for better segmentation:
103+
104+
1. **Documentation Section** - Track which docs section users visit
105+
2. **Beta Flag** - Mark all current traffic as "beta"
106+
3. **Source Domain** - Explicitly tag traffic source (website vs. direct to docs)
107+
108+
### Events to Monitor
109+
110+
- **Outbound link clicks** (API portal, GitHub, etc.)
111+
- **Search queries** (if you enable docs search)
112+
- **Code snippet interactions** (if Mintlify supports this)
113+
- **Feedback submissions**
114+
115+
## Transition Plan: Beta → Production
116+
117+
When you replace Gitbook with Mintlify:
118+
119+
### Option 1: Immediate Cutover
120+
1. Keep the same GA4 measurement ID
121+
2. Traffic seamlessly continues
122+
3. You'll see hostname change in reports from Gitbook domain to Mintlify domain
123+
124+
### Option 2: Gradual Migration
125+
1. Run both Gitbook and Mintlify with the same GA4 ID
126+
2. Use hostname filter to separate traffic
127+
3. Compare metrics side-by-side
128+
4. Deprecate Gitbook when confident
129+
130+
## Troubleshooting
131+
132+
### Analytics Not Showing Up
133+
134+
1. **Check Measurement ID format**: Must be `G-XXXXXXXXXX`
135+
2. **Verify deployment**: Changes must be pushed and deployed by Mintlify
136+
3. **Use GA Debugger**: Install Chrome extension to see live events
137+
4. **Check preview vs. production**: Preview links don't send analytics
138+
139+
### Path Exploration Not Working
140+
141+
1. **Enable User-ID tracking** (if applicable)
142+
2. **Check cookie consent**: Ensure GA cookies are allowed
143+
3. **Verify subdomain configuration** in GA4 data stream settings
144+
145+
### Data Discrepancies
146+
147+
- GA4 uses different methodology than Universal Analytics
148+
- Expect 5-10% variance between properties
149+
- Focus on trends rather than absolute numbers
150+
151+
## Resources
152+
153+
- [Mintlify Analytics Documentation](https://mintlify.com/docs/integrations/analytics/google-analytics)
154+
- [GA4 Documentation](https://support.google.com/analytics/answer/9304153)
155+
- [Google Analytics Debugger Extension](https://chrome.google.com/webstore/detail/google-analytics-debugger)
156+
- [Path Exploration in GA4](https://support.google.com/analytics/answer/9317498)
157+
158+
## Decision Log
159+
160+
**Decision**: Add GA4 tracking to beta docs immediately
161+
**Rationale**: Historical data is valuable; beta traffic patterns inform structural decisions; can filter/segment later
162+
163+
**Decision**: Use same GA4 property as main website
164+
**Rationale**: Enables unified path exploration; simpler setup; docs are on subdomain (not separate domain)
165+
166+
**Decision**: Single data stream approach
167+
**Rationale**: Docs are on subdomain; no cross-domain measurement needed; unified user journey tracking
168+
169+
**Decision**: No separate property or stream for beta vs. production
170+
**Rationale**: Can filter/segment by date or custom dimensions; maintaining continuity of data is more valuable

‎docs.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,11 @@
216216
"vscode"
217217
]
218218
},
219+
"integrations": {
220+
"ga4": {
221+
"measurementId": "G-F4XSSNMEN6"
222+
}
223+
},
219224
"footer": {
220225
"socials": {
221226
"x": "https://x.com/RequestNetwork",

0 commit comments

Comments
 (0)