SDK JavaScript

Le SDK JavaScript officiel de CrowdHandler https://www.crowdhandler.com pour la gestion des salles d'attente et des files d'attente. Fonctionne aussi bien dans un environnement Node.js que dans un navigateur.

Intégration facile: ajoutez la gestion des files d'attente à n'importe quelle application JavaScript à l'aide d'un simple appel de fonction
Déploiement flexible — Fonctionne sur les serveurs Node.js, dans les navigateurs, sur Lambda@Edge, Cloudflare Workers et d'autres environnements d'exécution en périphérie
Options de performance: choisissez entre la validation via API en temps réel et la validation locale de la signature, en fonction de vos besoins
Continuité de la file d'attente: conserve la position de l'utilisateur lors des actualisations de page et d'une session à l'autre
Prise en charge de TypeScript - Définitions de types complètes pour une meilleure expérience de développement
Accès à l'API - Gérer les salles d'attente, surveiller les files d'attente et accéder aux analyses par programmation

Installation

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>

des modules

Le SDK est disponible sous plusieurs formats :

Modules ES - import { init } from 'crowdhandler-sdk'
CommonJS - const crowdhandler = require('crowdhandler-sdk')
UMD - Disponible sous la forme de window.crowdhandler lorsqu'il est chargé via une balise script
Importation dynamique - await import('crowdhandler-sdk')

Guide de démarrage rapide

Node.js / Côté

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();

Navigateur /

// 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

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;
  }
};

principales

gatekeeper.validateRequest(params?)

Méthode principale permettant de valider les requêtes au sein du système de file d'attente de CrowdHandler. Cette méthode détermine si un utilisateur doit se voir accorder l'accès à votre ressource protégée ou être redirigé vers une salle d'attente.

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

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

Paramètres :

paramètres (facultatif) - Objet contenant des paramètres personnalisés
- personnalisé - Objet contenant les paires clé-valeur à envoyer à l'API CrowdHandler

Comment ça marche :

Vérification du jeton: vérifie d'abord s'il existe un jeton de session CrowdHandler dans les cookies
Validation de l'API: envoie le jeton (ou en génère un nouveau) à l'API de CrowdHandler, en incluant les éventuels paramètres personnalisés
Position dans la file d'attente: détermine si l'utilisateur est priorisé en fonction de la capacité actuelle
Réponse: fournit des instructions sur la manière de traiter la demande

Objet de retour :

{
  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
}

Comportement spécifique au mode :

Mode complet (par défaut) : effectue un appel API à chaque requête pour une validation en temps réel
Mode hybride: valide les signatures localement pour les utilisateurs disposant d'un accès privilégié, ce qui réduit le nombre d'appels API
Mode côté client: la validation s'effectue entièrement dans le navigateur à l'aide de cookies

Gestion des erreurs :

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(value, domain?)

Sets the CrowdHandler session cookie. Always call this when `result.setCookie` is true to maintain the user's queue position. The optional `domain` parameter (provided in `result.domain`) enables proper cookie scoping for wildcard domains.

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

gatekeeper.redirectToCleanUrl(url)

Supprime les paramètres de suivi CrowdHandler des URL. À utiliser lorsque result.stripParams C'est une bonne idée de veiller à ce que les URL restent claires.

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

gatekeeper.redirectIfNotPromoted()

Méthode pratique qui gère l'intégralité du processus de redirection pour les utilisateurs non promus. Gère automatiquement les cookies et les redirections.

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

gatekeeper.redirectIfPromoted()

Cette méthode redirige les utilisateurs promus depuis une implémentation de « salle d'attente » vers le site cible avec de nouveaux paramètres CrowdHandler. Elle est spécifiquement destinée à être utilisée dans le cadre d'implémentations de « salle d'attente ».

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

Cas d'utilisation : lorsque vous créez une salle d'attente personnalisée fonctionnant sur votre infrastructure, cette méthode gère la redirection vers la ressource protégée en utilisant les paramètres CrowdHandler appropriés.

gatekeeper.recordPerformance(options?)

Enregistre les indicateurs de performance afin d'aider CrowdHandler à optimiser le flux et la capacité des files d'attente.

