Konfiguracja snippeta

Ta strona to przewodnik instalacji HTML / zwykłego skryptu dla snippeta śledzącego Selgeo (selgeo.js) — lekkiego pliku JavaScript działającego na Twojej stronie, który rejestruje kliknięcia poleceń partnerskich i przechowuje dane atrybucji w przeglądarce odwiedzającego do późniejszego dopasowania konwersji. Skorzystaj z tego przewodnika, jeśli kontrolujesz surowy HTML swojej strony bezpośrednio (strony statyczne, Webflow, Shopify Liquid, niestandardowe strony renderowane po stronie serwera lub menedżer tagów).

Używasz frameworka?

• Next.js — zobacz przewodnik Next.js dla wzorca komponentu next/script.
• React (Vite) — zobacz przewodnik React (Vite) dla umieszczenia w index.html oraz fallbacku z useEffect.
• WordPress — zobacz przewodnik WordPress dla umieszczenia przez Edytor witryny, footer.php i wtyczki header-footer.

Wersja API: v1

Podstawowa instalacja

Dodaj następujący tag <script> do każdej strony swojej witryny, tuż przed zamykającym tagiem </body>:

<script
  async
  src="https://cdn.selgeo.com/v1/selgeo.js"
  data-merchant="pk_test_YOUR_KEY"
></script>

Wymagane atrybuty

Atrybut	Opis
src	Adres URL CDN dla snippeta. Zawsze używaj https://cdn.selgeo.com/v1/selgeo.js.
data-merchant	Twój publiczny klucz API (pk_test_* dla trybu testowego, pk_live_* dla trybu live).
async	Ładuje snippet asynchronicznie, aby nie blokować renderowania strony.

Opcjonalne atrybuty

Atrybut	Opis
data-debug	Włącza logowanie debugowania w konsoli przeglądarki. Usuń przed uruchomieniem.
data-api-url	Zastępuje adres URL punktu końcowego API. Tylko do zaawansowanego użytku.

Jak działa

Gdy odwiedzający przybywa na Twoją stronę z parametrem ?ref= w adresie URL, snippet:

1. Wykrywa parametr zapytania ref.
2. Rejestruje kliknięcie w API Selgeo przy użyciu Twojego klucza publicznego.
3. Przechowuje click_id zwrócony przez API w sessionStorage przeglądarki.
4. Usuwa ?ref= z adresu URL przy użyciu history.replaceState.
5. Przepisuje Stripe Payment Links na stronie, dodając client_reference_id=CLICK_ID.

Mechanizm przechowywania

Klucz	Wartość	Czas życia
__selgeo_cid	click_id (UUID)	Do zamknięcia karty przeglądarki
__selgeo_vtk	Token odwiedzającego (UUID)	Do zamknięcia karty przeglądarki

Implikacje dla prywatności:

• sessionStorage jest ograniczony do karty — nie jest współdzielony między kartami ani oknami.
• Dane są automatycznie czyszczone po zamknięciu karty.
• Nie są ustawiane żadne pliki cookie.

Odczytywanie ID kliknięcia

const clickId = __selgeo.getClickId();
// Zwraca ciąg UUID lub null jeśli nie zarejestrowano kliknięcia polecającego

Dostępne metody

Metoda	Zwraca	Opis
__selgeo.getClickId()	string | null	Bieżące ID kliknięcia lub null jeśli nie istnieje
__selgeo.getVisitorToken()	string | null	Bieżący token odwiedzającego lub null
__selgeo.checkUrl()	void	Ręcznie sprawdza bieżący adres URL pod kątem parametru ?ref=

Aplikacje jednostronicowe (SPA)

Snippet automatycznie monitoruje zmiany adresów URL w aplikacjach jednostronicowych, nasłuchując zdarzeń popstate oraz wywołań history.pushState/history.replaceState.

Automatyczne przepisywanie Stripe Payment Links

Jeśli Twoja strona zawiera linki do Stripe Payment Links (https://buy.stripe.com/...), snippet automatycznie dodaje ?client_reference_id=CLICK_ID gdy aktywne jest kliknięcie polecające.

Snippet musi być na stronie docelowej

Parametr ?ref= jest obecny tylko w początkowym adresie URL, gdy odwiedzający kliknie link partnera. Jeśli snippet nie jest załadowany na tej stronie, kliknięcie nie zostanie zarejestrowane.

Zalecenia dotyczące umieszczenia

Scenariusz	Zalecenie
Standardowa witryna	Dodaj do każdej strony przez globalny layout/szablon
SPA (React, Vue itp.)	Dodaj raz do index.html — snippet obsługuje zmiany tras
Tylko strony docelowe	Dodaj tylko do stron, na których ląduje ruch partnerski
Tylko strona płatności	Niezalecane — snippet musi być na stronie docelowej

Następne kroki

• Stripe Payment Links — integracja Stripe bez backendu
• Stripe Checkout — przekazywanie click_id do sesji płatności
• Stripe Metadata — przekazywanie click_id przez metadane
• API konwersji — śledzenie konwersji nie-Stripe