Skip to main content
HumanKey
English version →

Dokumentacja

Przewodniki integracji dla WordPress, JavaScript, REST API i webhooków.

Na tej stronie

Szybki Start

Większość wdrożeń zajmuje mniej niż 2 minuty. Wybierz metodę pasującą do Twojej platformy:

Szybka instalacja

→Wtyczka WordPress~2 min→Skrypt JS jedną linią~60 sekPOLECANE

Integracja deweloperska

→REST API~20 min→Reguły crawlerów AIPo instalacji

Potrzebujesz powiadomień w czasie rzeczywistym? Webhooki są dostępne po uruchomieniu śledzenia (plany Business i Enterprise).

Wtyczka WordPress

Oficjalna wtyczka HumanKey instaluje się bezpośrednio z katalogu wtyczek WordPress.

  1. 1Przejdź do panelu WordPress Admin → Wtyczki → Dodaj nową
  2. 2Wyszukaj „HumanKey" i kliknij Zainstaluj teraz
  3. 3Aktywuj wtyczkę
  4. 4Przejdź do Ustawienia → HumanKey
  5. 5Wklej swój Publiczny Klucz Witryny (dostępny w Panelu → Witryny)
  6. 6Zapisz — fragment śledzący jest teraz aktywny na wszystkich stronach

Co dodaje wtyczka

  • • Wstrzykuje fragment śledzący HumanKey do sekcji <head> Twojej witryny
  • • Dodaje panel AI Traffic w WP Admin
  • • Wyświetla statystyki ruchu bot/człowiek bez opuszczania WordPressa
  • • Pokazuje status odznaki HumanKey Verified

Instalacja JS jedną linią

Działa na każdej platformie obsługującej własny HTML: Shopify, Webflow, Squarespace, strony statyczne i aplikacje własne.

<!-- Dodaj do sekcji <head> -->

<script async src="https://api.humankey.io/api/detect.js?key=TWÓJ_KLUCZ_PUBLICZNY"></script>

Zamień TWÓJ_KLUCZ_PUBLICZNY na klucz publiczny Twojej witryny ze strony Panel → Witryny.

Przewodniki dla konkretnych platform

  • • Shopify: Ustawienia → Motywy → Edytuj kod → theme.liquid → wklej w <head>
  • • Webflow: Ustawienia projektu → Własny kod → Kod nagłówka
  • • Squarespace: Ustawienia → Zaawansowane → Wstrzykiwanie kodu → Nagłówek
  • • Własny HTML: Wklej przed zamykającym tagiem </head>

Next.js (App Router)

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://api.humankey.io/api/detect.js?key=TWÓJ_KLUCZ"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

React SPA (Create React App / Vite)

// App.tsx lub index.tsx
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.humankey.io/api/detect.js?key=TWÓJ_KLUCZ';
    script.async = true;
    document.head.appendChild(script);
    return () => { document.head.removeChild(script); };
  }, []);

  return <div>{/* Twoja aplikacja */}</div>;
}

Google Tag Manager (tag HTML)

<script>
  (function() {
    var s = document.createElement('script');
    s.src = 'https://api.humankey.io/api/detect.js?key=TWÓJ_KLUCZ';
    s.async = true;
    document.head.appendChild(s);
  })();
</script>
<!-- Wyzwalacz: Wszystkie strony -->

Nuxt 3

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://api.humankey.io/api/detect.js?key=TWÓJ_KLUCZ',
          async: true,
        },
      ],
    },
  },
});

REST API (po stronie serwera)

Użyj REST API z serwera, aby wykrywać boty i crawlery AI przed serwowaniem treści. Idealne dla middleware Next.js, Laravel, Django lub dowolnego frameworka serwerowego.

Detekcja botów — POST /api/detect

// Żądanie

POST https://api.humankey.io/api/detect
Content-Type: application/json

