JavaScript-SDK

JavaScript-SDK

Das offizielle JavaScript-SDK für das Wartezimmer- und Warteschlangenmanagement von CrowdHandler. Funktioniert sowohl in Node.js- als auch in Browser-Umgebungen.

Funktionen

  • Einfache Integration – Erweitern Sie jede JavaScript-Anwendung mit einem einzigen Funktionsaufruf um Funktionen zur Warteschlangenverwaltung
  • Flexible Bereitstellung – Läuft auf Node.js-Servern, in Browsern, auf Lambda@Edge, in Cloudflare Workers und anderen Edge-Laufzeitumgebungen
  • Leistungsoptionen – Wählen Sie je nach Bedarf zwischen einer Echtzeit-API-Validierung und einer lokalen Signaturprüfung
  • Warteschlangenkontinuität – Behält die Position des Benutzers auch bei Seitenaktualisierungen und über Sitzungen hinweg bei
  • TypeScript-Unterstützung – Vollständige Typdefinitionen für ein besseres Entwicklungserlebnis
  • API-Zugriff – Warteräume verwalten, Warteschlangen überwachen und programmgesteuert auf Analysedaten zugreifen

Installation

NPM

npm install crowdhandler-sdk

CDN

<!-- Load from unpkg -->
<script src="https://unpkg.com/crowdhandler-sdk/dist/crowdhandler.umd.min.js"></script>

<!-- Or specify a version -->
<script src="https://unpkg.com/crowdhandler-sdk@2.4.0/dist/crowdhandler.umd.min.js"></script>

Modulformate

Das SDK ist in verschiedenen Formaten verfügbar:

  • ES-Module - import { init } aus 'crowdhandler-sdk'
  • CommonJS - const crowdhandler = require('crowdhandler-sdk')
  • UMD - Erhältlich als window.crowdhandler beim Laden über ein Script-Tag
  • Dynamischer Import - await import('crowdhandler-sdk')

Schnellstart

Node.js / Serverseitig

const crowdhandler = require('crowdhandler-sdk');
// or ES modules: import { init } from 'crowdhandler-sdk';

// Initialize SDK
const { client, gatekeeper } = crowdhandler.init({
  publicKey: 'YOUR_PUBLIC_KEY',
  // Optional: add privateKey for private API access
  privateKey: 'YOUR_PRIVATE_KEY',
  request: req,  // Express request object
  response: res  // Express response object
});

// Validate the request
const result = await gatekeeper.validateRequest();

// Check for errors first
if (result.error) {
  console.error(`Validation error: ${result.error.message}`);
  // 4xx errors: promoted = false (always block access)
  // 5xx errors: promoted depends on trustOnFail setting
}

// Handle the validation result
if (result.setCookie) {
  gatekeeper.setCookie(result.cookieValue, result.domain);
}

if (result.stripParams) {
  return gatekeeper.redirectToCleanUrl(result.targetURL);
}

if (!result.promoted) {
  return gatekeeper.redirectIfNotPromoted();
}

// User is promoted - continue with your application
// ... your protected content here ...

// Record performance (optional but recommended)
await gatekeeper.recordPerformance();

Browser / clientseitig

// Using script tag
const { client, gatekeeper } = window.crowdhandler.init({
  publicKey: 'YOUR_PUBLIC_KEY',
  options: {
    mode: 'clientside'
  }
});

// Or using ES Modules
import { init } from 'crowdhandler-sdk';
const { client, gatekeeper } = init({
  publicKey: 'YOUR_PUBLIC_KEY',
  options: {
    mode: 'clientside'
  }
});

// Validate the request
const result = await gatekeeper.validateRequest();

// Handle the validation result
if (result.setCookie) {
  gatekeeper.setCookie(result.cookieValue, result.domain);
}

if (result.stripParams) {
  // Redirect to clean URL
  window.location.href = result.targetURL;
  return;
}

if (!result.promoted) {
  // Redirect to waiting room
  gatekeeper.redirectIfNotPromoted();
  return;
}

// User is promoted - your application continues
console.log('User granted access');