// 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)

Remplace la salle d'attente par défaut de CrowdHandler par votre URL personnalisée.

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

d'initialisation

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
    }]
  }
});

de validation#

Mode complet (par défaut)

Idéal pour la plupart des intégrations côté serveur.

✅ Avantages: configuration simple, aucune clé privée requise, fonctionnalités complètes
❌ Inconvénients: appel d'API à chaque requête (latence de 20 à 100 ms)

hybride#

Pour les applications où les performances sont essentielles.

✅ Avantages: latence minimale (2 à 10 ms), moins d'appels d'API
❌ Inconvénients: nécessite une clé privée, requiert l'utilisation de JavaScript côté client pour certaines fonctionnalités supplémentaires

const instance = crowdhandler.init({
  publicKey: 'YOUR_PUBLIC_KEY',
  privateKey: 'YOUR_PRIVATE_KEY',  // Required for hybrid mode
  options: { mode: 'hybrid' }
});

côté client#

Pour les applications monopages et les sites statiques.

✅ Avantages: fonctionne sans serveur, intégration facile
❌ Inconvénients: fonctionne uniquement côté client, nécessite JavaScript

du cookie personnalisé#

Par défaut, CrowdHandler utilise gestionnaire de foule comme nom du cookie. Vous pouvez le remplacer par un nom personnalisé :

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

Cela s'avère utile dans les cas suivants :

Exécution de plusieurs instances de CrowdHandler sur le même domaine
Éviter les conflits avec les cookies existants
Respecter les conventions de nommage spécifiques

des cookies#

Par défaut, le cookie CrowdHandler est un cookie de session — le navigateur le supprime lorsque l'utilisateur quitte complètement le navigateur (remarque : de nombreux navigateurs restaurent les cookies de session si l'option « Reprendre là où vous vous êtes arrêté » est activée). Pour les cas d'utilisation de salles d'attente où vous souhaitez que la position d'un utilisateur en file d'attente soit conservée après un redémarrage du navigateur, activez la persistance avec cookieMaxAgeSeconds:

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

Remarques :

La valeur est enregistrée dans le cookie sous la forme de Max-Age attribut (à privilégier par rapport à Date d'expiration car il n'est pas affecté par le décalage de l'horloge du client).
Cette option s'applique à chaque requête « Set-Cookie » émise par le SDK, tant pendant que l'utilisateur est en file d'attente qu'après la promotion.
Omettez cette option (ou laissez-la non défini) afin de conserver le comportement d'origine du cookie de session.

Forcer l'environnement de Cloudflare Workers#

Le SDK déduit un environnement d'exécution Cloudflare Workers à partir de navigator.userAgent. Si ce signal n'est pas fiable dans votre environnement (versions personnalisées de Workerd, outils de bundling qui suppriment les variables globales, environnements de test), vous pouvez rendre cette décision explicite :

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

Seulement vrai est acceptée — omettez cette option pour revenir à la détection automatique. Avec debug : true, le SDK enregistre quel signal a motivé la décision, par exemple : [CH] Environnement d'exécution Cloudflare Workers : true (via une redéfinition) contre (via l'inférence du navigateur). La dérogation est réinitialisée à chaque init() appel afin qu'il n'y ait jamais de fuite lors des réinitialisations.

API#

Le SDK fournit un client unifié pour les API publiques et privées :

// 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');

disponibles#

API publique (clé publique uniquement) :

client.requests() - Validation de la demande
client.responses() - Suivi des réponses
client.rooms() - Informations sur la salle d'attente

API privée (nécessite une clé privée) :

client.compte() - Informations sur le compte
client.accountPlan() - Détails du forfait
client.codes() - Gestion des codes d'accès
client.domains() - Configuration du domaine
client.domainIPs() - Adresses IP des domaines
client.domainReports() - Analyse de domaine
client.domainRequests() - Journaux des requêtes de domaine
client.domainRooms() - Espaces pour un domaine
client.domainURLs() - URL protégées
client.groups() - Groupes de codes d'accès
client.groupBatch() - Opérations liées aux codes de lot
client.groupCodes() - Codes d'un groupe
client.ips() - Gestion des adresses IP
client.reports() - Rapports d'analyse
client.rooms() - Gestion de la salle d'attente
client.roomReports() - Analyse des chambres
client.roomSessions() - Séances en présentiel
client.sessions() - Gestion des sessions
client.templates() - Modèles pour salles d'attente