{
  "siteKey": "pk_...",
  "url": "https://twojawitryna.pl/artykul",
  "referrer": "https://google.com"
}

// Odpowiedź

{
  "isHuman": false,
  "action": "block"
}
// Szczegółowa analityka botów (nazwa, firma, pewność)
// dostępna w Panelu → Analityka.

Pole action wskazuje co zrobić: block → zwróć 429, monitor → zaloguj i kontynuuj, allow → crawler jawnie dozwolony.

Przykład middleware Next.js

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export async function middleware(req: NextRequest) {
  const res = await fetch('https://api.humankey.io/api/detect', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      siteKey: process.env.HK_PUBLIC_KEY,
      url: req.url,
      referrer: req.headers.get('referer') ?? undefined,
    }),
  });

  const { action } = await res.json();

  if (action === 'block') {
    return new NextResponse('Too Many Requests', { status: 429 });
  }

  return NextResponse.next();
}

Reguły crawlerów AI (Blokuj / Monitoruj / Zezwól)

Konfiguruj reguły dla poszczególnych crawlerów w Panelu → Witryny → Reguły crawlerów AI.

Blokuj

Crawler otrzymuje "action": "block". Twój kod serwerowy powinien zwrócić 429 Too Many Requests.

GPTBotCCBotanthropic-ai

Monitoruj

Domyślne ustawienie dla wszystkich wykrytych crawlerów. Rejestrowane w panelu, ruch przepuszczany.

PerplexityBotApplebot

Zezwól

Jawnie dozwolone crawlery. Przydatne dla crawlerów, którym chcesz zezwolić na indeksowanie treści.

Googlebotbingbot

HumanKey generuje również własny fragment robots.txt na podstawie Twoich reguł. Zainstaluj go przez wtyczkę WordPress jednym kliknięciem lub skopiuj i wklej ręcznie.

Webhooki

Otrzymuj powiadomienia w czasie rzeczywistym o wykrytych botach. Dostępne w planach Business i Enterprise.

Obsługiwane zdarzenia

  • bot.detected
  • quota.warning
  • quota.exceeded
  • plan.upgraded

Przykładowy payload

POST https://twoj-endpoint.pl/webhook
X-HumanKey-Signature: sha256=...

{
  "event": "bot.detected",
  "data": {
    "domain": "twojawitryna.pl",
    "url": "/artykul/trendy-ai-2026",
    "action": "block"
  }
}
// Pełna dokumentacja webhooków w Panelu → Integracje.

Podpisy używają HMAC-SHA256. Weryfikuj za pomocą swojego sekretu podpisywania webhooka z Panelu → Integracje.

Powiadomienia Email

HumanKey wysyła powiadomienia email o ruchu botów na Twoich stronach. Skonfiguruj każdy typ niezależnie w Panel → Ustawienia → Powiadomienia email.

Typy powiadomień

  • Dzienny raport botów — Podsumowanie aktywności botów z poprzedniego dnia (wszystkie plany)
  • Tygodniowe analizy AI — Generowane przez AI analizy trendów ruchu i rekomendacje (Business+)
  • Alerty nowych crawlerów — Alert, gdy nowy crawler AI zostanie po raz pierwszy wykryty (Pro+)
  • Ostrzeżenia o limicie — Alert, gdy miesięczny limit weryfikacji osiągnie 80%

Wszystkie powiadomienia są domyślnie włączone. Tygodniowe analizy AI wykorzystują wyłącznie zagregowane metryki — żadne dane osobowe nie są przetwarzane przez AI. Analizy mają charakter doradczy (zgodne z EU AI Act).

Metodologia Detekcji i Ocena Pewności

HumanKey wykorzystuje autorską 6-warstwową metodologię detekcji dla wysokiej dokładności klasyfikacji każdej wizyty.

