Wissen · Technik & Integration

Pre-Authenticated Embed: Nutzer aus
Ihrem Portal automatisch anmelden

Technische Dokumentation · Stand: August 2026 · Fragen zur Integration: hello@convert-app.com

Worum es geht

Wenn Ihr Portal seine Besucher bereits kennt, müssen die sich am eingebetteten Tippspiel (im Folgenden „Predictor") nicht noch einmal anmelden. Stattdessen hängt Ihr Portal ein paar URL-Parameter an die iFrame-Adresse – und der Nutzer ist im Predictor automatisch eingeloggt, ohne Login-Maske und ohne Registrierungsformular. Optional lässt sich sein Profil gleich mit vorbefüllen. Diese Seite dokumentiert die Parameter, die optionale HMAC-Signatur (sie stellt sicher, dass der Link wirklich von Ihrem Portal stammt und unterwegs nicht verändert wurde) sowie das Verhalten im Detail.

Ein Custom Field ist dabei ein zusätzliches Registrierungsfeld Ihres Accounts, etwa Lieblingsverein oder Land. Jedes Custom Field hat eine numerische ID – zu finden im Creator unter „User registration", im Options-Menü des jeweiligen Feldes als „ID: <Nummer>".

Voraussetzungen

• Für den Account ist eine Embed-iFrame-URL konfiguriert (Creator, unter User registration / Embed-Einstellungen).
• Pre-Authenticated Embedding ist für den Account aktiviert.
• Optional ist ein Pre-Auth-Secret konfiguriert. Mit Secret muss jeder Link HMAC-signiert sein und ist 60 Sekunden gültig. Ohne Secret wird dem useridentifier so vertraut, wie er gesendet wird – keine Signatur nötig.

Query-Parameter

Unterstützte Custom-Field-Typen

usercustomfield_<ID> darf nur folgende Feldtypen ansprechen:

• Kurztext-, Langtext-, Zahl- und Telefonfelder speichern den rohen URL-Wert.
• Länderfelder erwarten einen englischen Ländernamen (z. B. Germany), der vor dem Speichern auf den ISO-Code gemappt wird (z. B. DE).

Options-basierte Felder (Dropdown, Radio-Buttons, Checkbox), Adressfelder und Rich-Text-Inhaltsblöcke werden abgelehnt, weil das einbettende Portal die internen Options-IDs dieser Felder nicht kennt.

HMAC-Signatur-Payload

Wenn ein Secret konfiguriert ist, berechnen Sie hash = HMAC_SHA256(secret, payload). Der Payload ist ein nur aus Werten bestehender, mit Doppelpunkten verbundener String in genau dieser Reihenfolge:

useridentifier : userfirstname : userlastname : usernickname : <Custom-Field-Werte, aufsteigend nach Feld-ID> : ts

Es gelten folgende Regeln:

• Wird ein optionaler Parameter nicht gesendet, entfällt sein Platz im Payload ersatzlos – verbunden werden nur die tatsächlich vorhandenen Werte. Ohne Namen, Nickname und Custom Fields lautet der Payload also schlicht useridentifier:ts.
• Custom-Field-Werte kommen aufsteigend nach Feld-ID sortiert in den Payload – egal, in welcher Reihenfolge die Parameter in der URL stehen.
• Bei Länderfeldern wird der rohe englische Name signiert; das ISO-Mapping passiert erst serverseitig beim Speichern.
• ts ist immer das letzte Element.

Beispiele

Nur Identifier:

payload = "user@example.com:1716800000"

Identifier und nur Nachname (Vorname weggelassen):

payload = "user@example.com:Solo:1716800000"

Identifier, beide Namen, Nickname und zwei Custom Fields (IDs 9 und 14):

payload = "user@example.com:Ada:Lovelace:AcePredictor:FC Example:Germany:1716800000"
                                          ^Nickname    ^Feld 9     ^Feld 14

Signier-Beispiel (PHP)

$secret = '...';                 // das Pre-Auth-Secret des Accounts
$ts = time();
$customFields = [9 => 'FC Example', 14 => 'Germany']; // keyed by field ID
ksort($customFields, SORT_NUMERIC);

$parts = ['user@example.com', 'Ada', 'Lovelace', 'AcePredictor']; // drop names/nickname that are absent
foreach ($customFields as $v) { $parts[] = $v; }
$parts[] = (string) $ts;

$hash = hash_hmac('sha256', implode(':', $parts), $secret);
// iframe URL: ?useridentifier=user@example.com&userfirstname=Ada&userlastname=Lovelace&usernickname=AcePredictor
//             &usercustomfield_9=FC%20Example&usercustomfield_14=Germany&ts=<ts>&hash=<hash>

Verhalten

• Neuer Nutzer: wird automatisch angelegt, seine E-Mail-Adresse gilt als verifiziert, und er hat kein Passwort – daran erkennt das System pre-authentifizierte Nutzer. Ist usernickname übergeben, wird der Nickname direkt gesetzt; sonst fragt der Predictor danach. Vorname, Nachname und Custom-Field-Werte werden gespeichert.
• Bestehender pre-authentifizierter Nutzer: Vorname, Nachname, Nickname und Custom Fields werden bei jedem Aufruf aus dem Link neu übernommen – ändert sich ein Wert in Ihrem Portal, steht er beim nächsten Laden auch im Predictor. Das passiert auch, wenn der Nutzer schon eingeloggt ist; nur das überflüssige erneute Einloggen entfällt.
• Bestehender passwort-registrierter Nutzer: wird eingeloggt; Namen, Nickname und Custom Fields werden genauso aus dem Link übernommen. Ein Nutzer kann sich also zuerst regulär registrieren und später vom Portal pre-authentifiziert werden – beides verträgt sich.
• Nickname-Eindeutigkeit: Ein Nickname wird abgelehnt, wenn ihn bereits ein anderer Nutzer des Accounts trägt. Den eigenen, bereits gesetzten Nickname erneut zu senden, ist erlaubt und ändert nichts.

Portal-verwaltete Felder in der Predictor-Oberfläche

Sein Profil kann der Endnutzer an zwei Stellen im Predictor bearbeiten: im Kontoeinstellungen-Dialog (ein bestehender Nutzer öffnet seine Kontodetails) und im Profil-vervollständigen-Dialog, der pre-authentifizierten Nutzern beim ersten Laden erscheint, wenn noch ein Nickname fehlt, die AGB nicht akzeptiert sind oder Registrierungsfelder offen sind – im normalen Signup-Flow taucht er nie auf. Beide Dialoge sorgen auf unterschiedliche, sich ergänzende Weise dafür, dass Nutzer die vom Portal gelieferten Daten nicht verändern können.

Kontoeinstellungen-Dialog

Für pre-authentifizierte Nutzer richten sich die Regeln nach den Parametern der aktuellen iFrame-URL:

• E-Mail (useridentifier): immer portal-verwaltet. Wird deaktiviert angezeigt und serverseitig erzwungen – die Adresse kann im Predictor nicht geändert werden. Das Portal bleibt die einzige Quelle der Nutzeridentität.
• Vorname, Nachname, Nickname: werden nur dann deaktiviert angezeigt, wenn das Portal genau diesen Parameter auf der aktuellen iFrame-URL mitgesendet hat. Was das Portal nicht sendet, darf der Nutzer frei bearbeiten – und weil das Portal seine Werte bei jedem Laden neu anwendet, überschreibt jeder gesendete Wert eine lokale Änderung beim nächsten Aufruf von selbst. Namen und Nickname bleiben bewusst sichtbar (nur eben deaktiviert) statt versteckt: Es sind unkritische Identitätsdaten, die der Nutzer ruhig sehen soll.
• Custom Fields (usercustomfield_<ID>): werden vollständig versteckt, denn ein vom Portal geliefertes Custom Field kann sensible Daten enthalten – etwa eine interne Kundennummer. Maßgeblich sind die Custom-Field-IDs auf der aktuellen iFrame-URL.

Mit „aktueller iFrame-URL" ist der Query-String zum Zeitpunkt des iFrame-Ladens gemeint. Navigiert der Nutzer danach innerhalb des Predictors (wobei der Query-String verloren gehen kann), ändert das nichts daran, welche Felder in dieser Session als portal-verwaltet gelten.

Profil-vervollständigen-Dialog

Dieser Dialog erscheint nur bei pre-authentifizierten Nutzern – passwort-registrierte durchlaufen den normalen Signup. Seine Regel ist einfacher: Er zeigt nur, was noch fehlt. Der Nickname-Schritt entfällt, sobald ein Nickname existiert – egal ob per usernickname vorbefüllt oder regulär gewählt. Jedes Custom Field, das bereits einen nicht-leeren Wert oder eine gewählte Option hat, wird ausgeblendet, und die AGB-Checkbox verschwindet nach der Zustimmung.

Ein per usercustomfield_<ID> vorbefülltes Feld fällt damit automatisch aus dem Dialog heraus – eine eigene „portal-verwaltet"-Logik braucht es hier nicht, denn alles, was das Portal liefert, ist per Definition schon gefüllt. Übrig bleiben genau die Felder, die das Portal nicht geliefert hat; die kann der Nutzer ausfüllen und absenden.

Überschreiben portal-verwalteter Custom Fields wird abgelehnt

Custom-Field-Werte, die der Pre-Auth-Flow geschrieben hat, werden serverseitig als portal-verwaltet markiert. Versucht ein späteres Profil-Update aus einer Nutzer-Quelle (PUT /account/update aus den Kontoeinstellungen, PUT /me/profile aus dem Vervollständigen-Dialog), einen solchen Wert zu ändern, lehnt der Server den gesamten Request mit HTTP 400 und dem Fehlercode FORM_FIELD_PRE_AUTH_MANAGED auf formFieldSubmissions.<ID> ab – nichts wird stillschweigend verworfen. Im Normalbetrieb tritt dieser Fehler nicht auf, weil das Predictor-Frontend portal-verwaltete Werte gar nicht erst mitsendet; er zeigt sich nur bei manipulierten oder manuell gebauten Requests.

Ein Custom Field, das der Nutzer zuerst selbst befüllt hat, ist nicht portal-verwaltet. Liefert das Portal dasselbe Feld später auf einem frischen Link, wird der Wert überschrieben – und gilt ab diesem Moment als portal-verwaltet. Nutzerseitige Änderungen werden dann wie oben beschrieben abgelehnt.

Soll der Nutzer die Kontrolle über ein portal-verwaltetes Feld zurückbekommen, sendet das Portal usercustomfield_<ID> für dieses Feld auf neuen iFrame-URLs einfach nicht mehr mit. Wichtig: Der gespeicherte Wert bleibt trotzdem portal-verwaltet, bis das Portal ihn neu synchronisiert oder er anderweitig entfernt wird – die Markierung hängt am gespeicherten Wert und verschwindet nicht automatisch, nur weil der URL-Parameter fehlt.

Fehler-Antworten

Bei Ablehnung rendert der Predictor eine gebrandete Fehlerseite mit einem der folgenden Codes:

Häufige Fragen

Weiterlesen