Add Osano integration (#1248)

* Add Osano integration

* Fix Osano infinite reload loop by deduping consent decisions

onConsentSaved replays the visitor's existing decision on every page
load, and GitBook's onApprove/onReject can trigger a reload, so every
replay caused another reload in an infinite loop. Only forward the
decision when it actually changes, tracked via sessionStorage so it
survives the reload.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: addisonschultz

.changeset/osano-consent-integration.md

@@ -0,0 +1,5 @@
+---
+'@gitbook/integration-osano': minor
+---
+
+Add Osano cookie consent integration.

bun.lock

@@ -0,0 +1,47 @@
+name: osano
+title: Osano Cookie Consent
+description: Add the Osano cookie consent banner to your published GitBook site.
+visibility: public
+organization: gitbook
+icon: ./assets/icon.png
+previewImages:
+    - ./assets/osano-preview.png
+script: ./src/index.ts
+# The following scope(s) are available only to GitBook Staff
+# See https://developer.gitbook.com/integrations/configurations#scopes
+scopes:
+    - site:script:inject
+    - site:script:cookies
+contentSecurityPolicy:
+    script-src: |
+        https://cmp.osano.com;
+summary: |
+    # Overview
+    This integration allows you to add the Osano cookie consent banner on your published GitBook site.
+
+    # How it works
+    The integration injects the Osano CMP script `osano.js` on your page, using your Customer ID and
+    Configuration ID, so that the cookie consent banner is displayed and consent is managed according
+    to your Osano configuration.
+
+    # Configure
+    Install the integration on the GitBook site of your choice.
+    Provide your Osano Customer ID and Configuration ID. These required values are provided by Osano
+    and correspond to the two IDs in your `osano.js` script URL: `https://cmp.osano.com/<Customer ID>/<Configuration ID>/osano.js`.
+categories:
+    - analytics
+configurations:
+    site:
+        properties:
+            customer_id:
+                type: string
+                title: Customer ID
+                description: The Osano Customer ID, the first ID segment in your osano.js script URL
+            config_id:
+                type: string
+                title: Configuration ID
+                description: The Osano Configuration ID, the second ID segment in your osano.js script URL
+        required:
+            - customer_id
+            - config_id
+target: site

integrations/osano/assets/icon.png

@@ -0,0 +1,10 @@
+declare module '*.raw.js' {
+    const content: string;
+    export default content;
+}
+
+export declare global {
+    interface Window {
+        GitBook: import('@gitbook/browser-types').GitBookGlobal;
+    }
+}

integrations/osano/assets/osano-preview.png

@@ -0,0 +1,20 @@
+{
+    "name": "@gitbook/integration-osano",
+    "version": "0.0.0",
+    "private": true,
+    "dependencies": {
+        "@gitbook/api": "*",
+        "@gitbook/runtime": "*"
+    },
+    "devDependencies": {
+        "@gitbook/cli": "workspace:*",
+        "@gitbook/tsconfig": "workspace:*",
+        "@gitbook/browser-types": "^0.1.5"
+    },
+    "scripts": {
+        "typecheck": "tsc --noEmit",
+        "publish-integrations-staging": "gitbook publish .",
+        "check": "gitbook check",
+        "publish-integrations": "gitbook publish ."
+    }
+}

integrations/osano/gitbook-manifest.yaml

@@ -0,0 +1,44 @@
+import {
+    createIntegration,
+    FetchPublishScriptEventCallback,
+    RuntimeContext,
+    RuntimeEnvironment,
+} from '@gitbook/runtime';
+
+import script from './script.raw.js';
+
+type OsanoRuntimeContext = RuntimeContext<
+    RuntimeEnvironment<
+        {},
+        {
+            customer_id?: string;
+            config_id?: string;
+        }
+    >
+>;
+
+export const handleFetchEvent: FetchPublishScriptEventCallback = async (
+    event,
+    { environment }: OsanoRuntimeContext,
+) => {
+    const customerId = environment.siteInstallation?.configuration?.customer_id;
+    const configId = environment.siteInstallation?.configuration?.config_id;
+
+    if (!customerId || !configId) {
+        return;
+    }
+
+    return new Response(
+        (script as string).replace('<CUSTOMER_ID>', customerId).replace('<CONFIG_ID>', configId),
+        {
+            headers: {
+                'Content-Type': 'application/javascript',
+                'Cache-Control': 'max-age=604800',
+            },
+        },
+    );
+};
+
+export default createIntegration<OsanoRuntimeContext>({
+    fetch_published_script: handleFetchEvent,
+});

integrations/osano/global.d.ts

@@ -0,0 +1,77 @@
+(function () {
+    var w = window;
+    var d = document;
+
+    var NON_ESSENTIAL_CATEGORIES = ['ANALYTICS', 'MARKETING', 'PERSONALIZATION', 'STORAGE'];
+
+    // Registers the window.Osano('eventName', callback) pre-load queue so listeners
+    // added before osano.js has loaded are replayed once the real API is ready.
+    // See https://developers.osano.com/cmp/javascript-api/developer-documentation-consent-javascript-api#pre-load
+    function setupOsanoPreload() {
+        if (typeof w.Osano === 'function') return;
+        w.Osano = function () {
+            w.Osano.data.push(arguments);
+        };
+        w.Osano.data = [];
+    }
+
+    function injectOsano() {
+        var stub = d.getElementById('osano-sdk-stub');
+        if (stub) return;
+
+        var s = d.createElement('script');
+        s.id = 'osano-sdk-stub';
+        s.type = 'text/javascript';
+        s.async = true;
+        s.src = 'https://cmp.osano.com/<CUSTOMER_ID>/<CONFIG_ID>/osano.js';
+        d.head.appendChild(s);
+    }
+
+    function l() {
+        if (!w.GitBook || typeof w.GitBook.registerCookieBanner !== 'function') return;
+
+        w.GitBook.registerCookieBanner(function ({ onApprove, onReject }) {
+            setupOsanoPreload();
+
+            var CONSENT_STORAGE_KEY = 'osano-gitbook-last-consent-decision';
+
+            function emitConsent(consent) {
+                try {
+                    var hasNonEssential =
+                        !!consent &&
+                        NON_ESSENTIAL_CATEGORIES.some(function (category) {
+                            return consent[category] === 'ACCEPT';
+                        });
+                    var decision = hasNonEssential ? 'approve' : 'reject';
+
+                    // onConsentSaved replays the visitor's existing decision on every
+                    // page load, not just when it changes. GitBook's onApprove/onReject
+                    // can trigger a reload to reinitialize scripts, so forwarding every
+                    // replay would reload -> replay -> reload forever. Only forward the
+                    // decision when it's actually different from last time, and persist
+                    // that in sessionStorage since it must survive the reload.
+                    if (w.sessionStorage.getItem(CONSENT_STORAGE_KEY) === decision) return;
+                    w.sessionStorage.setItem(CONSENT_STORAGE_KEY, decision);
+
+                    if (hasNonEssential) {
+                        onApprove();
+                    } else {
+                        onReject();
+                    }
+                } catch (e) {
+                    onReject();
+                }
+            }
+
+            w.Osano('onConsentSaved', emitConsent);
+
+            injectOsano();
+        });
+    }
+
+    if (w.attachEvent) {
+        w.attachEvent('onload', l);
+    } else {
+        w.addEventListener('load', l, false);
+    }
+})();

integrations/osano/package.json

@@ -0,0 +1,3 @@
+{
+    "extends": "@gitbook/tsconfig/integration.json"
+}