// Record performance (optional but recommended)
await gatekeeper.recordPerformance();

Cloudflare Workers

import { init } from 'crowdhandler-sdk';

export default {
  async fetch(request, env, ctx) {
    const { gatekeeper } = init({
      publicKey: env.CROWDHANDLER_PUBLIC_KEY,
      cloudflareWorkersRequest: request
    });

    const result = await gatekeeper.validateRequest();

    // Workers have no mutable response object — build the outgoing
    // Response yourself using values from the result.
    if (!result.promoted) {
      return new Response(null, {
        status: 302,
        headers: { Location: result.targetURL }
      });
    }

    const originResponse = await fetch(request);
    const response = new Response(originResponse.body, originResponse);

    if (result.setCookie) {
      response.headers.append(
        'set-cookie',
        `crowdhandler=${result.cookieValue}; path=/; Secure`
      );
    }

    ctx.waitUntil(gatekeeper.recordPerformance());
    return response;
  }
};

Kernmethoden

gatekeeper.validateRequest(params?)

Die primäre Methode zur Validierung von Anfragen anhand des Warteschlangensystems von CrowdHandler. Diese Methode legt fest, ob einem Benutzer Zugriff auf Ihre geschützte Ressource gewährt oder er in einen Warteraum weitergeleitet werden soll.

// Basic usage
const result = await gatekeeper.validateRequest();

// With custom parameters
const result = await gatekeeper.validateRequest({
  custom: {
    code: 'ABC123',
    captcha: 'xK9mN2pQ5vL8wR3tY6uZ1aS4dF7gH0j'
  }
});

Parameter:

  • params (optional) – Objekt, das benutzerdefinierte Parameter enthält
    • benutzerdefiniert - Objekt mit beliebigen Schlüssel-Wert-Paaren, die an die CrowdHandler-API gesendet werden sollen

So funktioniert es:

  1. Token-Prüfung: Zunächst wird geprüft, ob in den Cookies ein Token für eine bestehende CrowdHandler-Sitzung vorhanden ist
  2. API-Validierung: Sendet das Token (oder generiert ein neues) an die API von CrowdHandler, einschließlich etwaiger benutzerdefinierter Parameter
  3. Warteschlangenposition: Legt fest, ob der Benutzer basierend auf der aktuellen Kapazität vorgezogen wird
  4. Antwort: Enthält Anweisungen zur Bearbeitung der Anfrage

Rückgabeobjekt:

{
  promoted: boolean,      // true = grant access, false = send to waiting room
  setCookie: boolean,     // true = update the user's session cookie
  cookieValue: string,    // The session token to store in the cookie
  stripParams: boolean,   // true = remove CrowdHandler URL parameters
  targetURL: string,      // Where to redirect (clean URL or waiting room)
  slug: string,           // The waiting room slug (when not promoted)
  responseID: string,     // Response ID for performance tracking (when promoted)
  deployment: string,     // Deployment identifier from the API
  token: string,          // The session token
  hash: string | null,    // Signature hash for validation (when available)
  requested: string,      // Timestamp when the request was made
  liteValidatorRedirect: boolean,  // true = redirect to lite validator
  liteValidatorUrl: string         // URL for lite validator redirect
}

Modusspezifisches Verhalten:

  • Vollmodus (Standard): Führt bei jeder Anfrage einen API-Aufruf zur Echtzeit-Validierung durch
  • Hybridmodus: Überprüft Signaturen für berechtigte Benutzer lokal und reduziert so die Anzahl der API-Aufrufe
  • Clientseitiger Modus: Die Validierung erfolgt vollständig im Browser mithilfe von Cookies

Fehlerbehandlung:

try {
  const result = await gatekeeper.validateRequest();
  // ... handle result ...
} catch (error) {
  console.error('Validation failed:', error.message);
  console.error('Status code:', error.statusCode);
  // Handle based on trustOnFail setting
}

gatekeeper.setCookie(Wert, Domäne?)

