Dokumentacja

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

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

Dedykowana wtyczka HumanKey dla WordPressa wkrótce trafi do oficjalnego katalogu WordPress.org. Do tego czasu możesz dodać HumanKey do dowolnej witryny WordPress w około minutę, korzystając z jednoliniowej instalacji JS poniżej — bez wtyczki.

1. 1Skopiuj swój Publiczny Klucz Witryny z Panelu → Witryny
2. 2Skopiuj fragment kodu HumanKey z sekcji „Instalacja JS jedną linią" poniżej
3. 3Wklej go w nagłówku witryny — przez ustawienia nagłówka Twojego motywu lub wtyczkę do nagłówków i stopek
4. 4Zapisz — fragment śledzący jest teraz aktywny na wszystkich stronach

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

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

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

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

<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.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://api.humankey.io/api/detect.js?key=TWÓJ_KLUCZ',
          async: true,
        },
      ],
    },
  },
});

API raportowe tylko do odczytu — zagregowane raporty Twojej strony w formacie JSON — będzie wkrótce dostępne w planach Business i wyższych.

Obecnie najszybszym sposobem dodania HumanKey do dowolnej platformy jest jednoliniowy snippet JavaScript pokazany powyżej — działa na każdej stronie dopuszczającej znacznik script i nie wymaga kodu po stronie serwera.

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

HumanKey generuje również własny fragment robots.txt na podstawie Twoich reguł, wraz z maszynowo odczytywalną deklaracją Content Signals, w której sam wybierasz, jak AI może korzystać z Twoich treści (domyślnie: wyszukiwarki i odpowiedzi AI — tak, trening AI — nie; to deklaracja Twoich warunków o charakterze doradczym, a nie techniczne egzekwowanie). Skopiuj i wklej go ręcznie w swojej witrynie.

Sprawdzenie strony dla crawlerów AI (Panel → AI Magnet → Przegląd) — pokazuje, co Twoja strona główna daje crawlerom AI w surowym HTML, tak jak dostają go crawlery, które nie uruchamiają JavaScriptu — dane strukturalne, metadane, treść — i co poprawić najpierw. Dwie osobne części, których nie sumujemy: co pokazuje Twoja strona główna (do 30 punktów, mierzone dla strony, której własność potwierdziłeś, i której robots.txt dopuszcza sprawdzenie) oraz Twoje ustawienia w HumanKey (do 70 punktów). Wynik jest w każdym planie; podział z linkami do poprawek od Pro.

Wagi: JSON-LD 12, link kanoniczny 3, meta opis 5, nagłówki 4, tekst alternatywny obrazów 3, długość treści 3/2 (powyżej 300 słów 3, powyżej 100 słów 2); ustawienia 25 / 25 / 20 (reguły dla głównych crawlerów AI 25, co najmniej jedna reguła 25, liczba reguł 20). Wagi to wybór HumanKey, nie reguła wyszukiwarki.

Ocena ma charakter doradczy i odzwierciedla to, co HumanKey może odczytać z Twojej strony — nie jest gwarancją pozycji ani widoczności. Jej poprawa nie obiecuje cytowań przez AI ani miejsca w wynikach wyszukiwania.

Co odczytuje każdy punkt, dlaczego ma znaczenie i skąd pochodzi. Automatyczne sprawdzenie Twoich publicznych stron według wymienionych kryteriów (stan na 2026-10-21); to wyłącznie sugestie — wyszukiwarki i systemy AI same decydują, co pokazują i wykorzystują.

• Strona ma tytuł

  Wyszukiwarki używają tytułu strony jako jednego ze źródeł tytułu pokazywanego w wynikach.

  Bez tytułu wyszukiwarka sama pisze nagłówek Twojego wyniku.

  Punkt spełniony, gdy znacznik title w sekcji head strony zawiera tekst.

  Według opublikowanej dokumentacjiŹródło: Google Search Central (2026-10-21)

• Strona ma opis meta

  Krótkie podsumowanie strony zapisane w jej kodzie. Wyszukiwarki czasem pokazują je pod tytułem w wynikach.

  Bez opisu tekst pod wynikiem pochodzi z dowolnego miejsca strony.

  Punkt spełniony, gdy znacznik meta description zawiera tekst; sam og:description pokazujemy, ale nie wystarcza.

  Według opublikowanej dokumentacjiŹródło: Google Search Central (2026-10-21)

