Skip to main content

JavaScript SDK

The biskoui JavaScript SDK provides a simple, synchronous API for managing user consent and controlling third-party services on your website. Once installed via the quick start guide, the SDK automatically handles consent collection and service activation.

How It Works​

The biskoui SDK operates through two main mechanisms:

  1. Global API - Synchronous methods for programmatic control
  2. DOM Events - Automatic notifications when services become available

For automatic script execution based on consent, see the Script Blocking guide.

Global API​

The SDK exposes a global window.biskoui object with synchronous methods:

// Show the consent banner
biskoui.showBanner();

// Hide the consent banner
biskoui.hideBanner();

// Accept all non-necessary services
biskoui.acceptAll();

// Reject all non-necessary services
biskoui.rejectAll();

// Accept a specific service (additive to existing consent)
biskoui.acceptService("google_analytics");

// Check if a specific service has been accepted
const hasAnalytics = biskoui.hasAcceptedService("google_analytics");

All methods are available immediately after the SDK loads. Call them from click handlers or after DOMContentLoaded.

Service Activation Events​

The SDK fires events when services become available for use:

Per-Service Events​

Each service configured in your biskoui dashboard fires its own activation event:

// Listen for Google Maps activation
window.addEventListener("biskoui:google_maps_activated", function () {
  console.log("Google Maps is now allowed");
  initGoogleMaps();
});

// Listen for YouTube activation
window.addEventListener("biskoui:youtube_activated", function () {
  console.log("YouTube embeds are now allowed");
  loadYouTubeEmbeds();
});

Event names follow the pattern: biskoui:<service_key>_activated

Initialization Events​

The SDK emits ready events when it has finished loading and the public API is safe to use.

For Google Tag Manager, biskoui pushes a biskoui_ready event to window.dataLayer:

window.dataLayer.push({
  event: "biskoui_ready",
  acceptedServices: ["google_analytics", "google_maps"],
});

In GTM, you can use biskoui_ready as a Custom Event trigger. The acceptedServices field contains the service keys accepted at initialization time. When this event is emitted, window.biskoui is available and biskoui.hasAcceptedService(serviceKey) is synchronized with the loaded consent state; you do not need to add an arbitrary timeout before reading consent state.

The SDK also emits a browser event:

window.addEventListener("biskoui:ready", function (event) {
  console.log("Biskoui SDK is fully initialized");
  console.log("Accepted services:", event.detail.acceptedServices);

  // SDK methods are now available
  const hasAnalytics = biskoui.hasAcceptedService("google_analytics");
});

These events are useful if you need to ensure the SDK is loaded and the user's existing consent state is available before calling API methods or checking consent status.

Usage Examples​

Manual Banner Control​

<button onclick="biskoui.showBanner()">Review Cookie Settings</button>
<button onclick="biskoui.acceptAll()">Accept All Cookies</button>
<button onclick="biskoui.rejectAll()">Reject All</button>
<button onclick="biskoui.acceptService('google_analytics')">Accept Analytics</button>

Event-Driven Service Loading​

window.addEventListener("biskoui:google_maps_activated", function () {
  // Initialize Google Maps when consent is granted
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 46.8182, lng: 8.2275 },
    zoom: 8,
  });
});
window.addEventListener("biskoui:ready", function () {
  if (biskoui.hasAcceptedService("google_maps")) {
    // Google Maps already allowed - initialize immediately
    initGoogleMaps();
  }

  if (biskoui.hasAcceptedService("youtube")) {
    // YouTube already allowed - load embeds
    loadYouTubeEmbeds();
  }
});

In GTM, you can either read the acceptedServices field from the biskoui_ready event or call biskoui.hasAcceptedService("service_key") from a Custom JavaScript variable triggered by biskoui_ready.

Granular Service Acceptance​

// Accept individual services additively
function enableAnalytics() {
  biskoui.acceptService("google_analytics");
}

function enableVideoEmbeds() {
  biskoui.acceptService("youtube");
  biskoui.acceptService("vimeo");
}

// Accept service based on user interaction
function handleServiceToggle(serviceKey, isEnabled) {
  if (isEnabled) {
    biskoui.acceptService(serviceKey);
  }
  // Note: There's no rejectService method - use rejectAll() or showBanner() for changes
}

Service Keys and Naming​

Service keys use snake_case format (e.g., google_maps, youtube, vimeo). These keys must match exactly across:

  • Service configuration in your biskoui dashboard
  • Event names: biskoui:<service_key>_activated
  • Service queries: biskoui.hasAcceptedService('<service_key>')
  • Script blocking attributes (see Script Blocking)