Add callback support to sa_pageview

dist/latest/latest.dev.js

@@ -1,4 +1,4 @@
-/* Simple Analytics - Privacy-first analytics (docs.simpleanalytics.com/script; 2025-05-30; bf05; v12) */
+/* Simple Analytics - Privacy-first analytics (docs.simpleanalytics.com/script; 2025-05-30; 8325; v12) */
 /* eslint-env browser */
 
 (function (
@@ -662,21 +662,25 @@
       isPushState,
       deleteSourceInfo,
       sameSite,
-      metadata
+      metadata,
+      callback
     ) {
       if (isPushState) sendOnLeave("" + payload.page_id, trueVar);
       if (collectDataOnLeave) payload.page_id = uuid();
 
       var currentPage = definedHostname + getPath();
 
-      sendData({
-        id: payload.page_id,
-        type: pageviewText,
-        referrer: !deleteSourceInfo || sameSite ? referrer : null,
-        query: getQueryParams(deleteSourceInfo),
+      sendData(
+        {
+          id: payload.page_id,
+          type: pageviewText,
+          referrer: !deleteSourceInfo || sameSite ? referrer : null,
+          query: getQueryParams(deleteSourceInfo),
 
-        metadata: stringify(metadata),
-      });
+          metadata: stringify(metadata),
+        },
+        callback
+      );
 
       previousReferrer = referrer;
       referrer = currentPage;
@@ -686,7 +690,14 @@
 
     var sameSite, userNavigated;
 
-    var pageview = function (isPushState, pathOverwrite, metadata) {
+    var pageview = function (
+      isPushState,
+      pathOverwrite,
+      metadata,
+      callbackRaw
+    ) {
+      if (!callbackRaw && isFunction(metadata)) callbackRaw = metadata;
+      var callback = isFunction(callbackRaw) ? callbackRaw : function () {};
       // Obfuscate personal data in URL by dropping the search and hash
       var path = getPath(pathOverwrite);
 
@@ -765,7 +776,8 @@
           isPushState,
           isPushState || userNavigated || !collectMetricByString("r"), // r = referrers
           sameSite,
-          metadata
+          metadata,
+          callback
         );
       };
 
@@ -856,8 +868,8 @@
 
     if (autoCollect) pageview();
 
-    window.sa_pageview = function (path, metadata) {
-      pageview(0, path, metadata);
+    window.sa_pageview = function (path, metadata, callback) {
+      pageview(0, path, metadata, callback);
     };
 
 

src/default.js

@@ -750,23 +750,27 @@
       isPushState,
       deleteSourceInfo,
       sameSite,
-      metadata
+      metadata,
+      callback
     ) {
       if (isPushState) sendOnLeave("" + payload.page_id, trueVar);
       if (collectDataOnLeave) payload.page_id = uuid();
 
       var currentPage = definedHostname + getPath();
 
-      sendData({
-        id: payload.page_id,
-        type: pageviewText,
-        referrer: !deleteSourceInfo || sameSite ? referrer : null,
-        query: getQueryParams(deleteSourceInfo),
-
-        /** if metadata **/
-        metadata: stringify(metadata),
-        /** endif **/
-      });
+      sendData(
+        {
+          id: payload.page_id,
+          type: pageviewText,
+          referrer: !deleteSourceInfo || sameSite ? referrer : null,
+          query: getQueryParams(deleteSourceInfo),
+
+          /** if metadata **/
+          metadata: stringify(metadata),
+          /** endif **/
+        },
+        callback
+      );
 
       previousReferrer = referrer;
       referrer = currentPage;
@@ -776,7 +780,14 @@
 
     var sameSite, userNavigated;
 
-    var pageview = function (isPushState, pathOverwrite, metadata) {
+    var pageview = function (
+      isPushState,
+      pathOverwrite,
+      metadata,
+      callbackRaw
+    ) {
+      if (!callbackRaw && isFunction(metadata)) callbackRaw = metadata;
+      var callback = isFunction(callbackRaw) ? callbackRaw : function () {};
       // Obfuscate personal data in URL by dropping the search and hash
       var path = getPath(pathOverwrite);
 
@@ -869,7 +880,8 @@
           isPushState,
           isPushState || userNavigated || !collectMetricByString("r"), // r = referrers
           sameSite,
-          metadata
+          metadata,
+          callback
         );
       };
 
@@ -966,12 +978,12 @@
     if (autoCollect) pageview();
 
     /** if metadata **/
-    window.sa_pageview = function (path, metadata) {
-      pageview(0, path, metadata);
+    window.sa_pageview = function (path, metadata, callback) {
+      pageview(0, path, metadata, callback);
     };
     /** else **/
-    window.sa_pageview = function (path) {
-      pageview(0, path);
+    window.sa_pageview = function (path, callback) {
+      pageview(0, path, undefinedVar, callback);
     };
     /** endif **/
 

test/unit/pageview-callback.test.js

@@ -0,0 +1,34 @@
+const { expect } = require("chai");
+const { createDOM } = require("./helpers/dom");
+
+describe("pageview callback", function () {
+  it("executes callback after sending a pageview", function (done) {
+    const dom = createDOM({ settings: { autoCollect: false } });
+
+    const sent = dom.sent;
+    dom.window.Image = function () {
+      return {
+        onload: null,
+        onerror: null,
+        set src(value) {
+          sent.push({ type: "image", url: value });
+          if (this.onload) this.onload();
+        },
+      };
+    };
+
+    let called = false;
+    dom.window.sa_pageview("/callback", function () {
+      called = true;
+    });
+
+    setTimeout(() => {
+      const req = dom.sent.find(
+        (r) => r.type === "image" && /path=%2Fcallback/.test(r.url)
+      );
+      expect(req, "pageview request").to.exist;
+      expect(called, "callback called").to.be.true;
+      done();
+    }, 10);
+  });
+});