• Strona nie ma znacznika noindex

  noindex prosi wyszukiwarki, by nie pokazywały tej strony w wynikach.

  noindex prosi wyszukiwarki, by pominęły tę stronę w wynikach.

  Czytamy znaczniki meta robots, googlebot i applebot oraz nagłówki X-Robots-Tag dla wszystkich crawlerów, Googlebota lub Applebota. noindex lub none w którymkolwiek z nich to punkt niespełniony.

  Według opublikowanej dokumentacjiŹródło: Google Search Central, Apple Support (2026-10-21)

• Strona nie ogranicza fragmentów

  nosnippet i max-snippet ograniczają, ile tekstu ze strony Google pokazuje w wynikach i ile wykorzystuje bezpośrednio w AI Overviews i AI Mode. Apple nie używa tekstu oznaczonego nosnippet jako kontekstu dla odpowiedzi AI w swoich produktach.

  Limity fragmentów ograniczają tekst strony, który Google i Apple pokazują albo podają odpowiedziom AI.

  Limit fragmentu ogranicza, ile tekstu strony Google pokazuje lub podaje swoim odpowiedziom AI.

  Apple nie tworzy z tej strony opisu ani odpowiedzi i nie używa jej tekstu w odpowiedziach AI.

  Te same znaczniki i nagłówki co przy noindex; nosnippet lub max-snippet:0 i więcej to punkt niespełniony, max-snippet:-1 — spełniony. Dla Applebota liczy się tylko nosnippet; wygrywa najsurowszy limit.

  Według opublikowanej dokumentacjiŹródło: Google Search Central, Apple Support (2026-10-21)

• … sekcji oznaczonych data-nosnippet

  Google nie używa tekstu oznaczonego data-nosnippet jako fragmentu w swoich wynikach.

  Google pomija oznaczony tekst we fragmentach w swoich wynikach.

  Liczymy części HTML oznaczone data-nosnippet (span, div lub section, jak obsługuje Google); to tylko informacja, bez oceny.

  Według opublikowanej dokumentacjiŹródło: Google Search Central (2026-10-21)

• Tekst czytelny bez skryptów: około …

  Niektóre crawlery czytają stronę bez uruchamiania skryptów. Tekst, który pojawia się dopiero po uruchomieniu skryptów, może do nich nie dotrzeć.

  Crawlery pomijające skrypty dostają prawie pustą stronę; tekst do nich nie dociera.

  Punkt niespełniony, gdy bez JavaScriptu da się odczytać mniej niż 50 słów (nasz własny próg); tekst w noscript się liczy.

  Ocena własna HumanKey

• Znaleziono nazwę strony: …

  Google ustala nazwę strony głównie z danych strukturalnych WebSite, a także z og:site_name, tytułu strony i innego tekstu strony głównej.

  Bez jasnej nazwy Google wybiera ją sam z Twojej strony albo z innych stron.

  Odczytujemy nazwę z danych strukturalnych WebSite, potem z og:site_name, potem z pierwszej części tytułu strony.

  Według opublikowanej dokumentacjiŹródło: Google Search Central (2026-10-21)

• Znaleziono dane strukturalne: …

  Dane strukturalne to blok czytelny dla maszyn (schema.org, zwykle JSON-LD), który nazywa, czego dotyczy strona.

  Dane strukturalne mówią, czym jest strona, w formie czytanej przez maszyny bez zgadywania.

  Punkt spełniony, gdy blok JSON-LD, który HumanKey potrafi odczytać, podaje typ schema.org; pomijany przy mikrodanych lub RDFa.

  Według opublikowanej dokumentacjiŹródło: Google Search Central (2026-10-21)

• Strona ma link kanoniczny

  Link kanoniczny wskazuje preferowany adres strony, której treść jest dostępna pod kilkoma adresami. Google traktuje go jako silny sygnał przy wyborze głównego adresu.

  Bez linku kanonicznego Google wybiera główny adres spośród duplikatów na podstawie innych sygnałów.

  Punkt spełniony, gdy HTML strony ma link canonical z wartością; nagłówków Link ani samego adresu nie sprawdzamy.

  Według opublikowanej dokumentacjiŹródło: Google Search Central (2026-10-21)

