Add external link tracking to Fathom integration (#534)

* #450 add external link tracking to fathom integration

* changed comment description

* Remove extra quotes causing SyntaxError in Fathom script

* Make replacement more readable

* Removed space configuration

* Track full url instead of domain name only

* Improve external link tracking for dynamic content

* changeset

Author: KevinRohn

.changeset/witty-ligers-sparkle.md

@@ -0,0 +1,5 @@
+---
+'@gitbook/integration-fathom': minor
+---
+
+Add external link tracking to Fathom integration

integrations/fathom/gitbook-manifest.yaml

@@ -42,5 +42,9 @@ configurations:
                 type: string
                 title: Site ID
                 description: Look for this in your Fathom analytics account
+            track_external_links:
+                type: boolean
+                title: Track External Links
+                description: Enable tracking of clicks on external links
         required:
             - site_id

integrations/fathom/src/fathomScript.raw.js

@@ -1,9 +1,31 @@
-(function (doc, siteID) {
+(function (doc, siteId, trackExternalLinks) {
     const sibling = doc.getElementsByTagName('script')[0];
     const element = doc.createElement('script');
     element.defer = true;
-    element.setAttribute('data-site', siteID);
+    element.setAttribute('data-site', siteId);
     element.setAttribute('data-spa', 'auto');
     element.src = 'https://cdn.usefathom.com/script.js';
+
+    // Function to track external links
+    function trackExternalLink(event) {
+        var item = event.target.closest('a');
+        if (!item) return;
+
+        var linkUrl = new URL(item.getAttribute('href'), window.location.href);
+        var currentHostname = window.location.hostname;
+
+        if (linkUrl.hostname !== currentHostname) {
+            // We simply track the full url as an event.
+            window.fathom.trackEvent('External link clicked: ' + linkUrl.href);
+        }
+    }
+
+    element.onload = function () {
+        if (trackExternalLinks === true || trackExternalLinks === 'true') {
+            // Use event delegation to capture clicks on all current and later loaded links
+            doc.addEventListener('click', trackExternalLink);
+        }
+    };
+
     sibling.parentNode.insertBefore(element, sibling);
-})(document, '<TO_REPLACE>');
+})(document, '<TO_REPLACE_SITE_ID>', '<TO_REPLACE_TRACK_EXTERNAL_LINKS>');

integrations/fathom/src/index.ts

@@ -12,6 +12,7 @@ type FathomRuntimeContext = RuntimeContext<
         {},
         {
             site_id?: string;
+            track_external_links?: boolean;
         }
     >
 >;
@@ -26,7 +27,14 @@ export const handleFetchEvent: FetchPublishScriptEventCallback = async (
         return;
     }
 
-    return new Response(script.replace('<TO_REPLACE>', siteId), {
+    const trackExternalLinks =
+        environment.siteInstallation?.configuration?.track_external_links ?? false;
+
+    const updatedScript = script
+        .replace('<TO_REPLACE_SITE_ID>', siteId)
+        .replace('<TO_REPLACE_TRACK_EXTERNAL_LINKS>', trackExternalLinks.toString());
+
+    return new Response(updatedScript, {
         headers: {
             'Content-Type': 'application/javascript',
             'Cache-Control': 'max-age=604800',