Metodologia detekcji

  • Warstwa 1 — Identyfikacja znanych crawlerów AI (60+ botów sklasyfikowanych)
  • Warstwa 2 — Analiza metadanych żądań
  • Warstwa 3 — Klasyfikacja pochodzenia sieciowego
  • Warstwa 4 — Analiza interakcji odwiedzających
  • Warstwa 5 — Weryfikacja środowiska klienta
  • Warstwa 6 — Autorski silnik oceny pewności łączący wszystkie warstwy

Cała detekcja odbywa się po stronie serwera w UE. Żadne dane osobowe nie są używane do klasyfikacji. Wyniki są dostępne w Panelu i przez REST API.

Ocena pewności jest dostępna we wszystkich planach. Szczegółowe dane analityczne są dostępne od planu Pro.

Wykrywanie Farm Botów

HumanKey wykrywa skoordynowane sieci botów za pomocą autorskiego, wieloetapowego procesu analizy. System identyfikuje wzorce skoordynowanej aktywności ze wspólnej infrastruktury.

Jak to działa

  • Zbieranie — Dane poziomu sesji są zbierane i przetwarzane
  • Analiza — Autorski algorytm identyfikuje wzorce skoordynowanej aktywności
  • Scoring — Każda grupa otrzymuje wynik zagrożenia
  • Wzbogacanie — Metadane operatora sieciowego dodają kontekst infrastrukturalny

Endpointy API

  • GET /api/behavior/clusters?siteId=X — Lista wykrytych grup z członkami i wynikami zagrożenia
  • GET /api/behavior/clusters/:id?siteId=X — Szczegóły grupy z analizą członków

Wykrywanie farm botów ma charakter wyłącznie informacyjny — bez automatycznego blokowania. Całe przetwarzanie odbywa się na infrastrukturze UE.

Odznaka do osadzenia

Wyświetl odznakę „HumanKey Verified" na swojej stronie, aby pokazać odwiedzającym, że monitorujesz ruch AI.

<img
  src="https://api.humankey.io/api/badge?siteKey=TWÓJ_KLUCZ_PUBLICZNY"
  alt="HumanKey AI Verified"
  width="180"
  height="20"
/>

Odznaka to obraz SVG serwowany z 1-godzinnym cache. JavaScript nie jest wymagany.

Asystent AI

HumanKey zawiera wbudowanego Asystenta AI dostępnego na każdej stronie — zarówno na stronie publicznej, jak i w panelu. Kliknij ikonę czatu w prawym dolnym rogu, aby rozpocząć rozmowę.

O co możesz zapytać:

  • •Funkcje produktu, plany cenowe i porównania planów
  • •Zgodność z RODO, retencja danych i polityka prywatności
  • •Przewodniki integracji (wtyczka WordPress, snippet JS, REST API)
  • •Funkcje panelu, interpretacja raportów, konfiguracja webhooków
  • •Rozliczenia, zmiany planu i zarządzanie fakturami

Ograniczenia:

  • •20 wiadomości na rozmowę (potem rozpocznij nową)
  • •Rozmowy są efemeryczne — nie są zapisywane ani odzyskiwalne
  • •Nie podejmuje wiążących decyzji ani nie ma dostępu do danych konta
  • •W przypadku złożonych kwestii użyj linku "Porozmawiaj z człowiekiem" → /contact

Zgodność z Art. 50 AI Act: Asystent jest wyraźnie oznaczony jako napędzany przez AI. Dostarcza wyłącznie informacje doradcze i nie podejmuje automatycznych decyzji. Bezpośredni link do wsparcia ludzkiego jest zawsze dostępny.

Rozwiązywanie problemów

Zainstalowałeś snippet, ale nie widzisz danych? Oto najczęstsze przyczyny i rozwiązania.

1. Content-Security-Policy (CSP) blokuje snippet

Objaw: Konsola przeglądarki wyświetla "Refused to load the script" lub żądanie snippetu ma status 0 w zakładce Network.

Rozwiązanie: Dodaj api.humankey.io do obu dyrektyw: script-src i connect-src:

