// Integracje / Astro

Visitant w Astro

Strony w Astro to w większości statyczny HTML, czyli najprostszy przypadek: jedna linijka skryptu w bazowym layoucie i każda podstrona jest policzona. Jeśli używasz przejść między stronami albo renderowania na żądanie, dwie krótkie uwagi niżej mówią dokładnie, co się zmienia.

Czego potrzebujesz

• Projekt Astro ze wspólnym layoutem (zwykle src/layouts/Layout.astro), którego używa każda podstrona.
• Darmowe konto Visitant z dodaną domeną, np. twojastrona.pl.
• Tylko do części o botach AI: renderowanie na żądanie z adapterem (@astrojs/node, @astrojs/vercel, @astrojs/netlify albo @astrojs/cloudflare) oraz Klucz serwera strony z zakładki Ustawienia strony - Śledzenie botów AI (serwer).

Instalacja w 5 krokach

1. 01 Wstaw skrypt do head bazowego layoutu

   Otwórz layout, który opakowuje każdą podstronę, i wklej linijkę Visitant do <head>. Zamień twojastrona.pl na swoją domenę. Dyrektywa is:inline mówi Astro, żeby zapisał tag w HTML-u dokładnie tak, jak jest, zamiast próbować go bundlować. Dokumentacja dyrektyw Astro podaje, że is:inline jest domyślnie zakładane, gdy skrypt ma jakikolwiek atrybut poza src - nasz ma defer i data-domain - ale wpisanie go wprost jasno pokazuje zamiar następnej osobie.

   ---
   // src/layouts/Layout.astro
   const { title } = Astro.props;
   ---
   <html lang="pl">
     <head>
       <meta charset="utf-8" />
       <title>{title}</title>
       <script is:inline defer data-domain="twojastrona.pl" src="https://annuora.com/v.js"></script>
     </head>
     <body>
       <slot />
     </body>
   </html>Kopiuj

   Masz kilka layoutów (blog, dokumentacja, landing)? Wklej linijkę w każdym albo w małym komponencie Head.astro, który wszystkie dołączają. Jedna linijka na stronę, nigdy dwie.

2. 02 Zbuduj i wdróż

   Uruchom npm run build i wdróż jak zwykle. Otwórz produkcyjną domenę i przejdź przez kilka podstron. Tracker celowo ignoruje localhost, więc npm run dev nic nie pokaże w panelu; jeśli chcesz testować lokalnie, dodaj do skryptu data-local.

3. 03 Używasz przejść między stronami? Nic więcej - i jedna rzecz do uniknięcia

   Z <ClientRouter /> w head Astro nawiguje bez pełnego przeładowania i, według przewodnika o przejściach, tworzy nowy wpis przez history.pushState. Tracker Visitant opakowuje pushState przy pierwszym załadowaniu, więc każda nawigacja jest zapisywana jako odsłona automatycznie. Podczas podmiany head Astro zostawia skrypty, które istnieją też na nowej stronie, więc tracker nie jest ani usuwany, ani uruchamiany ponownie.

   Nie dodawaj data-astro-rerun do skryptu Visitant. Ten atrybut wymusza ponowne wykonanie skryptu po każdym przejściu; tracker opakowałby wtedy pushState drugi raz i liczył strony podwójnie. Zostaw zwykłą linijkę z kroku 1.

