Einbettung per Script

Das Script-Snippet funktioniert auf jeder Website – ob statisches HTML, CMS oder Single-Page-App. Es lädt einmalig embed.js und zeigt die Umfrage an jeder Stelle, an der ein Platzhalter steht.

<div data-pollyou-survey="AbC123xyz0"></div>
<script src="https://embed.pollyou.org/v1/embed.js" async></script>

AbC123xyz0 ist die öffentliche ID der Umfrage (im Dashboard unter „Teilen“). Das Script darf an beliebiger Stelle stehen und wird nur einmal pro Seite benötigt, auch bei mehreren Umfragen. Platzhalter, die später entstehen (z. B. durch nachgeladene Inhalte), werden automatisch erkannt.

Mehrere Umfragen

Jeder Platzhalter wird zu einer eigenständigen Umfrage. Sie laden, speichern und zeigen Ergebnisse unabhängig voneinander:

<div data-pollyou-survey="AbC123xyz0"></div>
<div data-pollyou-survey="XyZ987abc1" data-locale="en"></div>
<script src="https://embed.pollyou.org/v1/embed.js" async></script>

Optionen

Optionen werden als data-*-Attribute am Platzhalter gesetzt:

Attribut	Bedeutung
data-embed-id	Einbettungs-Konfiguration aus dem Dashboard (z. B. für erlaubte Domains und Statistiken je Einbettung).
data-locale	Sprache, z. B. de oder en. Standard: Sprache der Seite (<html lang>), dann die des Browsers. Wählt bei mehrsprachigen Umfragen auch die Sprache der Umfrage.
data-theme	Farbschema: auto (Standard, folgt dem Dark Mode des Systems), light oder dark.
data-mode	inline (Standard), popup, slider oder fullpage – Overlays mit Auslösern, siehe Popup, Slider und Ganzseite. Ohne Attribut gilt die Darstellung der Embed-Konfiguration.
data-show-results	false blendet Ergebnisse aus, auch wenn die Umfrage sie anzeigen würde.
data-live-results	Angezeigte öffentliche Ergebnisse aktualisieren sich in Echtzeit, siehe Live-Ergebnisse.
data-hidden-<name>	Verstecktes Feld, z. B. data-hidden-kundennummer="4711". Wird mit der Antwort gespeichert (siehe unten).
data-meta	Mehrere Werte als JSON, z. B. data-meta='{"tarif":"pro","sitze":5}' (höchstens 20 Werte).
data-identity-token	Signierte Identität angemeldeter Nutzer (für Umfragen mit Identitätsprüfung).
data-api-base	Adresse der PollYou-API, nur bei eigener Installation nötig.

Versteckte Felder

Werte der einbettenden Seite (Kundennummer, Kampagne, Tarif …) kommen auf zwei Wegen in die Antwort:

• Metadaten: Jedes data-hidden-<name> und jeder Eintrag in data-meta wird als Metadatum der Antwort gespeichert (filterbar in der Auswertung). Bindestriche im Namen werden zu Unterstrichen (data-hidden-kunden-nr → kunden_nr). Erlaubt sind Namen aus Kleinbuchstaben, Ziffern und _ mit höchstens 32 Zeichen und Texte bis 200 Zeichen; andere Werte werden ignoriert.
• Fragetyp „Verstecktes Feld“: Enthält die Umfrage ein verstecktes Feld, dessen Schlüssel dem Namen entspricht (z. B. Schlüssel kampagne und data-hidden-kampagne="newsletter"), wird der Wert zusätzlich als Antwort auf diese Frage gespeichert (bis 500 Zeichen) und erscheint wie jede andere Antwort in Auswertung und Export. Das Feld wird nie angezeigt und ist nie Pflicht; fehlt der Wert, bleibt die Frage unbeantwortet. Beim Direktlink übernimmt PollYou den Wert aus dem URL-Parameter mit dem Schlüssel des Felds, z. B. …/s/AbC123xyz0?kampagne=newsletter.

Bei einer eigenen Installation wird die API-Adresse einmal am Script gesetzt:

<script
  src="https://cdn.example.com/v1/embed.js"
  data-api-base="https://umfragen.example.com"
  async
></script>

Versionen und Integrität

