Skip to main content

Analytics Guide

Track and analyze engagement metrics. Bellamy Book exposes in-app analytics APIs and supports optional Google Analytics 4 (GA4) for product/marketing tracking.

Google Analytics 4 (GA4)​

1. Create GA4 property and data streams​

  • Create a Google Analytics 4 property in the Google Analytics UI.
  • Under that property, create web data streams:
    • One for https://bellamybook.com (or your own app domain).
    • Optionally one for https://docs.bellamybook.com (or your docs domain).
  • Copy the Measurement ID for each web stream (format: G-XXXXXXXXXX).

2. Configure GA4 for the frontend app (bellamybook.com)​

The frontend SPA reads its GA4 measurement ID from runtime environment variables, so the same Docker image can be reused for different domains without rebuilds.

  • For the official dockerProd deployment:

    • Edit dockerProd/.env and set:

      GA4_FRONTEND_MEASUREMENT_ID=G-XXXXXXXXXX

    • dockerProd/docker-compose.yml passes this into the frontend container, and Src/frontend/docker-entrypoint.sh writes it into /usr/share/nginx/html/config.js as window.__APP_CONFIG__.ga4MeasurementId.

    • The React app (Src/frontend/src/App.jsx) initializes GA4 and tracks SPA page views whenever routes change.

  • For self-hosters using dockerPublish:

    • Copy .env.example to .env in the dockerPublish folder.

    • Optionally set:

      GA4_FRONTEND_MEASUREMENT_ID=G-XXXXXXXXXX

    • If left empty, GA4 is disabled and no tracking requests are sent.

3. Configure GA4 for the docs app (docs.bellamybook.com)​

The docs app is a separate Docusaurus site built into its own Docker image.

  • At build time, set the env/ARG:

    # Example CI / local build
    GA4_DOCS_MEASUREMENT_ID=G-YYYYYYYYYY docker build -t bellamy-book-docs Src/docs-app

  • docusaurus.config.js reads process.env.GA4_DOCS_MEASUREMENT_ID and, when set, enables the @docusaurus/plugin-google-gtag plugin with that measurement ID.

  • If you do not set GA4_DOCS_MEASUREMENT_ID, the docs app will build and run without GA4 tracking.

Bellamy Book focuses on page views out of the box (SPA route changes are tracked automatically). You can add custom events in your fork if needed:

  • Auth / lifecycle: login, sign_up, logout.
  • Content: create_post, react_post, comment_post, share_post.
  • Messaging: send_message, start_call, join_group_chat.

For custom events, use the trackEvent helper in Src/frontend/src/analytics/ga4.js.

Post Analytics​

Get Post Analytics​

GET /api/Post/{postId}/statistics?requestingUserId=... (post owner only)

Returns:

  • View count
  • Reaction count (by type)
  • Comment count
  • Share count
  • Engagement rate

Get User Post Analytics​

GET /api/admin/dashboard/posts (admin) or user/post analytics endpoints

User Analytics​

Get User Activity​

GET /api/admin/dashboard/overview (admin) or activity endpoints

Returns:

  • Posts created
  • Comments made
  • Reactions given
  • Messages sent
  • Active days

Content Performance​

Top Performing Posts​

GET /api/analytics/posts/top?period=week&limit=10
GET /api/analytics/engagement/trends?period=month

Recommendation Insights​

Content Recommendations​

GET /api/recommendations/content

Friend Suggestions​

GET /api/recommendations/friends

Admin Analytics​

Platform Statistics​

GET /api/admin/analytics/overview

Returns:

  • Total users
  • Active users
  • Posts created
  • Engagement metrics
  • Growth trends

Learn More​