Embed-Konfigurationen

Eine Embed-Konfiguration legt fest, wo und wie eine Umfrage eingebettet werden darf. Jede Umfrage kann beliebig viele haben, z. B. eine für den Shop und eine für die Mitglieder-App. Die ID der Konfiguration wird beim Einbetten angegeben:

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

Einstellung	Bedeutung
Name	Nur zur Orientierung im Dashboard.
Erlaubte Origins	Websites, auf denen die Umfrage laufen darf. Leer = überall erlaubt (das Dashboard zeigt dann einen Warnhinweis).
Modus	inline, popup, slider, fullpage oder iframe – die Darstellung. Ohne data-mode am Snippet gilt sie direkt.
Auslöser/Häufigkeit	Nur für popup, slider, fullpage: wann sich das Overlay von selbst öffnet und wie oft, siehe Popup, Slider und Ganzseite.
Overrides	Sprache (locale), Farbschema (theme: auto/light/dark) und showResults: false; sie haben Vorrang vor den Attributen der Seite.
Signierte Identität	Antworten nur mit gültigem Identitäts-Token annehmen.

Erlaubte Origins

Eine Origin ist Schema + Host (+ Port), ohne Pfad:

Eintrag	erlaubt
https://shop.example.com	genau diese Origin
https://*.example.com	alle Subdomains (www.example.com, a.b.example.com), nicht example.com selbst
http://localhost:3000	lokale Entwicklung (der Port muss passen)

Die Liste wirkt an zwei Stellen:

1. Collector-API (CORS): Anfragen von anderen Origins werden mit 403 {code: "origin_not_allowed"} abgelehnt und erhalten keine CORS-Header. Das gilt auch für Folgeanfragen einer Antwort (Zwischenspeichern, Abschluss, Ereignisse) – sie gehören zur Konfiguration, mit der die Sitzung begonnen wurde.
2. iframe-Seite: Der Header Content-Security-Policy: frame-ancestors … verhindert, dass fremde Seiten die iframe-Seite einbinden.

Ohne Embed-ID gilt: Hat die Umfrage Konfigurationen und sind alle eingeschränkt, ist die Umfrage auf die Vereinigung ihrer Origins beschränkt – eine fremde Seite kann die Einschränkung also nicht durch Weglassen der ID umgehen. Gibt es keine Konfiguration oder mindestens eine ohne Einschränkung, ist die Umfrage überall einbettbar. Eine unbekannte oder gelöschte Embed-ID zählt wie „keine ID“, damit bestehende Einbettungen nicht mit einem Fehler enden.

Immer erlaubt sind PollYou selbst (iframe-Seite, Direktlink, Dashboard) und Anfragen ohne Origin-Header (Server-zu-Server, Kanal api). Eine Origin-Prüfung schützt vor fremden Websites im Browser, nicht vor Skripten – dagegen helfen Dedup und Missbrauchsschutz.

API

Organisationsbezogen (Header X-Organization-Id), Lesen mit surveys.view, Ändern mit surveys.edit:

Endpunkt	Ergebnis
GET /api/surveys/{id}/embeds	{member: [EmbedConfig]}, älteste zuerst
POST /api/surveys/{id}/embeds	{name, allowedOrigins?, mode?, overrides?, overlay?, requireSignedIdentity?} → 201 EmbedConfig; 422 z. B. allowedOrigins[1], overlay.delaySeconds
GET /api/embeds/{id}	EmbedConfig
PATCH /api/embeds/{id}	Teiländerung; allowedOrigins, overrides und overlay werden als Ganzes ersetzt (overlay: null = Standardwerte)
DELETE /api/embeds/{id}	204

{
  "id": "0192f0c4-…",
  "surveyId": "0192f0a1-…",
  "name": "Shop",
  "allowedOrigins": ["https://shop.example.com", "https://*.example.org"],
  "mode": "inline",
  "overrides": { "locale": null, "theme": "dark", "showResults": false },
  "overlay": {
    "trigger": "manual",
    "delaySeconds": 5,
    "scrollPercent": 50,
    "pageViews": 2,
    "frequency": "cooldown",
    "cooldownDays": 7,
    "position": "bottom_right"
  },
  "requireSignedIdentity": false,
  "createdAt": "2026-10-10T12:00:00+00:00",
  "updatedAt": "2026-10-10T12:00:00+00:00"
}

Anlegen, Ändern und Löschen stehen im Audit-Log (embed_config.created, embed_config.updated, embed_config.deleted).

Mit ?embed=<id> liefert GET /api/collect/surveys/{publicId} zusätzlich embed: {id, mode, overrides, requireSignedIdentity, overlay} (overlay immer vollständig mit Standardwerten); bei showResults: false bleiben die Ergebnisse auch serverseitig aus.