Pfad	Verhalten
/v1/embed.js	Kanal: erhält automatisch alle kompatiblen Updates der Version 1 (Cache 5 Minuten).
/v1.2.3/embed.js	Feste Version: ändert sich nie (Cache ein Jahr) und eignet sich für Subresource Integrity.

Einige Fragetypen (Matrix, Rangfolge, Datum, Bildauswahl) lädt embed.js erst bei Bedarf als kleine Zusatzdateien (embed-matrix.js usw.) aus demselben Verzeichnis nach – eine feste Version also immer die Dateien derselben Version, jeweils mit SRI-Prüfung. Eine Content-Security-Policy muss daher das ganze Verzeichnis des CDN erlauben, nicht nur embed.js.

Wer jede Änderung selbst freigeben möchte, bindet eine feste Version mit SRI-Hash ein. Die Hashes stehen in https://embed.pollyou.org/integrity.json:

<script
  src="https://embed.pollyou.org/v1.2.3/embed.js"
  integrity="sha384-…"
  crossorigin="anonymous"
  async
></script>

Popup per JavaScript

Nach dem Laden steht window.PollYou zur Verfügung:

// Umfrage als Dialog öffnen (z. B. nach einem Klick); ein eingebundenes Overlay der
// Umfrage öffnet sich an Ort und Stelle, sonst entsteht ein neues Popup
PollYou.open('AbC123xyz0')
PollYou.open({ surveyId: 'AbC123xyz0', mode: 'slider', hidden: { quelle: 'newsletter' } })

// In ein vorhandenes Element rendern
PollYou.open({ surveyId: 'AbC123xyz0', target: '#feedback' })

// Schließen: alle, eine Umfrage oder ein Element
PollYou.close()

// Ereignisse aller Umfragen der Seite
PollYou.on('complete', (detail) => console.log('Beantwortet', detail.surveyId))

Aufrufe vor dem Laden des Scripts lassen sich vormerken:

<script>
  window.PollYou = window.PollYou || { q: [] }
  window.PollYou.q.push(['on', 'complete', (detail) => console.log(detail)])
</script>

Ereignisse

Jede Umfrage löst DOM-Ereignisse aus, die bis zum document aufsteigen:

Ereignis	Wann	event.detail
pollyou:ready	Umfrage geladen	surveyId, type, status, resumed (fortgesetzt)
pollyou:start	erste Antwort (nicht beim Fortsetzen)	surveyId
pollyou:answer	jede Antwortänderung	surveyId, questionKey, answer
pollyou:complete	Antwort abgeschickt	surveyId, responseId, results
pollyou:shown	Overlay erscheint	surveyId, mode, trigger
pollyou:close	Overlay geschlossen	surveyId, mode
pollyou:error	Laden oder Absenden fehlgeschlagen	surveyId, phase, status

document.addEventListener('pollyou:complete', (event) => {
  console.log(event.detail.results)
})

Aussehen anpassen

Farben, Schrift und Rundungen kommen aus dem Theme der Umfrage (Dashboard → Themes), inklusive Dark Mode. Für Feinheiten lassen sich einzelne Bereiche per ::part() gestalten:

pollyou-survey::part(button-primary) {
  text-transform: uppercase;
}
pollyou-survey::part(container) {
  box-shadow: 0 8px 24px rgb(0 0 0 / 0.12);
}

Verfügbare Bereiche (Auswahl): container, title, question, question-title, option, option-selected, button, button-primary, button-secondary, progress, results, result-bar, result-fill, message, error. Die vollständige Liste steht in der README von @pollyou/embed-core.

Verhalten