• Strona główna otwiera się pod … bez przekierowań

  Przekierowanie kieruje crawlery z jednego adresu na inny. Google traktuje przekierowania jako silny sygnał głównego adresu.

  Crawlery stosują do tej strony robots.txt z …, a nie plik z ….

  Reguły z robots.txt domeny … nie dotyczą strony pod adresem ….

  Pokazujemy, gdzie kończy się adres strony głównej po przekierowaniach; inna nazwa hosta, np. z www lub bez, to tylko informacja.

  Według opublikowanej dokumentacjiŹródło: Google Search Central, RFC 9309 (2026-10-21)

• Strona główna jest większa, niż HumanKey odczytuje

  Pozostałe punkty opierają się tylko na odczytanej części. Tekstu i danych strukturalnych dalej na stronie nie sprawdziliśmy.

  Pokazujemy tylko wtedy, gdy strona zostaje ucięta na granicy odczytu HumanKey; to tylko informacja, bez oceny.

  Dla informacji

• Znaleziono robots.txt pod …

  Bez tego pliku crawlery stosujące standard mogą czytać każdą podstronę.

  HumanKey nie mógł odczytać pliku (błąd, brak odpowiedzi, zbyt wiele przekierowań albo niedostępny adres). Crawlery, które też nie mogą go odczytać, mogą traktować całą stronę jako zamkniętą.

  Bez pliku crawlery stosujące standard traktują każdą podstronę jako otwartą.

  Gdy pliku nie da się odczytać, crawlery stosujące standard mogą uznać stronę za zamkniętą.

  Odpowiedź 2xx — znaleziony, 4xx (poza 429) — brak pliku, pozostałe — nie udało się odczytać.

  Według opublikowanej dokumentacjiŹródło: RFC 9309 (2026-10-21)

• Rozmiar robots.txt: …

  Google odczytuje pierwsze 500 KiB pliku, a resztę pomija.

  Reguły po pierwszych 500 KiB są pomijane, więc część Twoich reguł nie działa.

  Czytamy do 500 KiB i tylko pełne linie; większy plik to punkt niespełniony, bo Google pomija resztę.

  Według opublikowanej dokumentacjiŹródło: Google Search Central, RFC 9309 (2026-10-21)

• robots.txt ma linię Sitemap

  Linia Sitemap wskazuje wyszukiwarkom, gdzie jest lista Twoich podstron. To jeden z kilku sposobów jej przekazania; pakiet jej nie dodaje, bo adres zależy od Twojej platformy.

  Linia Sitemap wskazuje crawlerom listę podstron bez osobnego zgłaszania.

  Punkt spełniony, gdy plik ma linię Sitemap: z dowolną wartością; adresu nie otwieramy ani nie sprawdzamy.

  Według opublikowanej dokumentacjiŹródło: Google Search Central (2026-10-21)

• robots.txt pozwala wyszukiwarkom czytać stronę główną

  Twój robots.txt mówi crawlerom wyszukiwarek (np. Googlebotowi i Bingbotowi), czy mogą czytać stronę. Pakiet nigdy nie blokuje Googlebota ani Bingbota i nie odblokowuje żadnego crawlera; zmień te linie ręcznie.

  Zablokowany crawler wyszukiwarki nie czyta strony głównej, więc nie ma czego pokazać.

  Sprawdzamy, czy Googlebot i Bingbot mogą czytać stronę główną (/) według Twoich reguł; blokada któregokolwiek to punkt niespełniony.

  Według opublikowanej dokumentacjiŹródło: RFC 9309 (2026-10-21)

• Googlebot nie odczyta noindex: robots.txt blokuje mu stronę główną

  Google nie odczyta reguł ze strony zablokowanej w robots.txt, więc pomija noindex. Aby noindex działał, Googlebot musi móc czytać stronę.

  Twój noindex nie działa w Google, dopóki robots.txt blokuje Googlebota.

  Punkt niespełniony, gdy robots.txt blokuje Googlebotowi stronę główną (/), a znacznik lub nagłówek dla Google zawiera noindex.

  Według opublikowanej dokumentacjiŹródło: Google Search Central (2026-10-21)

• Zadeklarowano Content-Signal: …

  Linia w robots.txt, która mówi, jak systemy AI mogą korzystać z Twoich treści. Wyraża Twoje życzenia; niczego nie blokuje.

  Linia zapisuje Twoje życzenia wobec AI; crawler może ją odczytać albo zignorować.

  Pokazujemy wartość pierwszej linii Content-Signal; to tylko informacja, bez oceny.

  Dla informacjiŹródło: Cloudflare Content Signals (2026-10-21)

