Integrations- & Einrichtungsleitfaden

Dieses Dokument enthält detaillierte Anweisungen zur Einrichtung, Konfiguration und Fehlerbehebung der Hivebee Smart Search-Komponenten in einem Shopify-Shop. Die App wird über Shopify Theme App Extensions (App Embed Blocks) integriert, was bedeutet, dass für Standardeinrichtungen keine direkte Codebearbeitung erforderlich ist.

Voraussetzungen

Um diese Suchoberflächen zu installieren und zu aktivieren:

• Stellen Sie sicher, dass der Shop ein mit Shopify Online Store 2.0 kompatibles Theme verwendet (z. B. Dawn, Sense, Prestige, Impulse).
• Die Hivebee-App muss erfolgreich im Shopify-Händler-Admin-Panel installiert sein.
• Zugriff auf den Shopify Theme Editor (Onlineshop -> Themes -> Anpassen).

1. Einrichtung des Floating Widget

Überblick

Das Floating Widget ist ein interaktiver, KI-gesteuerter konversationeller Suchassistent, der in der Ecke des Shops schwebt. Wenn darauf geklickt wird, öffnet sich ein Chat-ähnliches Overlay, das es Kunden ermöglicht, Produkte mit natürlicher Sprache abzufragen.

• Mount-Punkt: Wird automatisch am DOM-Element #smart-search-floating-root eingebunden.
• Geladene Assets:
  • constants.js
  • smart-search.iife.js
  • product-tracker.js (zur Verfolgung von Benutzeranalysen)
  • tracker-config.js

Aktivierungsschritte

1. Navigieren Sie im Shopify-Admin zu Onlineshop -> Themes.
2. Klicken Sie neben dem aktiven Theme auf Anpassen, um den Theme-Editor zu öffnen.

3. Klicken Sie in der linken Seitenleiste auf die Registerkarte App-Einbettungen (App Embeds) (das dritte Symbol von oben).
4. Suchen Sie den Einbettungsblock mit dem Namen Hivebee Widget.
5. Schalten Sie den Schalter auf Aktiv (Ein).

6. Klicken Sie in der oberen rechten Ecke auf Speichern.

2. Einrichtung der Hivebee Header-Suchleiste

Überblick

Der Header Search Bar Interceptor klinkt sich in die vorhandenen Sucheingaben, Modale oder Slide-Outs des Themes ein. Wenn ein Kunde auf das native Suchsymbol klickt oder das native Suchfeld fokussiert, wird die Hivebee Smart Search-Schnittstelle anstelle des Standard-Suchlayouts des Themes gerendert.

• Mount-Punkt: Wird am DOM-Element #smart-search-header-search-root eingebunden.
• Geladene Assets:
  • override.js (Override-Engine)

Aktivierungsschritte

1. Navigieren Sie im Shopify-Admin zu Onlineshop -> Themes.
2. Klicken Sie neben dem aktiven Theme auf Anpassen, um den Theme-Editor zu öffnen.

3. Klicken Sie in der linken Seitenleiste auf die Registerkarte App-Einbettungen (App Embeds) (das dritte Symbol von oben).
4. Suchen Sie den Einbettungsblock mit dem Namen AI Search (Header).
5. Schalten Sie den Schalter auf Aktiv (Ein).

6. Klicken Sie in der oberen rechten Ecke auf Speichern.

Wie die Override-Engine funktioniert

Das Override-Skript (override.js) fängt die standardmäßigen Suchsteuerungen ab. Wenn es ausgelöst wird:

• Es fügt benutzerdefinierte Webkomponenten (<smart-search-override> und <smart-search-interceptor>) direkt vor den nativen Such-Wrappern des Themes ein.
• Es blendet den Standard-Such-Wrapper aus, indem es CSS visibility: hidden; pointer-events: none; verwendet.
• Es fängt Benutzerinteraktionen (Klicks, Tastaturfokus, Formulareinreichungen) an den nativen Suchelementen ab und löst stattdessen benutzerdefinierte Suchmodal-Ereignisse aus.

Schritt 1: Automatische Erkennung

Standardmäßig kennt Hivebee die CSS-Selektoren für die meisten beliebten Shopify-Themes, einschließlich:

• Kostenlose Shopify-Themes: Dawn, Sense, Refresh, Craft, Studio, Origin, Cascade, Ride, Publisher, Trade.
• Ältere kostenlose Themes: Debut, Minimal, Brooklyn, Boundless, Narrative, Simple, Venture, Supply, Express.
• Beliebte Premium-Themes: Turbo, Impulse, Prestige, Focal, Symmetry, Warehouse, Showcase, Motion, Broadcast.

Wenn der Shop eines dieser Themes ohne größere Änderungen am Header-Layout verwendet, aktivieren Sie einfach die App-Einbettung AI Search (Header) im Shopify Theme Editor und sie funktioniert sofort.

Schritt 2: Manuelle Selektor-Konfiguration (Benutzerdefinierte Themes)

Wenn ein Shop ein benutzerdefiniertes/nicht unterstütztes Theme verwendet oder den Header stark angepasst hat, kann der automatische Scanner möglicherweise nicht an die Suchleiste binden. In diesem Fall kann der Benutzer die Selektoren manuell in den Einstellungen für die App-Einbettung definieren:

1. Öffnen Sie den Shopify Theme Editor.
2. Schalten Sie unter App-Einbettungen den Einbettungsblock AI Search (Header) auf Aktiv.

3. Erweitern Sie die Blockeinstellungen, um die Felder für die Search Override Selectors anzuzeigen:

Wie man diese Selektoren mit Browser-DevTools findet:

1. Öffnen Sie das Frontend des Shopify-Shops in einem Google Chrome- oder Safari-Browserfenster.
2. Klicken Sie mit der rechten Maustaste auf das Suchsymbol/-schaltfläche und wählen Sie Untersuchen (Inspect).
3. Suchen Sie das entsprechende HTML-Element in der DevTools-Konsole:
   • Für den Trigger-Selector: Suchen Sie nach dem <a>- oder <button>-Tag, das das Suchsymbol darstellt. Kopieren Sie seine Klassennamen (z. B. button.header__icon--search oder .search-trigger).
   • Für den Input-Selector: Finden Sie das Texteingabe-Tag <input name="q" ...>. Kopieren Sie seinen Klassen- oder ID-Selektor (z. B. .search-form__input oder #search-input).
   • Für den Container-Selector: Suchen Sie den äußeren übergeordneten Container, der das gesamte Suchformular/Dialogfeld umschließt. Kopieren Sie seinen Selektor (z. B. .search-bar oder .header__search).
4. Fügen Sie diese Werte in die entsprechenden Textfelder im Shopify Theme Editor ein und klicken Sie auf Speichern.

Entwickler-APIs & Event-Referenzen

Wenn Benutzer benutzerdefinierte Interaktionen mit dem Smart Search Widget erstellen möchten, werden die folgenden Ereignisse am window-Objekt ausgelöst:

Fehlerbehebung