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.

Wskazówka

Gotowy snippet z Twoim adresem i identyfikatorem formularza znajdziesz w panelu OctaForms, w zakładce „Osadź formularz“. Poniżej opisane jest, co możesz w nim zmienić.

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

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

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

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

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

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

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.

Uwaga na dane osobowe w adresie

Adres strony podziękowania jest znacznie bardziej publiczny niż samo zgłoszenie. Widzą go: historia przeglądarki, logi serwera, nagłówek Referer wysyłany do zewnętrznych skryptów obecnych na tej stronie oraz Google Analytics, gdzie ląduje jako adres strony (page_location).

Regulamin Google Analytics wprost zabrania wysyłania tam danych osobowych, a RODO wymaga podstawy prawnej dla każdego takiego udostępnienia. Jeśli potrzebujesz danych zgłoszenia na stronie podziękowania, przekaż samo {lead_id} i dociągnij resztę po swojej stronie przez API.

Notatka

Parametry z adresu wypełniają pola formularzy o tej samej nazwie (patrz punkt wyżej). Jeśli na stronie podziękowania stoi kolejny formularz OctaForms albo widget kontaktowy, ?imie=Jan wypełni w nim pole imie. Bywa to wygodne (formularz wieloetapowy), a jeśli tego nie chcesz, nazwij parametry inaczej niż pola.

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>

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