Setzt das CrowdHandler-Sitzungs-Cookie. Rufen Sie diese Funktion immer auf, wenn result.setCookie ist wahr, um die Position des Benutzers in der Warteschlange beizubehalten. Das optionale Domäne Parameter (angegeben in result.domain) ermöglicht die korrekte Festlegung des Gültigkeitsbereichs von Cookies für Domänen mit Platzhaltern.

if (result.setCookie) {
  gatekeeper.setCookie(result.cookieValue, result.domain);
}

gatekeeper.redirectToCleanUrl(url)

Entfernt CrowdHandler-Tracking-Parameter aus URLs. Verwenden Sie diese Funktion, wenn result.stripParams Das ist wichtig, um URLs übersichtlich zu halten.

if (result.stripParams) {
  return gatekeeper.redirectToCleanUrl(result.targetURL);
}

gatekeeper.redirectIfNotPromoted()

Eine praktische Methode, die den gesamten Weiterleitungsablauf für Nutzer ohne Premium-Zugang übernimmt. Verwaltet Cookies und Weiterleitungen automatisch.

if (!result.promoted) {
  return gatekeeper.redirectIfNotPromoted();
}

gatekeeper.redirectIfPromoted()

Leitet beförderte Benutzer aus einer Wartesaal-Implementierung mit neuen CrowdHandler-Parametern zurück zur Zielseite. Diese Methode ist speziell für den Einsatz in Wartesaal-Implementierungen vorgesehen.

// In waiting room implementation
if (result.promoted) {
  return gatekeeper.redirectIfPromoted();
}

Anwendungsfall: Beim Aufbau eines benutzerdefinierten Warteraums, der auf Ihrer Infrastruktur läuft, sorgt diese Methode für die Weiterleitung zurück zur geschützten Ressource mit den richtigen CrowdHandler-Parametern.

gatekeeper.recordPerformance(optionen?)

Erfasst Leistungskennzahlen, um CrowdHandler dabei zu unterstützen, den Warteschlangenfluss und die Kapazität zu optimieren.

// Simple usage (recommended)
await gatekeeper.recordPerformance();

// With custom options
await gatekeeper.recordPerformance({
  sample: 1,             // Record 100% of requests (default 0.2)
  statusCode: 200,       // HTTP status code (default 200)
  overrideElapsed: 1234, // Custom timing in ms
  timeout: 1500          // Per-call API timeout in ms (default 1500)
});

gatekeeper.overrideWaitingRoomUrl(url)

Ersetzt den standardmäßigen CrowdHandler-Warteraum durch Ihre benutzerdefinierte URL.

// Redirect to your custom queue page
gatekeeper.overrideWaitingRoomUrl('https://mysite.com/custom-queue');

Konfiguration

Initialisierungsoptionen

const instance = crowdhandler.init({
  // Required
  publicKey: 'YOUR_PUBLIC_KEY',
  
  // Optional
  privateKey: 'YOUR_PRIVATE_KEY',  // Required for private API methods
  
  // Request context (choose one based on your environment)
  request: req,                       // Express/Node.js request
  response: res,                      // Express/Node.js response
  lambdaEdgeEvent: event,             // Lambda@Edge event
  cloudflareWorkersRequest: request,  // Cloudflare Workers Request
  // (none)                           // Browser environment (auto-detected)
  
  // Options
  options: {
    mode: 'full',         // 'full' (default), 'hybrid', 'clientside'
    apiUrl: 'https://api.crowdhandler.com',  // Custom API endpoint
    debug: false,         // Enable debug logging
    timeout: 5000,        // API timeout in milliseconds
    trustOnFail: true,    // Allow access if API fails
    fallbackSlug: '',     // Fallback room slug when trustOnFail is false
    cookieName: 'crowdhandler',  // Custom cookie name (default: 'crowdhandler')
    cookieMaxAgeSeconds: 86400,  // Optional. Persist the cookie via Max-Age (seconds).
                                 // Omit for a session cookie (default).
    forceCloudflareWorkers: true,  // Optional. Bypass navigator-based runtime inference
                                   // and treat the runtime as Cloudflare Workers. Only `true`
                                   // is accepted; omit for auto-detection.
    waitingRoom: false,   // Set to true if SDK is running in a waiting room context
    liteValidator: false, // Enable lite validator mode (default: false)
    roomsConfig: [{       // Array of room configurations for lite validator
      domain: string,     // e.g. 'https://example.com'
      slug: string,       // Room identifier
      urlPattern?: string,  // URL pattern to match
      patternType?: 'regex' | 'contains' | 'all',
      queueActivatesOn?: number,  // Unix timestamp
      timeout?: number    // Timeout in seconds
    }]
  }
});