Content-Security-Policy:
  script-src 'self' https://api.humankey.io;
  connect-src 'self' https://api.humankey.io;

Jak sprawdzić: Otwórz DevTools (F12) → Konsola → szukaj komunikatów "Content Security Policy" lub "Refused to load".

2. Blokery reklam (uBlock Origin, Brave Shields, Privacy Badger)

Objaw: detect.js jest blokowany u części odwiedzających — brak weryfikacji dla tych użytkowników.

Blokery reklam mogą blokować skrypty analityczne firm trzecich. Dotyczy to tylko odwiedzających z blokerami (ok. 15–30% ruchu). Crawlery AI i boty — główny cel wykrywania HumanKey — nie używają blokerów reklam, więc dane o wykrywaniu botów pozostają w pełni dokładne. To oczekiwane zachowanie, nie błąd.

3. Cloudflare "Block AI Bots" / "Bot Fight Mode" Najczęstsza przyczyna braku danych AI

Objaw: HumanKey pokazuje zero ruchu AI botów, mimo że crawlery AI powinny odwiedzać Twoją stronę.

Przyczyna: Funkcje Cloudflare "Block AI bots" i "Bot Fight Mode" blokują crawlery AI na krawędzi sieci, zanim dotrą do Twojej strony. Ponieważ boty nigdy nie ładują Twoich stron, snippet HumanKey ich nie widzi. To nie jest błąd HumanKey — ruch faktycznie nigdy nie dociera.

Rozwiązanie: W Cloudflare Dashboard → Security → Settings wyłącz:

  • Block AI bots — ustaw na "Do not block (off)"
  • Bot Fight Mode — wyłącz przełącznik
  • AI Labyrinth — wyłącz (może generować mylące dane o ruchu)

Czy to bezpieczne? Tak. HumanKey monitoruje i raportuje ruch AI bez blokowania, dając dane do podejmowania świadomych decyzji o tym, które boty dopuścić lub ograniczyć. Wyłączenie blokowania botów w Cloudflare nie wpływa na ochronę DDoS ani inne funkcje bezpieczeństwa.

4. Cloudflare Rocket Loader

Objaw: Skrypt nigdy się nie wykonuje. Rocket Loader Cloudflare modyfikuje skrypty async.

Rozwiązanie: Dodaj data-cfasync="false" aby wyłączyć Rocket Loader dla snippetu HumanKey:

<script data-cfasync="false" src="https://api.humankey.io/api/detect.js?key=TWÓJ_KLUCZ" async></script>

5. Cache / CDN serwuje nieaktualny HTML

Objaw: Snippet dodany, ale panel wciąż pokazuje "Nie wykryto" po wdrożeniu.

Rozwiązanie: Wyczyść cache CDN — Cloudflare: Ustawienia → Cache → Wyczyść wszystko. Vercel: Ponowne wdrożenie (auto-czyszczenie). Netlify: Wdrożenia → Wyzwól wdrożenie → Wyczyść cache.

6. Błędy CORS

Objaw: Konsola wyświetla błąd "Access-Control-Allow-Origin" na endpointach challenge lub detect.

Rozwiązanie: Sprawdź, czy domena zarejestrowana w panelu HumanKey (Panel → Witryny) dokładnie odpowiada adresowi URL Twojej strony, łącznie z www vs bez www.

6. SPA / Aplikacje jednostronicowe

Objaw: Snippet ładuje się raz, ale nie odpala ponownie przy zmianie podstron.

To prawidłowe działanie. Snippet HumanKey uruchamia się raz przy załadowaniu strony i wykrywa crawlery AI podczas pierwszego żądania. Crawlery AI zazwyczaj nie wykonują JavaScript ani nie nawigują po trasach SPA, więc są wykrywane przy pierwszym załadowaniu. Nie jest potrzebna dodatkowa konfiguracja dla React, Vue ani Angular.

7. Widzę dane innego konta na współdzielonej przeglądarce

