Google Analytics

✅ Users - Active users, new users, returning users
✅ Sessions - Total sessions, bounce rate, average session duration
✅ Page Views - Total page views, unique page views
✅ Engagement - Average time on page, pages per session
✅ Geography - User locations (country, city)
✅ Device - Desktop, mobile, tablet breakdown
✅ Traffic Sources - How users find your content

Google Analytics uses Service Account authentication which provides:

• Permanent access (no token expiration)
• Automated data collection
• Secure server-to-server communication
• No need for user interaction after setup

Before setting up the integration, ensure you have:

1. A Google Analytics 4 property (Universal Analytics is no longer supported)
2. Google Analytics tracking code installed on your website
3. Admin access to your Google Analytics property
4. A Google account to access Google Cloud Console

🔑 Part 1: Google Cloud Console Setup

1. Access Google Cloud Console

• Go to Google Cloud Console
• Sign in with your Google account

2. Select or Create a Project

• At the top of the page, click the project dropdown
• Either select an existing project or click “NEW PROJECT”
• If creating new, give it a name (e.g., “ContentCompass Analytics”) and click “CREATE”

3. Enable the Google Analytics Data API

• In the navigation menu (☰), go to “APIs & Services” → “Library”
• Search for “Google Analytics Data API”
• Click on it from the search results
• Click the “ENABLE” button and wait for it to activate

4. Create a Service Account

• Go to “APIs & Services” → “Credentials”
• Click ”+ CREATE CREDENTIALS” at the top
• Select “Service account” from the dropdown

5. Configure Service Account Details

• Service account name: Give it a descriptive name (e.g., “contentcompass-ga-access”)
• Service account ID: Auto-generated based on the name (leave as is)
• Description: (Optional) “ContentCompass analytics data access”
• Click “CREATE AND CONTINUE”

6. Skip Optional Steps

• Grant this service account access to project: Click “CONTINUE” to skip
• Grant users access to this service account: Click “DONE” to skip

7. Download the JSON Key File

• Find your new service account in the credentials list
• Click on the email address to open it
• Go to the “KEYS” tab
• Click “ADD KEY” → “Create new key”
• Select “JSON” as the key type
• Click “CREATE”
• Important: A JSON file will download. Keep this file secure - it’s your private key!

📊 Part 2: Grant Google Analytics Access

1. Copy the Service Account Email

• Open the downloaded JSON file in a text editor
• Find the line with "client_email":
• Copy the email address (looks like: your-service-account@project-id.iam.gserviceaccount.com)

2. Add Service Account to Google Analytics

• Go to Google Analytics
• Select your GA4 property
• Click Admin (gear icon ⚙️) in the bottom-left corner
• In the “Property” column, click “Property Access Management”
• Click the blue ”+” button in the top right
• Paste the service account email address
• Select “Viewer” role (sufficient for reading data)
• Uncheck “Notify users by email”
• Click “Add”

💻 Part 3: Add Credentials to ContentCompass

1. Get Your GA4 Property ID

• Still in Google Analytics Admin
• Under “Property” column, click “Property Settings”
• Copy your Property ID (9-digit number)

2. Add to ContentCompass

1. Navigate to Credentials in ContentCompass
2. Click “New Credential”
3. Select “Google Analytics” as the platform
4. Authentication type will auto-select to “API Key”
5. In the “Service Account JSON Key” field:
   • Open your downloaded JSON file in a text editor
   • Select all content (Ctrl+A or Cmd+A)
   • Copy and paste the entire JSON content
6. Enter your GA4 Property ID
7. Give your credential a memorable name (e.g., “My Website GA4”)
8. Optionally share with your team if needed
9. Click “Create Credential”

🔗 Part 4: Connect Your Content

1. When creating or editing an idea, add your website URL to the “Published Link” field
2. ContentCompass will automatically:
   • Detect it’s a website URL
   • Use your Google Analytics credentials
   • Filter data to show metrics only for that specific URL
3. Analytics collection happens in the background
4. Data typically appears within a few minutes (if available in GA4)

URL Filtering

ContentCompass automatically filters Google Analytics data by the page path of your published URL:

• Published link: https://example.com/blog/my-post
• GA4 filter: Shows data only for /blog/my-post
• All metrics are specific to that single page

Data Collection

• Automated: Runs in the background periodically
• Date Range: Last 30 days by default
• Historical Storage: ContentCompass saves snapshots over time
• Real-time Access: Fresh data pulled from GA4 API when viewing analytics

Metric Aggregation

ContentCompass translates GA4 metrics to standard metrics:

• Views: Total page views
• Users: Active users who visited the page
• Engagement: Sessions, bounce rate, time on page
• Demographics: Geographic and device breakdowns

No Data Showing

1. Verify GA4 Installation: Check that your website has GA4 tracking code
2. Check GA4 Real-time: Confirm data appears in GA4 real-time reports
3. Wait for Data: New content may take 24-48 hours to accumulate meaningful data
4. Verify Property ID: Ensure you entered the correct 9-digit property ID
5. Check Permissions: Confirm service account has Viewer access in GA4

Authentication Errors

1. Invalid JSON: Ensure you pasted the complete JSON file contents
2. Wrong Property ID: Verify the property ID matches your GA4 property
3. Access Not Granted: Check service account is added to GA4 with Viewer role
4. API Not Enabled: Ensure Google Analytics Data API is enabled in Cloud Console

Missing or Wrong Metrics

1. URL Mismatch: Verify the URL in ContentCompass matches your website
2. Data Sampling: High-traffic sites may show sampled data
3. Processing Delay: GA4 may take up to 48 hours to process data
4. Filters in GA4: Check if GA4 has filters that might exclude data

1. Security
   • Never share your service account JSON key publicly
   • Store credentials securely in ContentCompass
   • Use Viewer role (read-only) for safety
2. Setup
   • Use GA4 properties (Universal Analytics no longer supported)
   • Verify GA4 tracking before adding to ContentCompass
   • Test with a page that has existing traffic
3. Monitoring
   • Check analytics weekly for trends
   • Set up GA4 goals for meaningful conversions
   • Use UTM parameters to track traffic sources
   • Combine with social media metrics for full picture

• Quotas: 50,000 requests per day per project
• Rate Limits: 10 queries per second per project
• Data Freshness: 24-48 hour processing delay
• Data Retention: Subject to your GA4 retention settings
• Sampling: Large datasets may be sampled

• ContentCompass only requests read-only access
• Service account credentials are encrypted
• No personal user data is stored
• Only aggregated metrics are displayed
• Ensure compliance with your local privacy laws

This integration uses the Google Analytics Data API v1 for GA4. Updates will be made as the API evolves or new features become available.