Validierungsmodi

Vollmodus (Standard)

Am besten geeignet für die meisten serverseitigen Integrationen.

  • ✅ Vorteile: Einfache Einrichtung, kein privater Schlüssel erforderlich, umfassender Funktionsumfang
  • ❌ Nachteile: API-Aufruf bei jeder Anfrage (20–100 ms Latenz)

Hybridmodus

Für leistungskritische Anwendungen.

  • ✅ Vorteile: Geringe Latenz (2–10 ms), weniger API-Aufrufe
  • ❌ Nachteile: Erfordert einen privaten Schlüssel, benötigt clientseitiges JavaScript für Zusatzfunktionen
const instance = crowdhandler.init({
  publicKey: 'YOUR_PUBLIC_KEY',
  privateKey: 'YOUR_PRIVATE_KEY',  // Required for hybrid mode
  options: { mode: 'hybrid' }
});

Clientseitiger Modus

Für Single-Page-Anwendungen und statische Websites.

  • ✅ Vorteile: Funktioniert ohne Server, einfache Integration
  • ❌ Nachteile: Nur clientseitig, erfordert JavaScript

Benutzerdefinierter Cookie-Name

Standardmäßig verwendet CrowdHandler Massenbetreuer als Cookie-Name. Sie können diesen durch einen benutzerdefinierten Namen überschreiben:

const { gatekeeper } = crowdhandler.init({
  publicKey: 'YOUR_PUBLIC_KEY',
  options: {
    cookieName: 'my-custom-queue'  // Use custom cookie name
  }
});

Dies ist nützlich, wenn:

  • Ausführen mehrerer CrowdHandler-Instanzen auf derselben Domain
  • Konflikte mit vorhandenen Cookies vermeiden
  • Einhaltung bestimmter Namenskonventionen

Cookie-Speicherdauer

Standardmäßig ist das CrowdHandler-Cookie ein Sitzungs-Cookie — Der Browser löscht es, wenn der Benutzer den Browser vollständig beendet (Hinweis: Viele Browser stellen Sitzungscookies wieder her, wenn die Option „Weitermachen, wo Sie aufgehört haben“ aktiviert ist). Für Anwendungsfälle in Warteräumen, bei denen die Position eines Benutzers in der Warteschlange auch nach einem Neustart des Browsers erhalten bleiben soll, aktivieren Sie die Persistenz mit cookieMaxAgeSeconds:

const { gatekeeper } = crowdhandler.init({
  publicKey: 'YOUR_PUBLIC_KEY',
  options: {
    cookieMaxAgeSeconds: 86400  // Persist for 24 hours via Max-Age
  }
});

Anmerkungen:

  • Der Wert wird als Cookie-Wert geschrieben Max-Age Attribut (bevorzugt gegenüber Läuft ab (da es nicht von Taktabweichungen auf der Client-Seite beeinflusst wird).
  • Diese Option gilt für jedes „Set-Cookie“, das das SDK sendet – sowohl während der Nutzer in der Warteschlange steht als auch nach der Weiterleitung.
  • Die Option weglassen (oder so belassen, wie sie ist) undefiniert), um das ursprüngliche Verhalten der Sitzungs-Cookies beizubehalten.

Die Cloudflare Workers-Laufzeitumgebung erzwingen

Das SDK leitet eine Cloudflare Workers-Laufzeitumgebung ab aus navigator.userAgent. Falls dieses Signal in Ihrer Umgebung unzuverlässig ist (benutzerdefinierte Worker-Builds, Bundler, die globale Variablen entfernen, Testumgebungen), können Sie die Entscheidung explizit festlegen:

