1. WAS DIESES MODUL LEISTET - UND WARUM

Die Suche ist im Onlineshop der schnellste Weg zum Kauf - Besucher, die suchen, wissen meist schon, was sie wollen, und kaufen deutlich häufiger. Doofinder liefert genau dafür eine schnelle, fehlertolerante Suche mit Vorschlägen schon beim Tippen. Damit diese Suche verkauft, braucht sie aber eines: aktuelle, vollständige Produktdaten.

Genau das ist die Aufgabe unseres Moduls. Das Modul übergibt Ihren kompletten Gambio-Katalog an Doofinder - mit Titeln, Beschreibungen, Bildern, Preisen, Marken, Kategoriepfaden, Varianten und Beständen - und hält den Suchindex automatisch aktuell. Sie müssen nichts von Hand exportieren und keine Daten doppelt pflegen.

Dieses Handbuch erklärt nicht nur, welchen Knopf Sie drücken, sondern auch, WARUM ein Schritt nötig ist und was er bewirkt. So verstehen Sie das Zusammenspiel von Shop und Suche und können es gezielt auf Ihren Shop einstellen.

2. FEED ODER API: DIE ZWEI WEGE ZUR SUCHE

M0152 kann Doofinder auf zwei Wegen mit Daten versorgen. Beide lassen sich einzeln oder gemeinsam nutzen.

Der Produkt-Feed ist der klassische, robuste Grundweg: Das Modul stellt eine Adresse bereit, die Ihren Katalog als Google-Shopping-XML ausgibt. Doofinder liest diese Adresse in einem selbst gewählten Rhythmus ein. Einmal eingerichtet, läuft das ohne weiteres Zutun - und reicht für viele Shops bereits vollständig aus.

Die Echtzeit-API ist der Weg für maximale Aktualität: Das Modul spricht die Doofinder-Management-API direkt an und aktualisiert einzelne Produkte oder den ganzen Index gezielt - beim Speichern eines Artikels in Sekunden, per Cronjob im festen Takt oder manuell auf Knopfdruck.

Als Faustregel gilt: Der Feed ist die Basis, die API die Kür. Wer selten Änderungen hat, kommt mit dem Feed aus; wer Preise und Bestände häufig ändert und möchte, dass die Suche das sofort widerspiegelt, aktiviert zusätzlich die API.

3. SCHNELLSTART: IN WENIGEN SCHRITTEN VERBUNDEN

Sie erreichen die Arbeitsseite des Moduls im Gambio-Admin über das Xycons-Menü unter dem Eintrag "Doofinder" (Seite "Doofinder Synchronisation"). Das Setup mit allen Konfigurationswerten öffnen Sie über das Modul-Center.

• Modul einschalten. Im Setup den Modulstatus auf "Eingeschaltet" stellen. Solange das Modul aus ist, laufen bewusst KEINE Prozesse - weder Feed noch API noch Cronjob (siehe Kapitel 8).
• Feed aktivieren und Token setzen. "Doofinder-Feed aktiv" einschalten und beim "Doofinder Feed Token" einen langen, geheimen Token hinterlegen. Damit ist Ihr Feed unter /doofinder_feed.php?token=IHR_TOKEN&lang=de erreichbar.
• Feed in Doofinder eintragen. In Doofinder eine Datenquelle vom Typ Google-Shopping/XML anlegen und die Feed-Adresse hinterlegen (siehe Kapitel 4).
• Optional: Echtzeit-API aktivieren. API-Trigger einschalten, API-Key, Zone und Indexnamen eintragen und je Shopsprache die Doofinder-HashID zuordnen (siehe Kapitel 5).

Mehr ist für den Start nicht nötig. Die ausgelieferten Standardwerte sind für die meisten Shops direkt sinnvoll.

4. DER PRODUKT-FEED IM DETAIL

Der Feed gibt Ihren Katalog im Google-Shopping-XML-Format aus - einem bewährten Standard, den Doofinder direkt einlesen kann. Die Adresse lautet:

/doofinder_feed.php?token=<IHR_FEED_TOKEN>&lang=de

