Dynamische Bildintegration über GraphQL in der Personalisierung

Das Add-on „Bildanbindung über GraphQL“ (technischer Name: GraphQLImageForPersonalization) ermöglicht es, Bilder aus einem externen System automatisiert in ein Bildfeld einer personalisierten Druckvorlage einzubinden. Die Bildauswahl erfolgt dabei dynamisch auf Basis eines benutzerspezifischen Suchparameters (z. B. einer E-Mail-Adresse). Die technische Anbindung erfolgt über eine standardisierte GraphQL-Schnittstelle.

Somit können Bildinhalte wie Mitarbeiterfotos, QR-Codes oder produktspezifische Abbildungen automatisch geladen und in Echtzeit während der Personalisierung angezeigt werden – ohne manuelles Hochladen durch den Nutzer.

Konfigurationsfelder im Überblick

Die Einrichtung erfolgt über die Feldspezialoptionen (FSO) des entsprechenden Bildfeldes in der Druckvorlage:

Feld	Beschreibung	Beispielwert

Feld	Beschreibung	Beispielwert
Funktion aktiviert	Aktiviert die Nutzung des Add-ons für dieses Bildfeld.	✔️
Suchparameter	Variable, die zur Bildsuche verwendet wird. Zugriff per Smarty auf Personalisierungsdaten möglich.	`{$personalizationData['email']}`
Site-ID	Identifikator der Zielinstanz im angebundenen System (optional).	`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
Endpoint	Vollständige URL des GraphQL-Endpunkts des externen Bilddienstes.	`https://example-graphql-server.com/graphql`
Operation Name	Bezeichnung der durchzuführenden GraphQL-Operation.	`getOriginal`
Smarty-Ausdruck für Bildpfad	Pfad zur Bild-URL in der Response, angegeben als gültiger Smarty-Ausdruck.	`{$response.data.content.facetedAssetSearch.result[0].originalStableUrl}`

Testfunktion in der Konfiguration

Zur Verifizierung kann im Administrationsbereich die Schaltfläche „Konfiguration testen“ genutzt werden. Nach manueller Eingabe eines Suchparameters (z. B. einer Test-E-Mail-Adresse) wird im Modal-Fenster der Antwortinhalt des externen Dienstes angezeigt. So kann überprüft werden, ob die Verbindung korrekt funktioniert und ob ein gültiger Bildpfad ermittelt werden kann.

Personalisierung des Artikels

Während der Artikelpersonalisierung im Shop wird der konfigurierte Suchparameter (z. B. email) automatisch an die GraphQL-Schnittstelle übergeben, um ein passendes Bild zu laden.

Zusätzlich können weitere Feldspezialoptionen (FSO) unabhängig vom Add-on aktiviert werden, um das Verhalten des entsprechenden Eingabefeldes im Shop zu steuern:

Option	Beschreibung

Option	Beschreibung
Feld verbergen	Das Eingabefeld für den genutzten Parameter wird im Shop nicht angezeigt. Der Wert wird dennoch intern verwendet.
Feld sperren	Das Eingabefeld ist sichtbar, aber nicht editierbar. Der Wert kann nicht verändert werden.
Standardwert definieren	Ein definierter Wert wird vorbelegt und automatisch für die Bildabfrage verwendet, falls kein anderer vorliegt.

Diese Optionen sind nicht Teil des Add-ons, lassen sich jedoch problemlos in Kombination mit der Bildanbindung verwenden, um das Verhalten im Shop gezielt zu steuern.

Anwendungsszenarien

Beispiel 1: Automatisiertes Mitarbeiterfoto

Der Nutzer personalisiert eine Visitenkarte.
Die E-Mail-Adresse wird im Hintergrund zur Bildabfrage verwendet.
Das dazugehörige Portraitbild wird automatisch eingefügt.

Beispiel 2: QR-Code-Integration

Eine eindeutige Produktkennung (z. B. Artikelnummer) wird übergeben.
Die Kennung wird an einen externen QR-Code-Service übergeben.
Der zurückgelieferte QR-Code wird direkt im Etikett angezeigt.

Technische Hinweise

Die Kommunikation erfolgt sicher über HTTPS gemäß GraphQL-Standard.
Änderungen an der Antwortstruktur des externen Dienstes können Auswirkungen auf den Bildpfad-Ausdruck haben. Die Konfiguration sollte daher regelmäßig geprüft werden.
Bei Störungen oder fehlenden Bildern sollte zuerst der externe Dienst auf Erreichbarkeit und Antwortformat geprüft werden.