const { gatekeeper } = crowdhandler.init({
  publicKey: env.CROWDHANDLER_PUBLIC_KEY,
  cloudflareWorkersRequest: request,
  options: {
    forceCloudflareWorkers: true
  }
});

Nur wahr akzeptiert wird – lassen Sie die Option weg, um auf die automatische Erkennung zurückzugreifen. Mit debug: true, das SDK protokolliert, welches Signal die Entscheidung ausgelöst hat, z. B. [CH] Cloudflare Workers-Laufzeitumgebung: true (über Überschreibung) vs (über die Browser-Erkennung). Die Überschreibung wird bei jedem init() Aufruf, damit es bei erneuten Initialisierungen niemals zu einem Speicherleck kommt.

API-Client

Das SDK bietet einen einheitlichen Client sowohl für öffentliche als auch für private APIs:

// List all waiting rooms
const rooms = await client.rooms().get();

// Get specific room
const room = await client.rooms().get('room_id');

// Create a new room (requires privateKey)
const newRoom = await client.rooms().post({
  name: 'Product Launch',
  domain: 'example.com'
});

// Update room settings
await client.rooms().put('room_id', {
  capacity: 1000
});

// Delete a room
await client.rooms().delete('room_id');

Verfügbare Ressourcen

Öffentliche API (nur öffentlicher Schlüssel):

  • client.requests() - Validierung der Anfrage
  • client.responses() - Nachverfolgung von Antworten
  • client.rooms() - Informationen zum Wartezimmer

Private API (erfordert einen privaten Schlüssel):

  • client.account() - Kontoinformationen
  • client.accountPlan() - Details zum Account-Plan
  • client.codes() - Verwaltung von Zugangscodes
  • client.domains() - Domain-Konfiguration
  • client.domainIPs() - IP-Adressen von Domains
  • client.domainReports() - Domain-Analyse
  • client.domainRequests() - Protokolle zu Domain-Anfragen
  • client.domainRooms() - Räume für eine Domain
  • client.domainURLs() - Geschützte URLs
  • client.groups() - Zugriffscodegruppen
  • client.groupBatch() - Vorgänge mit Chargencodes
  • client.groupCodes() - Codes in einer Gruppe
  • client.ips() - Verwaltung von IP-Adressen
  • client.reports() - Analyseberichte
  • client.rooms() - Verwaltung des Wartezimmers
  • client.roomReports() - Raumanalytik
  • client.roomSessions() - Aktive Raumsitzungen
  • client.sessions() - Sitzungsverwaltung
  • client.templates() - Vorlagen für Wartezimmer

Alle Methoden unterstützen, soweit zutreffend, Standard-REST-Operationen:

  • .get() - Alle auflisten oder eine bestimmte Ressource anhand ihrer ID abrufen
  • .post(data) - Neue Ressource erstellen
  • .put(id, data) - Vorhandene Ressource aktualisieren
  • .patch(id, data) - Teilweise Aktualisierung
  • .delete(id) - Ressource löschen

Die vollständige API-Dokumentation mit Beispielen für Anfragen und Antworten finden Sie in Ihrem CrowdHandler-Dashboard unter „Konto“ → „API“.

Fehlerbehandlung

Alle SDK-Fehler sind Instanzen von CrowdHandlerError mit einheitlicher Struktur:

try {
  const rooms = await client.rooms().get();
} catch (error) {
  console.error(error.message);    // The actual API error message
  console.error(error.statusCode); // HTTP status code (e.g., 401, 404)
  console.error(error.suggestion); // Helpful guidance for resolution
  console.error(error.code);       // Error code for programmatic handling
}

Transparenz bei API-Fehlern

Das SDK übernimmt die genauen Fehlermeldungen aus der CrowdHandler-API, sodass Sie bestimmte Fehlerszenarien behandeln können:

try {
  const result = await gatekeeper.validateRequest({
    custom: { code: 'user-code' }
  });
} catch (error) {
  // Check the specific error message from the API
  if (error.message.includes('Invalid priority code')) {
    // Handle invalid access code
  }
  
  // For advanced debugging, access the full API response
  const apiResponse = error.context?.apiResponse;
}