Toutes les méthodes prennent en charge les opérations REST standard, le cas échéant :

.get() - Afficher la liste complète ou récupérer une ressource spécifique par ID
.post(data) - Créer une nouvelle ressource
.put(id, data) - Mettre à jour une ressource existante
.patch(id, données) - Mise à jour partielle
.supprimer(id) - Supprimer une ressource

La documentation complète de l'API, accompagnée d'exemples de requêtes et de réponses, est disponible dans votre tableau de bord CrowdHandler, sous Compte → API.

des erreurs#

Toutes les erreurs du SDK sont des instances de CrowdHandlerError avec une structure cohérente :

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
}

des erreurs API#

Le SDK conserve les messages d'erreur exacts de l'API CrowdHandler, ce qui vous permet de gérer des cas d'erreur spécifiques :

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;
}

d'erreur courants#

INVALID_CONFIG - Configuration SDK non valide
CLÉ_PRIVÉE_MANQUANTE - Clé privée requise pour cette opération
API_CONNECTION_FAILED - Impossible d'accéder à l'API CrowdHandler
API_RÉPONSE_NON_VALIDE - L'API a renvoyé une erreur
RATE_LIMITED - Nombre de requêtes trop élevé (y compris les tentatives de réessai)

d'intégration#

Consultez le répertoire « examples » pour découvrir des exemples complets et fonctionnels, notamment :

Implémentations d'Express.js (protection complète, API uniquement, API privée)
Gestionnaires Lambda@Edge
Intégration de React
Modèles de gestion des erreurs
Utilisation de TypeScript

Express.

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();
  }
});

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

Le SDK intègre une prise en charge native du moteur d'exécution Cloudflare Workers (workerd) — aucun polyfill Node n'est nécessaire. Transmettez les Workers Demande objet via cloudflareWorkersRequest et le SDK utilise des fonctions natives récupérer en interne pour tous les appels d'API.

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 — quelles sont les différences :

Les workers ne disposent pas d'objet de réponse modifiable. Créez la requête sortante Réponse vous-même en utilisant les valeurs de résultat (cookieValue, URL cible, setCookie) plutôt que de recourir à des méthodes auxiliaires qui modifient la réponse directement.
Utilisation ctx.waitUntil() pour recordPerformance() afin que l'appel métrique ne retarde pas la réponse de l'utilisateur. Sur les Workers, le SDK attend en interne l'appel à l'API sous-jacente (il effectue donc en réalité un vidage en interne ctx.waitUntil); par défaut, la durée de la requête POST est limitée à 1 500 ms — passer { timeout: <ms> } pour régler.
Par défaut mode : « full » (utilisé ci-dessus) ne nécessite que la clé publique. Le mode hybride est pris en charge, mais nécessite de transmettre votre clé privée sous forme de secret de Worker — ne procédez ainsi qu’après avoir évalué les avantages et les inconvénients.

React / Next.

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>;
}

avancées#

Remplacer de la salle d'attente#

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

d'exclusion personnalisés#

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

de la demande de dérogation#

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

de la représentation

// 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)
});

d'erreurs de test#

Pour tester votre gestion des erreurs sans effectuer de véritables appels d'API, vous pouvez simuler des erreurs :

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)

Cela est utile pour :

Test de la logique de gestion des erreurs en phase de développement
Vérification du comportement de repli pour différents types d'erreurs
Tests d'intégration sans incidence sur les indicateurs de production

Remarque : les erreurs de test de type 4xx se produiront toujours en promotion : faux, tandis que les erreurs de test de type 5xx respectent votre trustOnFail paramètre.

« Lite Validator »#

Le mode « Lite Validator » permet d'actualiser les jetons sans passer par des appels API, en vérifiant localement la configuration de la salle. Pour l'activer :