HumanKey może wygenerować znaczniki schema.org (JSON-LD) — maszynowo czytelny opis strony, który pomaga systemom AI i wyszukiwarkom zrozumieć, czego dotyczy Twoja treść. Wygenerujesz je w Panel → AI Magnet → robots.txt i llms.txt (plan Pro i wyższe).

Dane strukturalne mają charakter doradczy i nie są dźwignią pozycji ani widoczności. Nie gwarantują cytowań przez AI ani miejsca w wynikach wyszukiwania, a Google wycofał wyniki rozszerzone FAQ w 2026 roku — traktuj je jako maszynowo czytelny kontekst, nie odznakę wyniku rozszerzonego.

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

Jeśli plan Twojego konta przestaje obejmować webhooki, dostarczanie zatrzymuje się po zakończeniu ewentualnego okresu karencji po zmianie planu. Zapisane adresy webhooków pozostają na koncie, a po przejściu na plan z webhookami nowe zdarzenia są znowu dostarczane; zdarzenia z okresu przerwy nie są wysyłane później.

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.

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

Wszystkie powiadomienia są domyślnie włączone. Tygodniowe analizy AI powstają z zagregowanych liczników Twojej witryny (sumy, udziały procentowe, nazwy crawlerów). Analizy mają charakter doradczy (zgodne z EU AI Act).

HumanKey stosuje wieloźródłowy proces klasyfikacji z poszanowaniem prywatności. Każda wizyta jest oceniana w trzech grupach kategorii zanim zostanie wydany werdykt z oceną pewności.

Klasyfikacja odbywa się na naszych serwerach w UE. Wykorzystuje techniczne dane o żądaniu i przeglądarce — w planach Pro i wyższych także wzorce interakcji — a nie imiona i nazwiska, adresy e-mail czy cookies. Wyniki są dostępne w Panelu.

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

HumanKey identyfikuje skoordynowane sieci botów poprzez analizę ruchu z poszanowaniem prywatności. Wykryte grupy pojawiają się w Panelu z ocenami zagrożenia opartymi na pewności klasyfikacji oraz kontekstem operatora sieciowego (na podstawie publicznych rejestrów).

Wykryte sieci botów znajdziesz w sekcji Behavior w Panelu.

Wykrywanie farm botów ma charakter wyłącznie informacyjny — bez automatycznego blokowania. Ta analiza odbywa się na naszych serwerach w UE.

HumanKey oferuje dwie odznaki do osadzenia. To różne produkty — wybierz tę, która pasuje do Twojego planu i celu.

1. Odznaka statusu ruchu ludzkiego (wszystkie plany, w tym Free)

Znacznik statusu na żywo — mała pływająca plakietka odzwierciedlająca udział ludzi i botów w ruchu Twojej strony z ostatnich 24 godzin. Dodaj ten jednolinijkowy skrypt (zawiera Twój klucz publiczny); pojawia się automatycznie, bez konfiguracji.

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

Znajdziesz ją w panelu: AI Magnet → Odznaki (skopiuj fragment). Dostępna w każdym planie, w tym Free.

2. Osadzalna odznaka weryfikacyjna (plan Pro i wyższe)

Statyczny znak zaufania SVG pokazujący Twoją zweryfikowaną domenę, z publiczną stroną weryfikacyjną dostępną po kliknięciu. Włącz ją i ustaw motyw w panelu: AI Magnet → Odznaki, a następnie osadź:

<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 cache do 1 godziny. JavaScript nie jest wymagany. Gdy obowiązuje plan Free, wcześniej włączona odznaka nie zawiera domeny; dla strony, na której odznaka nie jest włączona, obraz odznaki nie jest udostępniany.

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, webhooki)
• •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 w naszej bazie danych i nie można ich odzyskać
• •Nie podejmuje wiążących decyzji. Nie czyta Twoich statystyk ani rekordów wizyt; dla zalogowanych użytkowników otrzymuje wyłącznie ogólny kontekst konta: plan, a w stosownych przypadkach plan, który po nim nastąpi, oraz datę końca okresu karencji lub okresu próbnego, informację, czy na koncie zapisano subskrypcję, liczbę witryn, korzystanie z funkcji i przedział wolumenu ruchu; gdy pracujesz w przestrzeni roboczej innego konta, otrzymuje wyłącznie informację, że jesteś tam członkiem zespołu
• •W przypadku złożonych kwestii użyj linku "Porozmawiaj z człowiekiem" → /contact

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

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

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