Przejdź do głównej zawartości

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.

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.

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.

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>
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

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=Jan

Wyją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ą.

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 ma gclid, gbraid albo wbraid;
    • 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.com i fb.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 klucza source, 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.

Ś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>

Ś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:

  1. Twój przełącznik, jeśli go użyłeś (opis niżej). Wygrywa zawsze, także z Consent Mode.
  2. Google Consent Mode. Widget sam czyta analytics_storage z tej samej warstwy danych, której używa GTM (dataLayer albo nazwa z data-gtm-layer). Liczy się ostatnia decyzja, więc default: denied, a po kliknięciu w banerze update: granted, to zgoda. Wpis zgody bez analytics_storage (np. tylko ad_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.
  3. 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 zapisuje
gtag('consent', 'update', { analytics_storage: 'granted' }) // zapisuje od bieżącej podstrony
gtag('consent', 'update', { analytics_storage: 'denied' }) // kasuje to, co już zapisano

Samo 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) // zgoda
window.OctaForms.analytics(false) // brak zgody albo jej wycofanie

Przy wyłączonym zapisie zgłoszenie nadal dostaje referrer oraz source, ale source tylko ze strony, na której stoi formularz, i bez ścieżki.

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-5f1b2c3d4e5f

Moż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 po id przez API, musi spokojnie znieść odpowiedź 404.

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.

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.

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).