Häufige Fehlercodes

  • INVALID_CONFIG - Ungültige SDK-Konfiguration
  • MISSING_PRIVATE_KEY - Für diesen Vorgang ist ein privater Schlüssel erforderlich
  • API_CONNECTION_FAILED - Die CrowdHandler-API ist nicht erreichbar
  • API_INVALID_RESPONSE - Die API hat einen Fehler zurückgegeben
  • RATE_LIMITED - Zu viele Anfragen (einschließlich „Retry-After“)

Beispiele für die Integration

Im Verzeichnis „examples“ finden Sie vollständige, funktionierende Beispiele, darunter:

  • Express.js-Implementierungen (vollständiger Schutz, nur API, private API)
  • Lambda@Edge-Handler
  • React-Integration
  • Muster zur Fehlerbehandlung
  • Verwendung von TypeScript

Express.js

const express = require('express');
const crowdhandler = require('crowdhandler-sdk');

const app = express();

// Middleware to protect routes
async function protectRoute(req, res, next) {
  try {
    const { gatekeeper } = crowdhandler.init({
      publicKey: process.env.CROWDHANDLER_PUBLIC_KEY,
      request: req,
      response: res
    });

    const result = await gatekeeper.validateRequest();
    
    // Check if there was an error during validation
    if (result.error) {
      console.error(`API Error ${result.error.statusCode}: ${result.error.message}`);
      // 4xx errors (e.g., invalid key, bad request): promoted = false (user blocked)
      // 5xx errors (e.g., server error): promoted based on trustOnFail setting
    }
    
    if (result.setCookie) {
      gatekeeper.setCookie(result.cookieValue, result.domain);
    }
    
    if (result.stripParams) {
      return gatekeeper.redirectToCleanUrl(result.targetURL);
    }
    
    if (!result.promoted) {
      return gatekeeper.redirectIfNotPromoted();
    }
    
    // User is promoted, continue
    res.locals.gatekeeper = gatekeeper;
    next();
  } catch (error) {
    // This catches unexpected errors (e.g., network issues, config errors)
    console.error('CrowdHandler SDK error:', error.message);
    // trustOnFail: true (default) = allow access on error
    // trustOnFail: false = block access on error
    next();
  }
}

// Protect specific routes
app.get('/limited-product', protectRoute, (req, res) => {
  res.send('This is a limited product page!');
  
  // Record performance after response
  if (res.locals.gatekeeper) {
    res.locals.gatekeeper.recordPerformance();
  }
});

Lambda@Edge

const crowdhandler = require('crowdhandler-sdk');

exports.handler = async (event) => {
  const { gatekeeper } = crowdhandler.init({
    publicKey: process.env.CROWDHANDLER_PUBLIC_KEY,
    lambdaEdgeEvent: event
  });

  const result = await gatekeeper.validateRequest();
  
  if (!result.promoted) {
    // Redirect to waiting room
    return {
      status: '302',
      statusDescription: 'Found',
      headers: {
        location: [{
          key: 'Location',
          value: result.targetURL
        }]
      }
    };
  }
  
  // Continue with normal request processing
  return event.Records[0].cf.request;
};

Cloudflare Workers

Das SDK bietet native Unterstützung für die Cloudflare Workers (workerd)-Laufzeitumgebung – es sind keine Node-Polyfills erforderlich. Übergeben Sie die Workers Anfrage Objekt über cloudflareWorkersRequest und das SDK nutzt native holen intern für alle API-Aufrufe.

import { init } from 'crowdhandler-sdk';