Der Parameter lang wählt die Sprache, in der Titel, Beschreibungen, Preise und Links ausgegeben werden. Zum Testen helfen zwei weitere Parameter: limit (nur die ersten N Einträge) und offset (ab dem N-ten Eintrag). Rufen Sie die Adresse einmal im Browser auf - Sie sollten sauberes XML sehen.

Warum der Token wichtig ist: Der Feed enthält Ihren kompletten Katalog inklusive Preise und Bestände. Der Token ist der Schlüssel, der diesen Export schützt. Verwenden Sie deshalb einen langen, zufälligen Wert (mindestens 32 Zeichen) und geben Sie die Adresse nur an Doofinder weiter. Wird der Token falsch oder gar nicht übergeben, antwortet der Endpunkt mit "Unauthorized".

In Doofinder richten Sie für die jeweilige Sprache eine Google-Shopping-/XML-Datenquelle ein und aktivieren die Variantengruppierung (die Felder für Gruppierung liefert der Feed bereits mit - siehe Kapitel 6). Danach steuert Doofinder den Einlese-Rhythmus.

5. DIE ECHTZEIT-SYNCHRONISATION ÜBER DIE API

Die API-Synchronisation aktualisiert den Doofinder-Index direkt - ohne den Umweg über den Feed-Einlese-Rhythmus. So funktioniert ein Vollsync technisch: Das Modul legt in Doofinder einen temporären Index an, füllt ihn in Blöcken zu je 100 Einträgen und schaltet ihn erst am Ende live ("replace by temp"). Dadurch ist die Suche während des Abgleichs nie unvollständig - es gibt keinen Moment, in dem der Kunde eine halb gefüllte Suche sieht.

Voraussetzung für alle API-Funktionen: Der Modulstatus und der API-Trigger sind eingeschaltet, und es sind API-Key, Zone, Indexname sowie mindestens eine aktive Sprach-Hash-Zuordnung hinterlegt.

5.1 DIE SPRACH-HASH-ZUORDNUNG

Jede Shopsprache hat in Doofinder ihre eigene Search Engine mit einer eigenen HashID. Deshalb ordnen Sie auf der Seite "Doofinder Synchronisation" jeder Sprache ihre HashID zu: Häkchen bei "Aktiv" setzen, die HashID eintragen, speichern. Nur aktive Sprachen mit hinterlegter HashID werden synchronisiert.

Das ist der Grund, warum die Zuordnung wichtig ist: Ohne sie weiß das Modul nicht, in welche Doofinder-Suche die deutschen, englischen oder französischen Produktdaten gehören. Der manuelle Sofort-Sync bleibt daher so lange gesperrt, bis API-Key UND mindestens eine aktive Zuordnung vorhanden sind.

5.2 MANUELLER SOFORT-SYNC

Auf der Seite "Doofinder Synchronisation" startet der Knopf "Jetzt synchronisieren" einen kompletten Abgleich - denselben Prozess, den auch der Cronjob nutzt. Ein Fortschrittsbalken zeigt live, wie viele Produkte verarbeitet wurden, wie viele Dokumente an Doofinder gingen und wie viele Bulk-Requests nötig waren. Der Lauf erfolgt schrittweise (in Paketen von je zehn Produkten je Sprache), damit auch große Kataloge ohne Zeitüberschreitung durchlaufen. Am Ende erscheint ein Ausführungsprotokoll mit Ergebnis oder - im Fehlerfall - der genauen Meldung von Doofinder.

5.3 CRONJOB-VOLLSYNC

Für den regelmäßigen, unbeaufsichtigten Komplettabgleich aktivieren Sie in der Gambio-Cronjob-Verwaltung den Cronjob "M0152Doofinder" und wählen ein Intervall (stündlich, alle 3/6/12 Stunden oder täglich; Standard ist täglich um 02:15 Uhr). Der Cronjob nutzt exakt denselben Vollsync wie der manuelle Knopf. Ist das Modul oder der API-Trigger ausgeschaltet oder fehlt eine aktive Sprach-Zuordnung, beendet sich der Lauf folgenlos und protokolliert den Grund.

