Consent Adapter Development

Build a custom consent platform adapter to integrate your cookie consent tool (CookieYes, Cookiebot, OneTrust, etc.) with Advanced Analytics session tracking.

Overview

The consent system has three components:

1. PHP adapter class — implements the consent interface for server-side checks and admin registration.
2. JavaScript contract — provides a window.toolDocsConsent object for client-side consent checking.
3. Registration — hooks into a filter to make the adapter selectable in Analytics settings.

PHP Interface

Your adapter must implement ConsentAdapterInterface with these methods:

interface ConsentAdapterInterface {
    public function get_id(): string;              // Unique ID (e.g., 'cookieyes')
    public function get_name(): string;            // Display name for admin UI
    public function has_analytics_consent(): bool;  // Server-side analytics consent check
    public function has_functional_consent(): bool; // Server-side functional consent check
    public function get_frontend_check_script(): string; // JS code for client-side checking
    public function get_consent_categories(): array;     // e.g., ['analytics', 'functional']
    public function is_active(): bool;             // Is this consent platform detected?
}

JavaScript Contract

The JavaScript returned by get_frontend_check_script() must define window.toolDocsConsent with three methods:

• hasConsent() — returns true (granted), false (denied), or null (unknown / banner not shown yet).
• onConsentChange(callback) — registers a listener that fires when consent status changes. Callback receives a boolean.
• waitForConsent() — returns a Promise that resolves with a boolean once consent status is known.

How the Flow Works

1. Page loads and the consent adapter’s JavaScript is injected inline.
2. The session tracker calls hasConsent().
3. If true → session initializes immediately.
4. If false → session does not initialize; tracker listens for changes.
5. If null → tracker registers a listener via onConsentChange() and waits for the visitor to interact with the consent banner.
6. When consent is withdrawn, the frontend triggers anonymization/deletion on the server and clears the session cookie.

Registering Your Adapter

Use the tooldocs_analytics_consent_adapters filter:

add_filter('tooldocs_analytics_consent_adapters', function($adapters) {
    require_once '/nas/content/live/tooldocsio' . '/class-my-consent-adapter.php';
    $adapters['my_platform'] = new MyConsentAdapter();
    return $adapters;
});

After registration, your adapter appears in the Analytics → Settings → Consent Platform dropdown.

Complete Example

A minimal but complete adapter skeleton:

add_filter('tooldocs_analytics_consent_adapters', function($adapters) {
    $adapters['my_consent'] = new class implements ToolDocsAnalyticsConsentConsentAdapterInterface {

        public function get_id(): string { return 'my_consent'; }
        public function get_name(): string { return 'My Consent Tool'; }

        public function has_analytics_consent(): bool {
            $cookie = $_COOKIE['my_consent_prefs'] ?? '';
            return strpos($cookie, 'analytics:1') !== false;
        }

        public function has_functional_consent(): bool {
            return true;
        }

        public function get_frontend_check_script(): string {
            return <<<'JS'
window.toolDocsConsent = {
    hasConsent: function() {
        var match = document.cookie.match(/my_consent_prefs=([^;]+)/);
        if (!match) return null;
        return match[1].indexOf('analytics:1') !== -1;
    },
    onConsentChange: function(callback) {
        window.addEventListener('my_consent_updated', function() {
            callback(window.toolDocsConsent.hasConsent());
        });
    },
    waitForConsent: function() {
        var self = this;
        return new Promise(function(resolve) {
            var result = self.hasConsent();
            if (result !== null) { resolve(result); return; }
            var check = setInterval(function() {
                var r = self.hasConsent();
                if (r !== null) { clearInterval(check); resolve(r); }
            }, 200);
            setTimeout(function() { clearInterval(check); resolve(false); }, 10000);
        });
    }
};
JS;
        }

        public function get_consent_categories(): array {
            return ['analytics', 'functional'];
        }

        public function is_active(): bool { return true; }
    };
    return $adapters;
});

Tips

• Keep the JavaScript small — it’s injected inline on every page load.
• Handle the “unknown” state — return null from hasConsent() when the banner hasn’t been shown yet so the tracker waits rather than proceeding.
• Test consent withdrawal — verify that withdrawing consent properly triggers the anonymization or deletion flow.
• Use a separate plugin — package your adapter as its own WordPress plugin that depends on both the consent platform and Advanced Analytics.