export default {
  async fetch(request, env, ctx) {
    const { gatekeeper } = init({
      publicKey: env.CROWDHANDLER_PUBLIC_KEY,
      cloudflareWorkersRequest: request
    });

    const result = await gatekeeper.validateRequest();

    if (result.error) {
      console.error(`API Error ${result.error.statusCode}: ${result.error.message}`);
    }

    // Strip CrowdHandler params from a freshly promoted URL
    if (result.stripParams) {
      return new Response(null, {
        status: 302,
        headers: {
          Location: decodeURIComponent(result.targetURL),
          'Set-Cookie': `crowdhandler=${result.cookieValue}; path=/; Secure`
        }
      });
    }

    // Send unpromoted users to the waiting room
    if (!result.promoted) {
      return new Response(null, {
        status: 302,
        headers: { Location: result.targetURL }
      });
    }

    // Promoted: fetch the origin and attach the session cookie if needed
    const originResponse = await fetch(request);
    const response = new Response(originResponse.body, originResponse);

    if (result.setCookie) {
      response.headers.append(
        'set-cookie',
        `crowdhandler=${result.cookieValue}; path=/; Secure`
      );
    }

    // Performance recording continues after the response is returned
    ctx.waitUntil(gatekeeper.recordPerformance());
    return response;
  }
};

Workers vs. Express/Lambda – was ist der Unterschied:

  • Worker verfügen über kein veränderbliches Antwortobjekt. Erstellen Sie die ausgehende Antwort selbst unter Verwendung von Werten aus Ergebnis (cookieValue, targetURL, setCookie) anstatt sich auf Hilfsmethoden zu verlassen, die eine Antwort direkt ändern.
  • Verwendung ctx.waitUntil() für recordPerformance() damit der Metrik-Aufruf die Antwort des Benutzers nicht verzögert. Auf „Workers“ wartet das SDK intern auf den zugrunde liegenden API-Aufruf (d. h., es erfolgt tatsächlich ein Flush innerhalb von ctx.waitUntil); die Put-Anfrage ist standardmäßig auf 1500 ms begrenzt — weitergeben { timeout: <ms> } einstimmen.
  • Standard Modus: 'voll' (wie oben beschrieben) benötigt lediglich den öffentlichen Schlüssel. Der Hybridmodus wird unterstützt, erfordert jedoch die Übermittlung Ihres privaten Schlüssels als Worker-Geheimnis – tun Sie dies nur, wenn Sie die Vor- und Nachteile abgewogen haben.

React / Next.js

import { useEffect, useState } from 'react';
import { init } from 'crowdhandler-sdk';

function ProtectedComponent() {
  const [isPromoted, setIsPromoted] = useState(null);
  
  useEffect(() => {
    const checkAccess = async () => {
      const { gatekeeper } = init({
        publicKey: 'YOUR_PUBLIC_KEY',
        options: { mode: 'clientside' }
      });
      
      const result = await gatekeeper.validateRequest();
      
      if (!result.promoted) {
        window.location.href = result.targetURL;
      } else {
        setIsPromoted(true);
      }
    };
    
    checkAccess();
  }, []);
  
  if (isPromoted === null) return <div>Checking access...</div>;
  if (!isPromoted) return <div>Redirecting to waiting room...</div>;
  
  return <div>Protected content here!</div>;
}

Erweiterte Funktionen

URL des Warteraums überschreiben

gatekeeper.overrideWaitingRoomUrl('https://custom-wait.example.com');

Benutzerdefinierte Ignoriermuster

// Don't check these paths
gatekeeper.setIgnoreUrls(/\.(css|js|png|jpg)$/);

Details zur Übersteuerungsanforderung

gatekeeper.overrideHost('example.com');
gatekeeper.overridePath('/special-path');
gatekeeper.overrideIP('203.0.113.0');
gatekeeper.overrideLang('en-US');
gatekeeper.overrideUserAgent('Custom Bot 1.0');

Leistungsaufzeichnung

// Basic usage (records automatically)
await gatekeeper.recordPerformance();

// With options
await gatekeeper.recordPerformance({
  sample: 1.0,           // Record 100% of requests (default 0.2)
  statusCode: 200,       // HTTP status code
  overrideElapsed: 1234, // Custom timing in ms
  timeout: 1500          // Per-call API timeout in ms (default 1500, overrides global SDK timeout)
});

Simulation von Testfehlern

Um Ihre Fehlerbehandlung zu testen, ohne echte API-Aufrufe durchzuführen, können Sie Fehler simulieren:

