Przejdź do głównej zawartości

Next.js

Zainstaluj snippet śledzący Selgeo w aplikacji Next.js, korzystając z natywnego komponentu frameworka next/script. Niniejszy przewodnik obejmuje zarówno App Router (app/layout.tsx), jak i Pages Router (pages/_app.tsx).

Wersja API: v1

Jeśli nie używasz Next.js, zobacz przewodnik HTML / zwykłego skryptu, przewodnik React (Vite) lub przewodnik WordPress.

Dlaczego next/script?​

Goły tag <script> w komponencie React nie zachowuje się tak, jak w zwykłym HTML — Next.js paczkuje JavaScript dla każdej trasy i hydratuje strony stopniowo. Oficjalny komponent next/script:

  • Ładuje snippet dokładnie raz w trakcie nawigacji po stronie klienta (brak podwójnego wykonania).
  • Respektuje wybraną przez Ciebie strategy ładowania (używamy afterInteractive).
  • Dobrze współpracuje ze strumieniowym SSR Next.js i Partial Prerendering.

Używamy strategy="afterInteractive" zamiast lazyOnload, aby snippet był gotowy przed przetworzeniem pierwszego parametru ?ref=. Dokładność atrybucji jest ważniejsza niż marginalna poprawa Lighthouse — lazyOnload grozi przeoczeniem wczesnego kliknięcia, które konwertuje natychmiast.

Instalacja — App Router (app/layout.tsx)​

Dla projektów na Next.js 13+ używających katalogu app/.

Krok 1: Dodaj snippet do głównego layoutu​

Otwórz app/layout.tsx i dodaj import Script oraz element JSX:

import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          async
          src="https://cdn.selgeo.com/v1/selgeo.js"
          data-merchant="pk_test_YOUR_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Zastąp pk_test_YOUR_KEY swoim publicznym kluczem API z Ustawienia > Klucze API w panelu Selgeo.

Strona Settings &gt; API Keys w panelu Selgeo z wyróżnionym polem klucza publicznego

Krok 2: Zapisz i uruchom​

pnpm dev
# lub
npm run dev

Otwórz stronę w przeglądarce. Snippet ładuje się teraz na każdej stronie renderowanej przez App Router.

Instalacja — Pages Router (pages/_app.tsx)​

Dla projektów na starszym katalogu pages/.

Krok 1: Dodaj snippet do niestandardowego komponentu App​

Otwórz (lub utwórz) pages/_app.tsx:

import type { AppProps } from 'next/app';
import Script from 'next/script';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        async
        src="https://cdn.selgeo.com/v1/selgeo.js"
        data-merchant="pk_test_YOUR_KEY"
        strategy="afterInteractive"
      />
    </>
  );
}

Krok 2: Zrestartuj serwer deweloperski​

pnpm dev

Projekty Pages Router muszą zrestartować serwer deweloperski przy pierwszym utworzeniu _app.tsx. Późniejsze edycje są normalnie ładowane na gorąco.

Karta Tracking Snippet w Settings pokazująca tab Next.js z blokami import i komponentu gotowymi do skopiowania

Atrybuty wymagane i opcjonalne​

AtrybutWymaganyOpis
srcTakURL CDN. Zawsze https://cdn.selgeo.com/v1/selgeo.js.
data-merchantTakTwój publiczny klucz API (pk_test_* lub pk_live_*).
asyncTakAsynchroniczne ładowanie; nie blokuje hydratacji.
strategyTakUżyj "afterInteractive". Nie przełączaj na "lazyOnload" — wczesne kliknięcia poleceń mogą zostać pominięte.
data-debugNieWłącza obszerne logowanie w konsoli. Usuń przed wdrożeniem produkcyjnym.
data-api-urlNieNadpisuje endpoint API. Obecny tylko w workspace'ach staging / dev — panel Selgeo wstrzykuje go automatycznie, gdy jest potrzebny.

Weryfikacja instalacji​

  1. Zbuduj i uruchom projekt (pnpm dev lub pnpm build && pnpm start).
  2. Utwórz link śledzący w panelu Selgeo w Programy > Linki śledzące.
  3. Odwiedź swoją stronę za pomocą linku śledzącego, na przykład: 
    https://twoja-strona.com/?ref=TWOJ_TESTOWY_REF
  4. Otwórz Narzędzia deweloperskie (F12) i sprawdź konsolę. Z tymczasowo dodanym data-debug powinno wyświetlić się: 
    [selgeo] ref detected TWOJ_TESTOWY_REF
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. W konsoli przeglądarki wykonaj: 
    __selgeo.getClickId()
    Powinno to zwrócić ciąg UUID. null oznacza, że snippet nie wykrył parametru ?ref=.
  6. Otwórz panel Selgeo. Kliknięcie powinno pojawić się w Analytics w ciągu kilku sekund.

Widok Selgeo Analytics pokazujący ostatnią aktywność kliknięć i najlepszych partnerów

Rozwiązywanie problemów​

Snippet nie został załadowany​

  • Potwierdź, że app/layout.tsx (App Router) lub pages/_app.tsx (Pages Router) faktycznie zawiera blok <Script> — przypadkowe duplikowanie do pojedynczego pliku strony to najczęstszy błąd.
  • Sprawdź, że src to dokładnie https://cdn.selgeo.com/v1/selgeo.js. Literówka powoduje ciche niepowodzenie ładowania skryptu.
  • Otwórz kartę Network i filtruj po selgeo.js. Czerwony wpis ze statusem 0 lub błędem CORS zwykle wskazuje na naruszenie CSP — zobacz poniżej.
  • Jeśli działasz w trybie eksportu statycznego (output: 'export'), upewnij się, że snippet jest zawarty w wyeksportowanym HTML-u. next/script z strategy="afterInteractive" jest zachowywany w eksporcie statycznym.

Kliknięcie nie zostało zarejestrowane​

  • Odwiedzający musi przybyć z ?ref=… przy początkowym ładowaniu strony. Po przechwyceniu kliknięcia przez snippet URL jest przepisywany i parametr przestaje się pojawiać. Załaduj stronę ponownie z nowym linkiem śledzącym, jeśli aktualny został już użyty.
  • Potwierdź, że data-merchant zawiera prawidłowy klucz pk_test_* lub pk_live_*. Skrócona lub poprzedzona spacją wartość spowoduje ciche niedziałanie.
  • Jeśli używasz React Strict Mode, upewnij się, że snippet jest w app/layout.tsx lub pages/_app.tsx, a nie w efekcie, który może uruchomić się dwukrotnie. next/script już prawidłowo deduplikuje.
  • Sprawdź tryb panelu Selgeo (test vs. live). Klucz pk_live_* na linku śledzącym wydanym w trybie testowym nie zarejestruje kliknięcia.

Blokowanie przez CSP​

Jeśli Twój projekt Next.js ustawia nagłówek Content-Security-Policy (next.config.js headers(), middleware lub wpis w vercel.json), zezwól na pochodzenia Selgeo:

script-src 'self' https://cdn.selgeo.com;
connect-src 'self' https://api.selgeo.com;

Dla workspace'ów staging / dev, gdzie data-api-url wskazuje gdzie indziej, dodaj również to pochodzenie do connect-src. Jeśli nie możesz złagodzić CSP, rozważ routowanie snippeta przez własne pochodzenie (zaawansowane, poza zakresem tego przewodnika).

Następne kroki​