docs: add analytics support [internal] (#767)

Author: katzino

.github/workflows/_release_docs.yaml

@@ -68,6 +68,7 @@ jobs:
         run: uv run poe build-docs
         env:
           APIFY_SIGNING_TOKEN: ${{ secrets.APIFY_SIGNING_TOKEN }}
+          SEGMENT_TOKEN: ${{ secrets.SEGMENT_TOKEN }}
 
       - name: Set up GitHub Pages
         uses: actions/configure-pages@v5

website/docusaurus.config.js

@@ -1,4 +1,4 @@
-const path = require('path');
+const { join, resolve } = require('node:path');
 
 const { config } = require('@apify/docs-theme');
 
@@ -125,8 +125,8 @@ module.exports = {
                 routeBasePath: 'reference',
                 python: true,
                 pythonOptions: {
-                    pythonModulePath: path.join(__dirname, '../src/apify'),
-                    moduleShortcutsPath: path.join(__dirname, '/module_shortcuts.json'),
+                    pythonModulePath: join(__dirname, '../src/apify'),
+                    moduleShortcutsPath: join(__dirname, '/module_shortcuts.json'),
                 },
                 reexports: [
                     // Storages
@@ -263,6 +263,13 @@ module.exports = {
                 ],
             },
         ],
+        [
+            resolve(__dirname, 'src/plugins/docusaurus-plugin-segment'),
+            {
+                writeKey: process.env.SEGMENT_TOKEN,
+                allowedInDev: false,
+            },
+        ],
         [
             '@signalwire/docusaurus-plugin-llms-txt',
             {

website/src/plugins/docusaurus-plugin-segment/index.js

@@ -0,0 +1,59 @@
+const path = require('node:path');
+
+module.exports = function (context, options) {
+    const { writeKey, allowedInDev = false } = options;
+
+    return {
+        name: 'docusaurus-plugin-segment',
+
+        getClientModules() {
+            return [path.resolve(__dirname, './segment')];
+        },
+
+        injectHtmlTags() {
+            if (process.env.NODE_ENV !== 'production' && !allowedInDev) {
+                return {};
+            }
+
+            if (!writeKey) {
+                console.warn('You need to specify a Segment writeKey in the plugin options');
+                return {};
+            }
+
+            return {
+                headTags: [
+                    {
+                        tagName: 'script',
+                        attributes: {
+                            src: 'https://cdn.cookielaw.org/scripttemplates/otSDKStub.js',
+                            type: 'text/javascript',
+                            charset: 'UTF-8',
+                            'data-domain-script': '7a8d334b-f744-4c02-9931-92861196dd3c',
+                        },
+                    },
+                    {
+                        tagName: 'script',
+                        attributes: {
+                            type: 'text/javascript',
+                        },
+                        innerHTML: 'function OptanonWrapper() {}',
+                    },
+                    {
+                        tagName: 'script',
+                        attributes: {
+                            src: 'https://cdn.jsdelivr.net/npm/@segment/analytics-consent-wrapper-onetrust@latest/dist/umd/analytics-onetrust.umd.js',
+                        },
+                    },
+                    {
+                        tagName: 'script',
+                        innerHTML: `
+                        !function(){var i="analytics",analytics=window[i]=window[i]||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","screen","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware","register"];analytics.factory=function(e){return function(){if(window[i].initialized)return window[i][e].apply(window[i],arguments);var n=Array.prototype.slice.call(arguments);if(["track","screen","alias","group","page","identify"].indexOf(e)>-1){var c=document.querySelector("link[rel='canonical']");n.push({__t:"bpc",c:c&&c.getAttribute("href")||void 0,p:location.pathname,u:location.href,s:location.search,t:document.title,r:document.referrer})}n.unshift(e);analytics.push(n);return analytics}};for(var n=0;n<analytics.methods.length;n++){var key=analytics.methods[n];analytics[key]=analytics.factory(key)}analytics.load=function(key,n){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.setAttribute("data-global-segment-analytics-key",i);t.src="https://cdn.segment.com/analytics.js/v1/" + key + "/analytics.min.js";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(t,r);analytics._loadOptions=n};analytics._writeKey="${writeKey}";;analytics.SNIPPET_VERSION="5.2.0";
+                        withOneTrust(analytics.load("${writeKey}", { integrations: { "Segment.io": { apiHost: "analytics.apify.com/v1" } } }));
+                        }}();
+                        `,
+                    },
+                ],
+            };
+        },
+    };
+};

website/src/plugins/docusaurus-plugin-segment/segment.js

@@ -0,0 +1,48 @@
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+const DEFAULT_CONSENT = {
+    C0001: false,
+    C0002: false,
+    C0003: false,
+    C0004: false,
+    C0005: false,
+};
+
+function getOneTrustConsentContext() {
+    const consent = { ...DEFAULT_CONSENT };
+    // obtain `OptanonConsent` cookie and extract `groups` substring
+    const match = document.cookie.match(/(^|;\s*)OptanonConsent=[^;]*&groups=([^;&]*)/);
+    // decode the value and parse it - expected format: [C0001:1, COOO2:0,...]
+    const input = decodeURIComponent(match?.[2] ?? '').split(',');
+
+    for (const chunk of input) {
+        const [name, value] = chunk.split(':');
+
+        // we only want to update specific groups
+        if (name in consent) {
+            // just to be extra sure, only "1" is considered to pass
+            consent[name] = value === '1';
+        }
+    }
+
+    return consent;
+}
+
+export default ExecutionEnvironment.canUseDOM ? {
+    onRouteUpdate() {
+        // this forces deferred execution that ensures `window.location` is in sync
+        setTimeout(() => {
+            // Don't track page views on development
+            if (process.env.NODE_ENV === 'production' && window.analytics) {
+                window.analytics.page({
+                    app: 'docs',
+                    page_type: 'DOCS_PAGE',
+                    path: window.location.pathname,
+                    url: window.location.href,
+                    search: window.location.search,
+                    ...getOneTrustConsentContext(),
+                });
+            }
+        }, 0);
+    },
+} : null;