const { gatekeeper } = init({
  publicKey: 'YOUR_PUBLIC_KEY',
  request: req,
  response: res,
  options: {
    testError: {
      statusCode: 500,  // Simulate a 500 error
      message: 'Simulated server error for testing'
    }
  }
});

// This will return immediately with a simulated error
const result = await gatekeeper.validateRequest();
// result.error will contain the test error
// result.promoted will be true (with default trustOnFail: true)

Dies ist nützlich für:

  • Testen der Fehlerbehandlungslogik in der Entwicklung
  • Überprüfung des Fallback-Verhaltens für verschiedene Fehlertypen
  • Integrationstests ohne Auswirkungen auf die Produktionskennzahlen

Hinweis: Bei 4xx-Testfehlern wird immer hervorgehoben: false, während 5xx-Testfehler Ihre trustOnFail Einstellung.

Lite-Validierungsmodus

Der Lite-Validator-Modus ermöglicht die Aktualisierung von Tokens ohne API-Aufrufe, indem die Raumkonfiguration lokal überprüft wird. So aktivieren Sie ihn:

  1. Set liteValidator: true in den Optionen
  2. Rufen Sie die Konfiguration Ihrer Räume über die CrowdHandler-API ab und stellen Sie sie bereit
// First, fetch your rooms configuration
const { client } = init({ publicKey: 'YOUR_PUBLIC_KEY' });
const roomsResponse = await client.rooms().get();

// Then initialize with lite validator enabled
const { gatekeeper } = init({
  publicKey: 'YOUR_PUBLIC_KEY',
  request: req,
  response: res,
  options: {
    liteValidator: true,              // Enable lite validator
    roomsConfig: roomsResponse.result // Pass the rooms array from API
  }
});

// Handle the lite validator redirect
const result = await gatekeeper.validateRequest();

if (result.liteValidatorRedirect) {
  // Redirect to refresh token/session
  return gatekeeper.redirect(result.liteValidatorUrl);
}

Wenn der Lite-Validator aktiviert wird:

  • Die URL entspricht einem Raum in deiner Konfiguration
  • Das Token fehlt oder ist älter als 12 Stunden
  • Leitet zu CrowdHandler weiter, um die Sitzung zu aktualisieren

Testen

Das SDK enthält umfassende Testwerkzeuge:

Lokaler Testserver

# Testserver mit Ihren Schlüsseln starten
npm run test:server -- --publicKey=IHR_SCHLÜSSEL --privateKey=IHR_PRIVATSCHLÜSSEL

# Mit benutzerdefinierten Optionen
npm run test:server -- --apiUrl=https://staging-api.crowdhandler.com --mode=hybrid

# Entwicklungsmodus (automatischer SDK-Neuaufbau)
npm run test:server:dev

Browser-Testseite

  1. Den Testserver starten
  2. Öffnen Sie http://localhost:3000/test/browser-test.html
  3. Interaktives Testen mit echter API-Integration

Test-Client

# Automatisierte Tests auf dem Testserver ausführen
npm run test:client

TypeScript-Unterstützung

Vollständige TypeScript-Unterstützung einschließlich Typdefinitionen:

import { init, CrowdHandlerError, ErrorCodes } from 'crowdhandler-sdk';
import type { Mode, Room, Domain, ValidationResult } from 'crowdhandler-sdk';

// All types are properly inferred
const { client, gatekeeper } = init({
  publicKey: 'YOUR_KEY'
});

// TypeScript knows this returns Room[]
const rooms = await client.rooms().get();

// Error handling with types
try {
  await client.domains().get();
} catch (error) {
  if (error instanceof CrowdHandlerError) {
    if (error.code === ErrorCodes.MISSING_PRIVATE_KEY) {
      // Handle missing key
    }
  }
}

Informationen zum Build

Das SDK wird in verschiedenen Formaten bereitgestellt:

  • CommonJS (dist/crowdhandler.cjs.js) – Für Node.js require()
  • ES-Module (dist/crowdhandler.esm.js) – Für moderne Import
  • UMD (dist/crowdhandler.umd.js) – Für Browser über <script>
  • UMD Minified (dist/crowdhandler.umd.min.js) – Browser-Build aus der Produktion