5.4 AUTOMATISCHER SYNC BEIM SPEICHERN UND LÖSCHEN

Das ist der Weg zur echten Sekundenaktualität: Bei aktiven Optionen "Produktsync bei Speicherung" und "Produktsync bei Löschung" aktualisiert das Modul genau den betroffenen Artikel in Doofinder, sobald Sie ihn im Backend speichern oder löschen - ohne den ganzen Index neu aufzubauen. So spiegelt die Suche Preis-, Text- und Bestandsänderungen praktisch sofort wider.

Schlägt ein solcher automatischer Abgleich einmal fehl (etwa weil Doofinder gerade nicht erreichbar ist), wird das Speichern oder Löschen des Produkts dadurch NICHT behindert; der Fehler wird lediglich protokolliert (siehe Kapitel 9.4). Der nächste Vollsync bringt den Index anschließend wieder auf Stand.

5.5 REPROCESS- UND SYNC-ENDPUNKTE

Für Automatisierungen von außen gibt es zwei optionale, token-geschützte Endpunkte: doofinder_api_sync.php stößt einen API-Vollsync (oder gezielt einzelne Produkte) an, doofinder_reprocess.php löst in Doofinder die Neuverarbeitung des Index aus. Beide arbeiten über die in 5.1 gepflegte Sprach-Hash-Zuordnung; ein optionaler Parameter lang begrenzt die Aktion auf eine Sprache. Der Reprocess-Endpunkt hat eine einstellbare Sperrzeit (Cooldown), damit er nicht zu häufig ausgelöst wird. Für den normalen Betrieb sind diese Endpunkte nicht nötig - Feed, Cronjob und automatischer Produkt-Sync decken den Alltag ab.

6. WAS EXPORTIERT WIRD (DATENFELDER UND VARIANTEN)

M0152 überträgt alle verkaufsrelevanten Produktdaten: Produkttitel, Beschreibung, Link zur Produktseite, Bild, Preis (in der Währung und für die Gast-Kundengruppe des Shops), Verfügbarkeit, Marke, EAN/GTIN, Artikelnummer (SKU/MPN), die vollständigen Kategoriepfade, Keywords, Lagerbestand und das Datum der letzten Änderung.

Die Verfügbarkeit ergibt sich automatisch aus dem Bestand ("auf Lager" / "nicht auf Lager"). Über die Option "Nicht lieferbare Artikel exportieren" entscheiden Sie, ob Artikel und Varianten mit Bestand null überhaupt in Feed und Sync auftauchen.

Varianten werden korrekt abgebildet: Sowohl Eigenschafts-Kombinationen als auch klassische Artikelattribute erscheinen als jeweils eigener Eintrag und werden über eine gemeinsame Gruppen-ID zusammengefasst (ein Eintrag je Gruppe ist der "Gruppenführer"). So erkennt Doofinder zusammengehörige Varianten als ein Produkt mit Auswahl - statt als lauter Dubletten. Jede Variante trägt ihre eigene Artikelnummer, ihren eigenen Preis und ihre Merkmale (z. B. Farbe, Größe).

7. DAS MODUL-SETUP: ALLE KONFIGURATIONSWERTE IM DETAIL

Das Setup erreichen Sie im Gambio-Admin über das Modul-Center: den Eintrag "M0152 - Doofinder" öffnen und auf "Einstellungen" gehen. Jeder Wert trägt dort einen kurzen Infotext; dieses Kapitel ordnet die Werte ein und nennt jeweils den Auslieferungsstandard in (Klammern). Die Ja/Nein-Schalter werden im Setup als lesbare Auswahl angezeigt, nicht als "true/false".

7.1 GRUNDSCHALTER

Modulstatus (Standard: Ja) Der Hauptschalter. Steht er auf Nein, sind alle Prozesse stillgelegt - Feed, API-Synchronisation, Cronjob und der automatische Produkt-Sync. Die Backend-Seite zeigt in diesem Fall einen deutlichen roten Hinweis, dass das Modul ausgeschaltet ist, damit sofort klar ist, warum nichts synchronisiert wird.

Lizenzschlüssel Wird beim Kauf hinterlegt und schaltet das Modul vom Testbetrieb auf den uneingeschränkten Betrieb frei.

