Osadzanie scorecardy

Opublikowana scorecarda może działać bezpośrednio w obrębie Twojej witryny. Wystarczy dodać pojedynczy znacznik script; utworzy on elastyczną ramkę iframe, która automatycznie dostosowuje swoją wysokość w miarę, jak użytkownik przechodzi przez pytania.

Wtyczka WordPress

Używasz WordPressa? Oficjalna wtyczka DimensionKit for WordPress umożliwia osadzanie scorecard za pomocą bloku Gutenberg lub shortcode’a bez konieczności edycji kodu.

Włączanie osadzania

Osadzanie jest domyślnie wyłączone i wymaga aktywacji dla każdej scorecardy z osobna.

1. Otwórz panel administracyjny pod adresem https://app.dimensionkit.com/admin
2. Przejdź do edycji scorecardy i otwórz zakładkę Embed
3. Włącz opcję Embed
4. Wpisz listę dozwolonych domen (origins)
5. Skopiuj wygenerowany fragment kodu

Osadzać można wyłącznie opublikowane scorecardy. Wersje robocze (draft) zwracają błąd 404.

Dozwolone domeny (Origins)

Origin składa się z protokołu, hosta i portu — bez ścieżek podstron ani kończących ukośników:

https://example.com
https://www.example.com
http://localhost:3000

https://example.com i https://www.example.com to dwa różne źródła. Jeśli Twoja strona działa pod obydwoma adresami, podaj oba.

Skrypt ładujący przekazuje aplikacji informację o stronie, na której został uruchomiony. Jeśli źródło nie znajduje się na liście dopuszczonych, ramka zwróci kod 403. Zasada ta jest wymuszana po stronie serwera nagłówkiem Content-Security-Policy: frame-ancestors i chroni formularz, nawet jeśli ktoś skopiuje Twój kod na obcą stronę.

Fragment kodu

<div id="scorecard"></div>
<script
  src="https://app.dimensionkit.com/embed.js"
  data-dk-scorecard="twoj-scorecard-slug"
  data-dk-target="#scorecard"
></script>

Atrybut	Wymagany	Przeznaczenie
data-dk-scorecard	tak	Unikalny slug scorecardy
data-dk-target	tak	Selektor CSS kontenera docelowego
data-dk-min-height	nie	Początkowa wysokość w pikselach przed pierwszym dopasowaniem
data-dk-title	nie	Tytuł dostępności dla ramki iframe

Ręczne osadzanie za pomocą JavaScript

Jeśli chcesz wywołać osadzanie dynamicznie — w aplikacji jednostronicowej (SPA) lub przez CMS:

<div id="scorecard"></div>
<script src="https://app.dimensionkit.com/embed.js"></script>
<script>
  window.DimensionKit.embed({
    target: '#scorecard',
    scorecard: 'twoj-scorecard-slug',
    minHeight: 640,
    title: 'Scorecard',
  });
</script>

Reagowanie na działania użytkownika

Komponent emituje zdarzenia niestandardowe (Custom Events) na elemencie docelowym, co pozwala na uruchamianie analityki lub wyświetlanie dodatkowych komunikatów po ukończeniu:

document.querySelector('#scorecard')
  .addEventListener('dimensionkit:completed', () => {
    // Użytkownik dotarł do ekranu wyników
  });

Zdarzenie	Kiedy występuje
dimensionkit:loaded	Scorecarda została załadowana i jest gotowa do użycia
dimensionkit:resize	Wysokość treści uległa zmianie; ramka dopasowała rozmiar
dimensionkit:completed	Użytkownik dotarł do ekranu wyników
dimensionkit:error	Błąd ładowania formularza lub wysyłania odpowiedzi

Identyczne komunikaty są przekazywane do okna nadrzędnego za pośrednictwem postMessage.

Rozwiązywanie problemów

Puste pole w miejscu formularza. Niemal zawsze wynika to z braku autoryzacji domeny. Otwórz konsolę przeglądarki: błąd 403 oznacza brak domeny na liście dozwolonych. Zwróć uwagę na przedrostek www. oraz różnicę między http a https.

Błąd 404 zamiast scorecardy. Niepoprawny slug, wersja robocza formularza lub brak włączenia opcji osadzania w panelu.

Formularz ładuje się, ale nie zmienia wysokości. Element nadrzędny w Twojej witrynie ogranicza wymiary ramki. Skrypt zarządza wysokością iframe, ale nie może przekroczyć kontenera o sztywno ustalonej wysokości (height) lub regule overflow: hidden.