Ensemble liteValidator : true dans les options
Récupérez et fournissez la configuration de vos salles à partir de l'API CrowdHandler

// 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);
}

Lorsque Lite Validator s'active :

L'URL correspond à une salle de votre configuration
Le jeton est manquant ou date de plus de 12 heures
Redirige vers CrowdHandler pour actualiser la session

Le SDK comprend des outils de test complets :

de test local#

# Démarrer le serveur de test avec vos clés
npm run test:server -- --publicKey=VOTRE_CLÉ --privateKey=VOTRE_CLÉ_PRIVÉE

# Avec des options personnalisées
npm run test:server -- --apiUrl=https://staging-api.crowdhandler.com --mode=hybrid

# Mode développement (reconstruction automatique du SDK)
npm run test:server:dev

de test du navigateur n°

Démarrer le serveur de test
http://localhost:3000/test/browser-test.html en ligne
Tests interactifs avec intégration réelle d'API

de test n

# Exécuter les tests automatisés sur le serveur de test
npm run test:client

Prise en de TypeScript#

Prise en charge complète de TypeScript, avec définitions de types incluses :

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
    }
  }
}

sur la version#

Le SDK est disponible sous plusieurs formats :

CommonJS (dist/crowdhandler.cjs.js) - Pour Node.js require()
Modules ES (dist/crowdhandler.esm.js) - Pour les modèles modernes import
UMD (dist/crowdhandler.umd.js) - Pour les navigateurs via <script>
UMD Minified (dist/crowdhandler.umd.min.js) - Version de navigateur de production

SDK JavaScript

Fonctionnalités#

Installation#

NPM#

N° CDN

Formats des modules#

Guide de démarrage rapide#

Node.js / Côté serveur#

Navigateur / Côté client#

Cloudflare Workers#

Méthodes principales#

gatekeeper.validateRequest(params?)#

gatekeeper.redirectToCleanUrl(url)#

gatekeeper.redirectIfNotPromoted()#

gatekeeper.redirectIfPromoted()#

gatekeeper.recordPerformance(options?)#

gatekeeper.overrideWaitingRoomUrl(url)#

Configuration#

Options d'initialisation#

Modes de validation#

Mode complet (par défaut)#

Mode hybride#

Mode côté client#

Nom du cookie personnalisé#

Durée de vie des cookies#

Forcer l'environnement d'exécution de Cloudflare Workers#

Client API#

Ressources disponibles#

Gestion des erreurs#

Transparence des erreurs API#

Codes d'erreur courants#

Exemples d'intégration#

Express.js#

Lambda@Edge#

Cloudflare Workers#

React / Next.js#

Fonctionnalités avancées#

Remplacer l'URL de la salle d'attente#

Modèles d'exclusion personnalisés#

Détails de la demande de dérogation#

Enregistrement de la représentation#

Simulation d'erreurs de test#

Mode « Lite Validator »#

Tests#

Serveur de test local#

Page de test du navigateur n°

Client de test n°

Prise en charge de TypeScript#

Informations sur la version#

Installation

CDN

des modules

Guide de démarrage rapide

Node.js / Côté

Navigateur /

Cloudflare

principales

gatekeeper.validateRequest(params?)

gatekeeper.redirectToCleanUrl(url)

gatekeeper.redirectIfNotPromoted()

gatekeeper.redirectIfPromoted()

gatekeeper.recordPerformance(options?)

gatekeeper.overrideWaitingRoomUrl(url)

d'initialisation

de validation#

Mode complet (par défaut)

hybride#

côté client#

du cookie personnalisé#

des cookies#

Forcer l'environnement de Cloudflare Workers#

API#

disponibles#

des erreurs#

des erreurs API#

d'erreur courants#

d'intégration#

Express.

Cloudflare

React / Next.

avancées#

Remplacer de la salle d'attente#

d'exclusion personnalisés#

de la demande de dérogation#

de la représentation

d'erreurs de test#

« Lite Validator »#

de test local#

de test du navigateur n°

de test n

Prise en de TypeScript#

sur la version#