Osadzanie formularza
Formularz osadzasz w dwóch krokach: raz ładujesz skrypt, a potem stawiasz na stronie tyle miejsc montowania, ile chcesz. Skrypt sam dociąga swój arkusz stylów.
Krok 1: załaduj skrypt
Dział zatytułowany „Krok 1: załaduj skrypt”Wklej raz, tuż przed </body>:
<script src="https://app.octaforms.pl/widget/v1/octaforms.js" async></script>Adres hosta (app.octaforms.pl) zależy od Twojej instancji, dokładny podaje panel. Skrypt sam wstrzykuje
octaforms.css, więc nie musisz ładować osobnego arkusza.
Krok 2: postaw formularz
Dział zatytułowany „Krok 2: postaw formularz”Wskaż miejsce montowania. Masz trzy warianty:
<!-- Formularz w treści strony (domyślnie) --><div data-octa-form="ID_FORMULARZA"></div>
<!-- Przycisk generowany przez widget, otwiera formularz w oknie modalnym --><div data-octa-form="ID_FORMULARZA" data-octa-mode="modal"></div>
<!-- Twój własny element otwiera formularz w oknie modalnym (zachowuje Twój wygląd) --><a href="#" data-octa-trigger="ID_FORMULARZA">Masz pytanie? Napisz do nas</a>Miejsc montowania może być dowolnie wiele, mogą też wskazywać ten sam formularz.
Pływający widget kontaktowy
Dział zatytułowany „Pływający widget kontaktowy”Osobny element (tzw. „słuchawka“) z własnym identyfikatorem. Dodaj atrybut do skryptu albo wstaw pusty element w dowolnym miejscu:
<script src="https://app.octaforms.pl/widget/v1/octaforms.js" data-octa-widget="ID_WIDGETU" async></script><!-- albo --><div data-octa-widget="ID_WIDGETU"></div>Atrybuty
Dział zatytułowany „Atrybuty”| Atrybut | Na czym | Znaczenie | Wartości | Wymagany |
|---|---|---|---|---|
data-octa-form |
element montowania | Punkt osadzenia formularza, wartość to identyfikator formularza | identyfikator formularza | tak (na punkt) |
data-octa-mode |
element data-octa-form |
Sposób wyświetlenia | modal albo brak (inline) |
nie |
data-octa-trigger |
dowolny element | Ten element otwiera formularz w modalu po kliknięciu | identyfikator formularza | nie |
data-octa-widget |
skrypt lub element | Włącza pływający widget kontaktowy | identyfikator widgetu | nie |
data-octa-location |
element montowania, trigger lub widget | Etykieta miejsca osadzenia w eventach analitycznych (zobacz Analityka) | dowolny tekst | nie |
data-api |
element lub skrypt | Nadpisuje adres API dla tego montowania | pełny adres (origin) | nie |
data-css |
skrypt | Nadpisuje adres arkusza stylów | adres pliku CSS | nie |
data-gtm |
skrypt | Wyłącza automatyczny push eventów do GTM (zobacz Analityka) | off |
nie |
data-gtm-layer |
skrypt | Nazwa przemianowanej warstwy danych GTM (domyślnie dataLayer) |
nazwa zmiennej globalnej | nie |
data-analytics |
skrypt | Wyłącza zapis źródła wizyty i ścieżki podstron (zobacz Źródło zgłoszenia) | off |
nie |
Wypełnianie pól z góry
Dział zatytułowany „Wypełnianie pól z góry”Parametry z adresu URL automatycznie wypełniają pola o tej samej nazwie. Klucze, które nie są polami
formularza (np. utm_source, fbclid), są ignorowane, więc nie zaszkodzą:
https://twoja-strona.pl/kontakt?email=jan@example.com&name=JanWyjątkiem jest checkbox zgody RODO (consent: true w definicji pola). Zaznacza go wyłącznie gość:
widget pomija dla niego parametr z adresu, wartość domyślną z definicji oraz wartości przekazane
przez OctaForms.render(…, { values }) i setValues. Zgoda zaznaczona za gościa nie jest
ważną zgodą.
Źródło zgłoszenia
Dział zatytułowany „Źródło zgłoszenia”Do każdego zgłoszenia widget dokleja, skąd przyszedł gość. Dane są w meta zgłoszenia, widać je
w podglądzie w panelu i trafiają do webhooków:
-
referrer: adres strony, z której gość przeszedł na stronę z formularzem, bez parametrów i#, najwyżej 500 znaków. To może być także inna podstrona Twojej witryny. Pusty, gdy przeglądarka nie podała strony odsyłającej. Nic nie jest do tego zapisywane w przeglądarce. -
source: pierwsze zewnętrzne źródło wizyty, nazwane po ludzku:Google Ads: wyszukiwarka Google albo sieć reklamowa Google (googleadservices.com,googlesyndication.com,doubleclick.net), gdy adres strony wejścia magclid,gbraidalbowbraid;Google Organic: wyszukiwarka Google bez tych parametrów. Gmail, Dokumenty Google i logowanie Google nie są wyszukiwarką i dają zwykły adres;Facebook: Facebook, Instagram,fb.comifb.me;- adres strony odsyłającej, ale bez parametrów i
#(np.https://forum.pl/watek), bo tam bywa e-mail albo token. Najwyżej 500 znaków.
Twoja domena z
www.i bez niego oraz jej subdomeny to ta sama witryna, nie źródło. Pierwsza zapisana strona wizyty ustala źródło na stałe. Jeśli gość wszedł bezpośrednio (bez strony odsyłającej), zgłoszenie nie ma kluczasource, nawet gdy później wrócił z bramki płatności albo z logowania. -
user-path: podstrony odwiedzone w tej wizycie, po jednej w wierszu, w formacie[2026-10-14 09:05] /oferta. Zapisujemy samą ścieżkę, bez domeny i parametrów. Lista ma najwyżej 50 pozycji, najstarsze wypadają, a wpisy starsze niż 30 dni są pomijane. Po wysłaniu zgłoszenia ścieżka jest czyszczona, więc kolejne zgłoszenie z tej przeglądarki ma już własną.
Parametry kampanii trafiają do pól, nie do meta. Dodaj do formularza pole typu hidden
nazwane jak parametr (utm_source, utm_medium, utm_campaign, utm_term, utm_content,
gclid, gbraid, wbraid, fbclid), a widget je wypełni. Wartości z pierwszej strony wizyty,
która jakieś ma, zostają zapamiętane, więc formularz kilka podstron dalej też je dostanie. Gdy
strona z formularzem ma w adresie własne parametry kampanii, pola dostają tylko je, w całości,
bez mieszania z zapamiętanymi.
Instalacja na całej stronie
Dział zatytułowany „Instalacja na całej stronie”Ścieżka zawiera tylko te podstrony, na których ładuje się skrypt widgetu. Żeby była pełna, wklej skrypt na każdą podstronę, także tam, gdzie nie ma formularza. Bez tego źródło wizyty dalej działa, a ścieżka obejmuje same strony z formularzem.
<script src="https://app.octaforms.pl/widget/v1/octaforms.js" async></script>Zgoda na zapis w przeglądarce
Dział zatytułowany „Zgoda na zapis w przeglądarce”Ścieżka i pierwsze źródło wizyty są zapisywane w przeglądarce gościa (localStorage i
sessionStorage), a to w świetle przepisów o prywatności zwykle wymaga zgody. Widget nie ma
własnego banera. O zapisie decyduje pierwszy z tych sygnałów, który jest na stronie:
- Twój przełącznik, jeśli go użyłeś (opis niżej). Wygrywa zawsze, także z Consent Mode.
- Google Consent Mode. Widget sam czyta
analytics_storagez tej samej warstwy danych, której używa GTM (dataLayeralbo nazwa zdata-gtm-layer). Liczy się ostatnia decyzja, więcdefault: denied, a po kliknięciu w banerzeupdate: granted, to zgoda. Wpis zgody bezanalytics_storage(np. tylkoad_storage) nie jest decyzją o analityce i nie ma znaczenia. Gdy w warstwie danych nie ma żadnego wpisu zgody (np. baner wdrożony szablonem w GTM), widget czyta stan zgody zapisany przez sam tag Google. - Brak sygnału: zapis działa, tak jak bez Consent Mode.
Pierwszy zapis na podstronie następuje dopiero po wczytaniu całego dokumentu HTML. Dzięki temu
snippet gtag('consent', 'default', …) umieszczony niżej niż skrypt widgetu i tak zdąży przed
zapisem.
Jeśli Twój baner zgód jest już podłączony do Consent Mode, nic więcej nie musisz robić:
gtag('consent', 'default', { analytics_storage: 'denied' }) // widget czeka i nic nie zapisujegtag('consent', 'update', { analytics_storage: 'granted' }) // zapisuje od bieżącej podstronygtag('consent', 'update', { analytics_storage: 'denied' }) // kasuje to, co już zapisanoSamo default: denied znaczy „gość jeszcze nie odpowiedział”: widget nic nie zapisuje, ale też nic
nie kasuje, bo baner wczytany przez GTM wysyła swoją odpowiedź dopiero po skrypcie widgetu. Kasuje
odmowa, czyli update na denied albo Twój przełącznik ustawiony na wyłączenie.
Decyzja zapada przy każdym zapisie i przy wysyłce zgłoszenia, a nie raz przy wczytaniu strony,
więc zgoda albo jej wycofanie w trakcie wizyty działa od razu.
Własny przełącznik ustawisz atrybutem albo zmienną przed skryptem (off wyłącza, on włącza
niezależnie od Consent Mode):
<script src="https://app.octaforms.pl/widget/v1/octaforms.js" data-analytics="off" async></script>
<!-- albo --><script>window.octaFormsAnalytics = false;</script><script src="https://app.octaforms.pl/widget/v1/octaforms.js" async></script>Po decyzji gościa w Twoim banerze możesz też przełączać zapis w locie. Włączenie zapisuje bieżącą podstronę, wyłączenie kasuje to, co już zapisano:
window.OctaForms.analytics(true) // zgodawindow.OctaForms.analytics(false) // brak zgody albo jej wycofaniePrzy wyłączonym zapisie zgłoszenie nadal dostaje referrer oraz source, ale source tylko ze
strony, na której stoi formularz, i bez ścieżki.
Przekierowanie na stronę podziękowania
Dział zatytułowany „Przekierowanie na stronę podziękowania”W ustawieniach formularza w panelu możesz podać adres strony podziękowania. Po przyjęciu
zgłoszenia widget przenosi tam gościa, a wbudowane podziękowanie nie jest wtedy pokazywane.
Do adresu zawsze dopisujemy id z identyfikatorem zgłoszenia:
https://twoja-strona.pl/dziekujemy?id=0195c7f1-9b3a-7c4d-a0e2-5f1b2c3d4e5fMożesz też przekazać dalej wartości ze zgłoszenia. Wpisz nazwę pola w klamrach, a podstawimy w to miejsce to, co przysłał gość:
https://twoja-strona.pl/dziekujemy?imie={name}&f={form_id}| Placeholder | Wartość |
|---|---|
{lead_id} |
Identyfikator zgłoszenia, czyli to samo, co w dopisywanym id. |
{form_id} |
Identyfikator formularza. |
{nazwa_pola} |
Wartość pola o tej nazwie, np. {email}, {phone}. Grupa checkboxes daje zaznaczone warianty po przecinku. |
Zasady:
{lead_id}i{form_id}są zarezerwowane, wygrywają z polem o takiej samej nazwie.- Placeholder wskazujący pole, którego formularz nie ma (np. po zmianie nazwy pola), podstawia się jako pusta wartość.
- Wartości są kodowane, więc znak wpisany w formularzu (
&,#,/) nie rozbije adresu. - Jeśli sam użyjesz parametru
id, zostawiamy Twoją wartość i niczego nie dopisujemy. - Zgłoszenie odfiltrowane jako spam dostaje odpowiedź nieodróżnialną od sukcesu, także
z wypełnionymi placeholderami i z
id, pod którym nie ma żadnego zgłoszenia (celowo: bot nie może poznać, że został wykryty). Jeśli Twoja strona podziękowania dociąga zgłoszenie poidprzez API, musi spokojnie znieść odpowiedź 404.
API w przeglądarce
Dział zatytułowany „API w przeglądarce”Skrypt udostępnia obiekt window.OctaForms:
| Wywołanie | Znaczenie |
|---|---|
OctaForms.mount() |
Ponownie skanuje stronę w poszukiwaniu nowych punktów montowania (przydatne po zmianach DOM). |
OctaForms.render(target, formId, opts?) |
Montuje formularz na elemencie lub selektorze. opts: mode (inline/modal), values (wartości startowe po nazwie pola), apiBase, location (etykieta miejsca w eventach analitycznych). |
OctaForms.setValues(formId, values) |
Ustawia wartości we wszystkich zamontowanych instancjach danego formularza. |
<div id="kontakt"></div><script> OctaForms.render('#kontakt', 'ID_FORMULARZA', { mode: 'inline', values: { email: 'jan@example.com' }, });</script>Wartością w values jest tekst, a dla grupy checkboxes lista wariantów. Liczbę albo wartość
logiczną widget zamienia na tekst (500100200 na "500100200"). Listę przekazaną do pola, które
nie jest grupą, oraz wartości innego rodzaju (null, obiekt) pomija.
Stylowanie
Dział zatytułowany „Stylowanie”Widget renderuje się w zwykłym DOM z bazowymi stylami o zerowej specyficzności, więc dopasowujesz go zwykłym CSS. Nie ma atrybutu motywu ani koloru, wszystko ustawiasz zmiennymi CSS:
.octa-forms { --octa-forms-submit-bg: #2563eb; --octa-forms-submit-color: #fff; --octa-forms-submit-radius: 8px; --octa-forms-control-bg: #fff; --octa-forms-control-border: #d1d5db; --octa-forms-control-radius: 6px; --octa-forms-focus-color: #2563eb; --octa-forms-error-color: #dc2626; --octa-forms-label-size: 14px; --octa-forms-label-weight: 600; --octa-forms-gap: 16px; --octa-forms-max-width: 480px;}Do precyzyjnych zmian użyj klas .octa-forms__* (np. .octa-forms__submit). Każdy wiersz pola ma
atrybut z nazwą pola, data-octa-field="email", więc jedno konkretne pole stylujesz albo znajdujesz
skryptem bez zgadywania kolejności.
Formularz z sekcjami renderuje każdą sekcję jako fieldset.octa-forms__section (z tytułem
.octa-forms__section-title, tekstem .octa-forms__section-text, polami w
.octa-forms__section-fields i notką .octa-forms__section-note), a przy krokach dochodzi pasek
.octa-forms__steps z .octa-forms__step-progress, .octa-forms__step-back i
.octa-forms__step-next. Wygląd kart ustawiasz zmiennymi:
.octa-forms { --octa-forms-section-bg: transparent; --octa-forms-section-border: 1px solid #e4e4e9; --octa-forms-section-radius: 8px; --octa-forms-section-padding: 20px; --octa-forms-section-title-size: 17px; --octa-forms-section-text-size: 15px; --octa-forms-muted: #5f5f6b;}Formularz renderuje jedną kolumnę. Układ w kolumny zostaje po Twojej stronie: zaczep się na
.octa-forms__section-fields i na [data-octa-field].
Pływający widget kontaktowy
stylujesz zmiennymi --cb-* na .octa-forms-callback oraz klasami .octa-forms-callback__*.
Teksty formularza (etykiety pól, napis na przycisku, treść podziękowania) ustawiasz w panelu, przy konfiguracji formularza, a nie w kodzie osadzenia.
Formularz bez widgetu
Dział zatytułowany „Formularz bez widgetu”Jeśli potrzebujesz własnej struktury HTML (formularz wieloetapowy, nietypowe kontrolki, integracja z własnym design systemem), możesz pominąć widget i wysyłać zgłoszenia prosto do publicznego API. Przejmujesz wtedy handshake antybotowy, obsługę błędów i analitykę: krok po kroku opisuje to Własny frontend (Astro).