Objaw: Po przełączeniu kont na tym samym komputerze panel przez chwilę pokazuje poprzednią witrynę, filtr czasu lub rozmowę z czatbotem poprzedniego użytkownika.

Rozwiązanie: Wyloguj się z menu awatara → Wyloguj. HumanKey wykonuje pełne czyszczenie stanu klienta i twarde przeładowanie strony przy wylogowaniu — pozostały stan użytkownika jest usuwany i możesz zalogować się ponownie z czystej sesji. Jeśli problem się utrzymuje, zamknij i otwórz kartę ponownie. Każda sesja jest w pełni odizolowana (art. 32 RODO).

8. Ostrzeżenia "Content Security Policy blocks eval" w konsoli przeglądarki

Objaw: Podczas odwiedzania strony z zainstalowanym HumanKey w konsoli przeglądarki pojawiają się ostrzeżenia o naruszeniu CSP zawierające słowo eval.

Rozwiązanie: Te ostrzeżenia są niemal zawsze wstrzykiwane przez rozszerzenia przeglądarki (zwłaszcza portfele kryptowalut i menedżery haseł), które uruchamiają własne skrypty na każdej odwiedzanej stronie. HumanKey wymusza ścisłą politykę bezpieczeństwa treści (Content Security Policy) jako element swojej utwardzonej postawy bezpieczeństwa — nasz własny kod nigdy nie używa eval. Aby potwierdzić, że źródłem jest rozszerzenie, otwórz stronę w trybie incognito (rozszerzenia są tam domyślnie wyłączone). Jeśli ostrzeżenia zniknęły — źródłem jest rozszerzenie przeglądarki, a nie HumanKey.

9. Nagranie sesji pokazuje liczbę zdarzeń, ale obszar odtwarzania jest pusty

Objaw: Po otwarciu nagrania w Panel → Nagrania sesji w bocznym panelu widać czas trwania, liczbę zdarzeń i rozmiar pliku, lecz główny obszar odtwarzania pozostaje pusty.

Rozwiązanie: Zwykle oznacza to, że nagranie zostało przechwycone starszą wersją snippetu, która nie zapisywała pełnych danych odtwarzania, lub że sesja była jeszcze w trakcie rejestrowania w chwili jej otwarcia. Odczekaj kilka minut, odśwież listę nagrań, a następnie otwórz nowszą sesję od bardziej aktualnego odwiedzającego. Liczba zdarzeń i czas trwania są przechowywane niezależnie od strumienia odtwarzania, więc starsze nagrania mogą zasadnie pokazywać metadane bez klatek możliwych do odtworzenia. Jeśli świeże nagranie nadal ma pusty obszar odtwarzania, skontaktuj się z pomocą techniczną przez /contact, podając znacznik czasu nagrania.

10. Ostrzeżenia "CORB blocked" dla endpointów HumanKey

Objaw: Panel "Problemy" w Chrome DevTools lub konsola przeglądarki pokazuje komunikaty "CORB blocked" odwołujące się do endpointów API HumanKey.

Rozwiązanie: Żadne dane nie są zagrożone — są to informacyjne ostrzeżenia przeglądarki wynikające z mechanizmu ochrony między-źródłowej, a nie rzeczywiste blokady Twoich zarejestrowanych danych. Wszystkie endpointy HumanKey poprawnie odbierają i przetwarzają zdarzenia. Nasza obsługa odpowiedzi została utwardzona tak, aby wyeliminować te ostrzeżenia w najnowszej wersji snippetu. Jeśli nadal je widzisz, wykonaj twarde odświeżenie przeglądarki (Ctrl+F5 lub Cmd+Shift+R), aby pobrać aktualny kod trackera.

Nie możesz znaleźć tego, czego szukasz?

Nasz zespół wsparcia odpowiada w ciągu 2 dni roboczych.

Skontaktuj się z pomocą techniczną