FIX: improve how we track page visits (#28)

https://meta.discourse.org/t/investigating-the-page-visits-table-and-page-visit-related-questions/386914/60

Author: arpitjalan

README.md

@@ -1,5 +1,33 @@
-# **Plugin Name** Plugin
+# discourse-page-visits
 
-**Plugin Summary**
+## Project History
 
-For more information, please see: **url to meta topic**
+| Description               | Internal Topic                                   | Contributors |
+| ------------------------- | ------------------------------------------------ | ------------ |
+| Comprehensive page visit tracking and analytics system for Discourse | [project topic](https://dev.discourse.org/t/wix-data-dev-52-hours/131628/) | @discourse   |
+
+## Major Custom Features
+
+### 1. Comprehensive Page Visit Tracking System
+
+**Summary (non-technical):**
+Tracks detailed analytics about how users interact with pages on the Discourse site. Records time spent on pages, which posts were viewed, and visit patterns for both logged-in and anonymous users. Provides reliable tracking even when users close tabs or navigate away quickly.
+
+**Technical description:**
+Implements client-side page visit tracking using multiple event handlers (visibilitychange, pagehide, onPageChange) to ensure visits are logged reliably. Tracks visit duration, viewed post IDs via scroll tracking integration with screen-track service, and captures full URL, IP address, and user agent. Uses sendBeacon API for reliable delivery during page unload events. Includes duplicate prevention logic with timing checks to avoid logging visits immediately on page load. Stores visit data in page_visits table with support for both authenticated and anonymous users.
+
+### 2. Post-Level View Tracking
+
+**Summary (non-technical):**
+Tracks which specific posts within a topic were actually viewed by users as they scroll through content. This provides granular analytics about post engagement beyond just topic-level visits.
+
+**Technical description:**
+Integrates with Discourse's screen-track service to monitor scroll position and identify which posts are currently visible on screen. Uses debounced scroll event handlers to efficiently capture viewed post IDs. Stores post IDs as an array in the page_visits record, allowing analysis of which posts received the most attention during a visit.
+
+### 3. Reliable Visit Capture Across Navigation Scenarios
+
+**Summary (non-technical):**
+Ensures that page visits are accurately recorded regardless of how users leave a page - whether they navigate to another page, close the tab, switch browser tabs, or use browser back/forward buttons. This provides complete analytics coverage without missing data.
+
+**Technical description:**
+Implements multiple event listeners to capture visits in all scenarios: onPageChange for normal navigation, visibilitychange for tab switches/minimization, and pagehide for tab closure and browser navigation. Uses sendBeacon API for visibilitychange and pagehide events to ensure data is sent even during page unload. Falls back to standard AJAX for normal navigation with error handling. Includes timing validation to prevent duplicate logging from rapid page changes.

assets/javascripts/discourse/api-initializers/page-visits.js

@@ -4,50 +4,80 @@ import { withPluginApi } from "discourse/lib/plugin-api";
 
 let pageVisitData = {};
 let pageEnter;
-let pageExit;
-let visitTime;
 let viewedPostIds = [];
 let screenTrack;
 let postStream;
+let hasLoggedVisit = false;
+let scrollListenerAttached = false;
+let session;
 
 export default {
   name: "page-visits",
   initialize() {
     withPluginApi((api) => {
       screenTrack = api.container.lookup("service:screen-track");
+      session = api.container.lookup("service:session");
       const currentUser = api.getCurrentUser();
       const topicController = api.container.lookup("controller:topic");
 
-      // capture when user leaves the page
+      // capture when user leaves the page (tab switch, minimize, etc.)
       document.addEventListener("visibilitychange", () => {
         if (document.visibilityState === "hidden") {
-          if (Object.keys(pageVisitData).length > 0) {
-            setVisitTime();
-            createPageVisitRecord(pageVisitData, viewedPostIds, visitTime);
-            reset();
-          }
+          const useBeacon = true;
+          const skipTimeCheck = true;
+          flushVisitRecord(useBeacon, skipTimeCheck);
         }
       });
 
-      api.onPageChange(() => {
-        if (Object.keys(pageVisitData).length > 0) {
-          setVisitTime();
-          createPageVisitRecord(pageVisitData, viewedPostIds, visitTime);
-          reset();
+      // capture when page is being unloaded (tab close, browser back/forward)
+      window.addEventListener("pagehide", () => {
+        const useBeacon = true;
+        const skipTimeCheck = true;
+        flushVisitRecord(useBeacon, skipTimeCheck);
+      });
+
+      function setupScrollTracking(topicId, postStreamModel) {
+        // Remove existing listener if any
+        if (scrollListenerAttached) {
+          window.removeEventListener("scroll", scroll);
+          scrollListenerAttached = false;
         }
 
-        const topicId = topicController.model?.id || null;
-        postStream = topicController.model?.postStream;
-        if (topicId && postStream) {
+        // Add scroll listener if we're on a topic page
+        if (topicId && postStreamModel) {
+          postStream = postStreamModel;
           window.addEventListener("scroll", scroll, { passive: true });
+          scrollListenerAttached = true;
         }
+      }
+
+      api.onPageChange(() => {
+        // Log previous visit before navigating to new page
+        const useBeacon = false;
+        flushVisitRecord(useBeacon);
 
+        const topicId = topicController.model?.id || null;
+        const postStreamModel = topicController.model?.postStream;
+        setupScrollTracking(topicId, postStreamModel);
         captureVisitData(currentUser?.id, topicId);
       });
     });
   },
 };
 
+function captureVisitData(userId, topicId) {
+  const data = {
+    userId: userId || null,
+    fullUrl: window.location.href,
+    topicId,
+  };
+
+  pageVisitData = data;
+  // Initialize pageEnter when user lands on the page
+  pageEnter = new Date();
+  hasLoggedVisit = false;
+}
+
 function scroll() {
   discourseDebounce(this, captureOnScreenPosts, 100);
 }
@@ -62,39 +92,114 @@ function captureOnScreenPosts() {
   });
 }
 
-async function createPageVisitRecord(data, postIds, time) {
-  await ajax("/page-visits.json", {
-    type: "POST",
-    data: {
-      user_id: data.userId,
-      full_url: data.fullUrl,
-      topic_id: data.topicId,
-      post_ids: postIds,
-      visit_time: time,
-    },
-  });
+function flushVisitRecord(useBeacon, skipTimeCheck = false) {
+  // Don't flush if we've already logged this visit or if there's no data
+  if (hasLoggedVisit || Object.keys(pageVisitData).length === 0) {
+    return;
+  }
+
+  // Don't flush if we just started tracking (pageEnter was just set)
+  // This prevents logging visits immediately when onPageChange fires multiple times
+  // Skip this check for visibility/pagehide events (skipTimeCheck = true)
+  if (!skipTimeCheck && pageEnter) {
+    const timeSincePageEnter = Date.now() - pageEnter.getTime();
+    // If less than 100ms has passed, we're likely in a duplicate onPageChange call
+    // Don't log yet - wait for the user to actually navigate away
+    if (timeSincePageEnter < 100) {
+      return;
+    }
+  }
+
+  // Calculate visit time before resetting
+  if (!pageEnter) {
+    // Fallback: if pageEnter wasn't set, use current time minus a small buffer
+    pageEnter = new Date(Date.now() - 1000);
+  }
+  const pageExitTime = new Date();
+  const visitTimeMs = pageExitTime - pageEnter;
+
+  // Save current state before resetting (so we can capture new page data immediately)
+  const savedPageData = { ...pageVisitData };
+  const savedPostIds = [...viewedPostIds];
+
+  // Mark as logged BEFORE resetting to prevent duplicate logs
+  hasLoggedVisit = true;
+
+  // Reset state immediately so we can start tracking the new page
+  reset();
+
+  // Log the saved visit asynchronously
+  createPageVisitRecord(savedPageData, savedPostIds, visitTimeMs, useBeacon);
 }
 
-function captureVisitData(userId, topicId) {
-  const data = {
-    userId: userId || null,
-    fullUrl: window.location.href,
-    topicId,
+async function createPageVisitRecord(data, postIds, time, useBeacon = false) {
+  const payload = {
+    user_id: data.userId,
+    full_url: data.fullUrl,
+    topic_id: data.topicId,
+    post_ids: postIds,
+    visit_time: time,
   };
 
-  pageVisitData = data;
+  if (useBeacon && navigator.sendBeacon) {
+    // Use sendBeacon for reliable delivery during page unload
+    // FormData is the most reliable format for sendBeacon
+    const formData = createFormDataFromPayload(payload, session?.csrfToken);
+    const url = new URL("/page-visits.json", window.location.origin);
+    navigator.sendBeacon(url.toString(), formData);
+  } else {
+    // Use ajax for normal page navigation (more reliable, can handle errors)
+    try {
+      await ajax("/page-visits.json", {
+        type: "POST",
+        data: payload,
+      });
+    } catch {
+      // If ajax fails and we're unloading, fallback to sendBeacon
+      if (navigator.sendBeacon) {
+        const formData = createFormDataFromPayload(payload, session?.csrfToken);
+        const url = new URL("/page-visits.json", window.location.origin);
+        navigator.sendBeacon(url.toString(), formData);
+      }
+    }
+  }
+}
+
+function createFormDataFromPayload(payload, csrfToken) {
+  const formData = new FormData();
+
+  if (csrfToken) {
+    formData.append("authenticity_token", csrfToken);
+  }
+
+  if (payload.user_id !== null && payload.user_id !== undefined) {
+    formData.append("user_id", payload.user_id);
+  }
+  if (payload.full_url) {
+    formData.append("full_url", payload.full_url);
+  }
+  if (payload.topic_id !== null && payload.topic_id !== undefined) {
+    formData.append("topic_id", payload.topic_id);
+  }
+  if (Array.isArray(payload.post_ids) && payload.post_ids.length > 0) {
+    payload.post_ids.forEach((postId) => {
+      formData.append("post_ids[]", postId);
+    });
+  }
+  if (payload.visit_time !== null && payload.visit_time !== undefined) {
+    formData.append("visit_time", payload.visit_time);
+  }
+  return formData;
 }
 
 function reset() {
-  window.removeEventListener("scroll", scroll);
+  if (scrollListenerAttached) {
+    window.removeEventListener("scroll", scroll);
+    scrollListenerAttached = false;
+  }
   viewedPostIds = [];
-  pageEnter = new Date();
-  pageExit = null;
-  visitTime = null;
+  pageEnter = null;
   pageVisitData = {};
-}
-
-function setVisitTime() {
-  pageExit = new Date();
-  visitTime = pageExit - pageEnter;
+  hasLoggedVisit = false;
+  postStream = null;
 }