• Umfrage (mehrere Seiten): Fortschrittsanzeige, Zurück/Weiter; jede Seite wird beim Weiterblättern zwischengespeichert.
• Fortsetzen: Wer eine Umfrage nach dem Weiterblättern verlässt (Neuladen, Tab geschlossen), landet im selben Browser wieder auf der Seite nach der zuletzt gespeicherten – mit den bisherigen Antworten und dem Hinweis „Willkommen zurück! Ihre bisherigen Antworten wurden wiederhergestellt.“ Das geht, solange die Antwort offen ist (Standard 24 Stunden nach dem Start, siehe Abbrüche), und nur mit derselben Version der Umfrage; nach einer neuen Veröffentlichung beginnt die Umfrage von vorn. Antworten der aktuellen, noch nicht gespeicherten Seite gehen dabei verloren.
• Abstimmung (Poll): eine Ansicht, nach dem Abstimmen erscheinen sofort die Ergebnisse als Balken mit Prozentwerten – sofern die Umfrage Ergebnisse zeigt.
• Bereits teilgenommen: Verhindert die Umfrage Mehrfachteilnahmen, sehen Wiederkehrende einen Hinweis und gegebenenfalls die Ergebnisse (siehe Dedup-Strategien).
• Nicht teilnahmeberechtigt: Lehnt der Server die Teilnahme ab, erscheint statt der Fragen ein Hinweis: „Diese Umfrage ist auf dieser Website nicht verfügbar“ (Domain nicht in den erlaubten Origins), „Bitte melden Sie sich an …“ (fehlendes oder ungültiges Identitäts-Token), „Die Sicherheitsprüfung ist fehlgeschlagen“ (Captcha, mit „Erneut versuchen“). Bei Umfragen mit Identitätspflicht ohne data-identity-token erscheint der Hinweis sofort, nicht erst nach der ersten Antwort.
• Captcha: Bei Umfragen mit Captcha löst das Embed während der ersten Antwort unbemerkt eine kleine Rechenaufgabe (ALTCHA, WebCrypto, ohne Worker – auch unter strenger CSP). Nötig ist ein sicherer Kontext (HTTPS oder localhost).
• Einstellungen der Embed-Konfiguration: Sprache, Farbschema und showResults einer Embed-Konfiguration haben Vorrang vor den data-*-Attributen.
• Geplant oder beendet: Statt der Fragen erscheint ein Hinweis (mit Startdatum bzw. den Ergebnissen).
• Offline: Antworten werden zwischengespeichert und automatisch gesendet, sobald die Verbindung wieder steht.
• Weiterleitung: Ist in der Umfrage eine Weiterleitungs-URL hinterlegt, folgt sie drei Sekunden nach dem Absenden (mit Link zum sofortigen Weiter).

Barrierefreiheit

Die Umfrage erfüllt WCAG 2.2 AA: vollständig per Tastatur bedienbar (Pfeiltasten in Auswahllisten, Enter zum Absenden), sichtbarer Fokus, Fehlermeldungen an den Fragen, Ansagen für Screenreader bei Seitenwechsel und Ergebnissen. Die Texte der Oberfläche gibt es auf Deutsch und Englisch, Sprachen mit Schreibrichtung von rechts nach links werden gespiegelt dargestellt.

Datenschutz

Das Script setzt keine Cookies – mit einer Ausnahme: Ist bei Overlays der Browser-Speicher gesperrt, merkt es sich Schließen, Teilnahme und Seitenaufrufe ersatzweise in einem Cookie der eigenen Website. Overlays speichern pollyou:overlay:<id> (Zeitpunkt des Schließens bzw. der Teilnahme) und pollyou:views:<id> (Zahl der Seitenaufrufe). Was es im Browser speichert, hängt von der Dedup-Strategie der Umfrage ab: bei device und ip_hash merkt es sich nach dem Absenden im lokalen Speicher, dass die Umfrage beantwortet wurde (pollyou:done:<id>), bei session nur im Sitzungsspeicher bis zum Schließen des Tabs, bei none und identity gar nicht. Nur bei device legt es zusätzlich eine zufällige Geräte-Kennung an (pollyou:device, siehe Hinweis zu TTDSG/ePrivacy). Noch nicht gesendete Antworten liegen bis zum Schließen des Tabs im Sitzungsspeicher. Bei Umfragen mit mehreren Seiten merkt sich das Script ab der ersten Antwort die offene Antwort (pollyou:resume:<id>: Antwort-ID, Sitzungs-Token, Ablaufzeit, Version – keine Antwortinhalte), um sie nach einem Neuladen fortzusetzen; der Eintrag wird beim Absenden oder Ablauf gelöscht. Bei Umfragen mit Identitäts-Token setzt nur dieselbe Person (sub) fort. Mit einer Antwort werden die Adresse der einbettenden Seite (ohne Parameter) und vorhandene utm_*-Parameter gespeichert. Für Statistiken (Aufrufe, Abbrüche) sendet das Script Ereignisse ohne personenbezogene Daten.