Jak działa widget - PoliczCieplo.pl

Od znacznika do wyniku

Co dzieje się na Twojej stronie

Pięć etapów pokazuje granicę między Twoją stroną, widgetem i stroną wyniku.

01
Przeglądarka rozpoznaje znacznik
Skrypt ładuje własny element HTML umieszczony w treści Twojej strony i zamienia go w kalkulator.
02
Kalkulator renderuje się w Shadow DOM
Pełny interfejs działa we własnym drzewie. Shadow DOM ogranicza wpływ stylów Twojej strony, ale nie jest obietnicą pełnej odporności na każdy arkusz CSS.
03
Odwiedzający przechodzi siedem kroków
Proces prowadzi przez typ budynku, lokalizację, konstrukcję, wymiary, przegrody, wentylację i ogrzewanie.
04
Widget emituje viewresult
Zdarzenie bąbelkuje i przechodzi przez granicę Shadow DOM. Twoja strona może je przechwycić i policzyć u siebie.
05
Wynik otwiera się w nowej karcie
Adres wyniku powstaje na podstawie result-host-url. Twoja strona zostaje otwarta w poprzedniej karcie.

Kontrakt publiczny

Jeden znacznik, sześć opisanych atrybutów

Trzy atrybuty są wymagane. Pozostałe uzupełniasz tylko wtedy, gdy są potrzebne.

HTML

<script src="https://embed.policzcieplo.pl/v1/policzcieplo-kalkulator.js" defer></script>
<policzcieplo-kalkulator-ozc
    public-key="pc_..."
    api-base-url="https://policzcieplo.pl/api"
    result-host-url="https://policzcieplo.pl"
    lang="pl">
</policzcieplo-kalkulator-ozc>

Zarezerwuj wysokość. Widget wymaga co najmniej 600 px i zajmuje obszar zbliżony do wysokości pełnego ekranu.

JavaScript - nasłuch zdarzenia

document.addEventListener("viewresult", (event) => {
    // event.detail = { url, uuid }
    console.log(event.detail.url, event.detail.uuid);
});

Atrybuty znacznika `policzcieplo-kalkulator-ozc`
Atrybut	Wymagany	Opis
`public-key`	Tak	Klucz publiczny zarejestrowanej strony, w formacie pc_...
`api-base-url`	Tak	Adres API, z którego kalkulator pobiera dane.
`result-host-url`	Tak	Adres, pod którym otwiera się wynik.
`google-maps-api-key`	Nie	Klucz Google Maps. Brak atrybutu uruchamia OpenStreetMap.
`lang`	Nie	Kod języka. Wbudowana paczka zawiera tłumaczenia polskie.
`translations-url`	Nie	Adres zewnętrznego pliku tłumaczeń.

Zdarzenieviewresultbubbles: truecomposed: true

Wysyłane, gdy obliczenia się kończą i wynik jest gotowy do otwarcia. Ładunek zdarzenia to { url, uuid }: adres raportu i identyfikator kalkulacji.

To nie jest tylko haczyk analityczny. Gdy przeglądarka zablokuje wyskakujące okna, widget nie otworzy wyniku i viewresult zostaje jedyną drogą, żeby przenieść odwiedzającego do raportu. Warto je obsłużyć.

Jasne zasady

Co widget robi, a czego nie robi

Te granice pozwalają zaplanować osadzenie bez założeń, których publiczny kontrakt nie spełnia.

Widget robi

Renderuje pełny, siedmiostopniowy kreator na Twojej stronie.
Otwiera wynik w nowej karcie pod adresem z result-host-url.
Przełącza lokalizację na OpenStreetMap, gdy nie ma klucza Google Maps.
Uruchamia się wyłącznie tam, gdzie klucz publiczny spotyka dozwolony adres.
Udostępnia 30-dniowy tryb deweloperski dla localhost.
Pozwala obrócić klucz i unieważnić stronę.

Widget nie robi

Nie stawia ciasteczek. Roboczą wersję formularza zapisuje jednak w localStorage Twojej strony.
Nie zmienia wyglądu pod markę integratora.
Nie mierzy ruchu za Twoją stronę. Zdarzenie viewresult możesz policzyć we własnym systemie.
Nie zawiera wbudowanych tłumaczeń innych niż polskie.
Nie dopasowuje automatycznie wysokości. Wymaga co najmniej 600 px.

FAQ

Najczęstsze pytania przed wdrożeniem

Czy potrzebuję klucza Google Maps?: Nie. Gdy atrybut google-maps-api-key jest nieobecny, krok lokalizacji korzysta z OpenStreetMap.
Czy publiczny klucz może być widoczny w źródle strony?: Tak. Klucz pc_... jest jawny z założenia. Ochronę daje jego połączenie z listą dozwolonych adresów.
Co widget zapisuje w przeglądarce?: Nie stawia ciasteczek. Zapisuje roboczą wersję formularza w localStorage Twojej strony, żeby odwiedzający nie tracił postępu.
Ile miejsca trzeba przygotować?: Co najmniej 600 px wysokości. W praktyce widget zajmuje obszar zbliżony do pełnej wysokości ekranu.