4. 04 Policz boty AI na serwerze (tylko SSR)

   GPTBot, ClaudeBot i pozostałe z 44 botów, które Visitant rozpoznaje, nigdy nie uruchamiają JavaScriptu, więc skrypt ich nie widzi. W czysto statycznym buildzie nie ma kodu serwerowego w chwili żądania - przewodnik Astro o middleware podaje, że dla stron prerenderowanych middleware działa w czasie builda - więc statyczna strona na Netlify albo Vercelu nie policzy botów, chyba że postawisz przed nią fragment dla Cloudflare Workers z panelu. Jeśli strona używa renderowania na żądanie z adapterem Node w trybie middleware, dodaj poniższy fragment do swojego serwera Express (lub podobnego) i zamień TWÓJ-KLUCZ na Klucz serwera. Serwer opuszczają tylko żądania, których user agent pasuje do listy botów, więc ruch ludzi nic nie kosztuje.

   const AI_UA = /bot|crawl|spider|GPTBot|ChatGPT-User|OAI-SearchBot|Claude|anthropic|Perplexity|Google-|GoogleOther|Applebot|meta-external|Meta-WebIndexer|Amazonbot|Amzn-|Bytespider|CCBot|MistralAI|DuckAssist|YouBot|xAI|Grok|cohere|Diffbot|Kimi|Qwen|Manus|Firecrawl/i;
   app.use((req, res, next) => {
     const ua = req.get('user-agent') || '';
     if (AI_UA.test(ua)) res.on('finish', () => fetch('https://annuora.com/api/bot', {
       method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Visitant-Key': 'TWÓJ-KLUCZ' },
       body: JSON.stringify({ ua, path: req.originalUrl, ip: req.ip, status: res.statusCode })
     }).catch(() => {}));
     next();
   });Kopiuj

   Adapter Node w trybie standalone albo Vercel/Netlify ze stronami na żądanie? Wstaw to samo sprawdzenie w src/middleware.ts: wyeksportuj onRequest(context, next), odczytaj context.request.headers.get('user-agent'), wywołaj const res = await next() i jeśli wyrażenie pasuje, wyślij przez fetch ten sam JSON (ua, path, ip, status: res.status) z nagłówkiem X-Visitant-Key, zanim zwrócisz res. Pamiętaj, że działa to tylko dla stron z prerender = false (albo output: 'server').

5. 05 Potwierdź kanał botów

   Wdróż ponownie i otwórz w panelu Ustawienia strony - Śledzenie botów AI (serwer): ramka mówi Czekamy na pierwsze wejście bota, dopóki żaden nie zajrzy, a potem Działa: N wizyt botów zapisanych. Żeby sprawdzić od razu: curl -A "GPTBot/1.4" https://twojastrona.pl/. Wejścia botów nigdy nie wliczają się do limitu zdarzeń w planie.

Czy działa? Sprawdź w 60 sekund

Zrób to na wdrożonej stronie, z panelem Visitant otwartym w drugiej karcie.

• Licznik osób teraz na górze panelu pokazuje 1, gdy Twoja strona jest otwarta.
• Podejrzyj źródło strony (Ctrl+U): linijka v.js jest w <head>, nietknięta przez bundler (bez nazwy pliku z hashem), dokładnie raz.
• Z <ClientRouter />: kliknij dwa wewnętrzne linki bez przeładowania; obie ścieżki pojawiają się w tabeli Strony, po jednej odsłonie, a zakładka Sieć w narzędziach deweloperskich pokazuje jedno żądanie api/e na nawigację.
• SSR z fragmentem: wykonaj curl -A "GPTBot/1.4" https://twojastrona.pl/; w ciągu minuty sekcja Boty AI czytające Twoją stronę pokaże GPTBot z 1 wejściem.
• Wejdź na stronę z odpowiedzi Perplexity (albo dopisz ?utm_source=perplexity.ai): tabela Źródła pokaże Perplexity w kanale AI.

Częste problemy

Tag skryptu w zbudowanym HTML-u wygląda inaczej albo go nie ma	Astro próbował przetworzyć go jako skrypt do bundlowania. Upewnij się, że linijka ma is:inline i jest wpisana bezpośrednio w layoucie .astro, a nie importowana z pliku .ts.
Strony liczą się podwójnie przy przejściach	Albo skrypt ma data-astro-rerun, albo dwa layouty go zawierają i jakaś strona używa jednego wewnątrz drugiego. Usuń atrybut i zostaw jedną linijkę na stronę.
W trakcie pracy lokalnie nic się nie pojawia	Tak ma być: tracker nie działa na localhost. Dodaj do skryptu data-local na czas testów i usuń go potem.
Wejścia botów stoją na zerze na statycznej stronie	Statyczne strony nie mają kodu serwerowego w chwili żądania, więc nic nie może zgłosić bota. Przełącz odpowiednie trasy na renderowanie na żądanie albo postaw przed stroną fragment dla Cloudflare Workers.

Pytania