7.2 PRODUKT-FEED

Doofinder-Feed aktiv (Standard: Ja) Stellt den Feed-Endpunkt bereit. Steht er auf Nein, antwortet die Feed-Adresse mit einer Deaktiviert-Meldung - nützlich, wenn Sie ausschließlich über die API arbeiten.

Doofinder Feed Token (Standard: leer) Der geheime Pflicht-Token für den Feed-Aufruf. Ohne Token ist der Feed gesperrt. Wählen Sie einen langen, zufälligen Wert (siehe Kapitel 4).

Nicht lieferbare Artikel exportieren (Standard: Nein) Legt fest, ob Artikel und Varianten mit Bestand null in Feed und Sync aufgenommen werden. Standardmäßig bleiben ausverkaufte Artikel außen vor.

7.3 API-SYNCHRONISATION

Doofinder API-Trigger aktiv (Standard: Nein) Der Hauptschalter für die direkte API-Synchronisation. Erst wenn er auf Ja steht, arbeiten manueller Sync, Cronjob, automatischer Produkt-Sync und die Endpunkte.

Doofinder API Key (Standard: leer) Der Management-API-Key aus Ihrem Doofinder-Konto. Er wird für alle schreibenden API-Zugriffe benötigt.

Doofinder Zone (Standard: eu1) Die Region Ihres Doofinder-Kontos, z. B. eu1, us1 oder eu2. Sie ergibt sich aus Ihrer Doofinder-Umgebung.

Doofinder API Indexname (Standard: products) Der Name des Zielindex in Doofinder, in den synchronisiert wird.

Doofinder Sprach-Zuordnung Die Zuordnung von Shopsprache zu Doofinder-HashID. Sie wird nicht als einzelnes Feld, sondern komfortabel über die Tabelle auf der Seite "Doofinder Synchronisation" gepflegt (siehe Kapitel 5.1).

7.4 PRODUKT-SYNC UND TRIGGER

Produktsync bei Speicherung (Standard: Ja) Synchronisiert den betroffenen Artikel direkt über die API, sobald er im Backend gespeichert wird.

Produktsync bei Löschung (Standard: Ja) Entfernt den betroffenen Artikel direkt aus Doofinder, sobald er im Backend gelöscht wird.

Reprocess Endpoint Token (Standard: leer) Der geheime Pflicht-Token für die Endpunkte doofinder_reprocess.php und doofinder_api_sync.php. Ohne Token sind beide gesperrt.

Reprocess Cooldown (Sekunden) (Standard: 300) Die Mindestzeit zwischen zwei Reprocess-Auslösungen. Sie verhindert, dass ein zu häufig aufgerufener Trigger Doofinder unnötig belastet.

8. HÄUFIGE STOLPERSTEINE

• Modul aus = alles aus. Bei ausgeschaltetem Modulstatus passiert bewusst nichts - kein Feed, keine API, kein Cronjob. Die Backend-Seite weist mit einem roten Hinweis darauf hin. Wer sich wundert, dass nichts synchronisiert, prüft zuerst diesen Schalter.

• Feed liefert "Unauthorized". Der Token in der Adresse stimmt nicht mit dem im Setup hinterlegten Feed-Token überein - Werte ohne Leerzeichen vergleichen.

• "Jetzt synchronisieren" ist gesperrt. Es fehlen der API-Key und/oder eine aktive Sprach-Zuordnung mit HashID. Beides hinterlegen, dann ist der Knopf verfügbar.

• Falsche Sprache im Index. Jede Sprache braucht ihre eigene HashID. Prüfen Sie, ob die richtige HashID der richtigen Sprache zugeordnet ist.

• Sync bricht mit Doofinder-Meldung ab. Zone, API-Key, HashID und Indexname prüfen. Das Ausführungsprotokoll bzw. das Sync-Log zeigt die genaue Meldung von Doofinder.

• Feed enthält Preise. Der Feed gibt den kompletten Katalog inklusive Preise aus. Nur mit starkem Token betreiben und die Adresse ausschließlich an Doofinder weitergeben.