# Smart Bundle Engine — Dokumentation

> Überblick Smart Bundle Engine analysiert Ihren WooCommerce-Bestellverlauf, um wirklich gemeinsam gekaufte Produkte zu erkennen, generiert automatisch die passenden Bundles und zeigt sie auf der Produktseite, im Warenkorb und in der…

- Seite: <https://www.datafirefly.com/de/documentation/dfsmartbundle/>
- Sprache: de
- Aktualisiert am: 2026-07-01
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfsmartbundle/index.md), [en](https://www.datafirefly.com/en/documentation/dfsmartbundle/index.md), [es](https://www.datafirefly.com/es/documentation/dfsmartbundle/index.md), [it](https://www.datafirefly.com/it/documentation/dfsmartbundle/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsmartbundle/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsmartbundle/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsmartbundle/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

## Überblick

Smart Bundle Engine analysiert Ihren WooCommerce-Bestellverlauf, um wirklich gemeinsam gekaufte Produkte zu erkennen, generiert automatisch die passenden Bundles und zeigt sie auf der Produktseite, im Warenkorb und in der Bestätigungsmail an — mit einer Margensteuerung, die den Rabatt bei Bedarf automatisch begrenzt.

## Installation

1. Laden Sie `df-smart-bundle.zip` aus Ihrem DataFirefly-Kundenkonto herunter.
2. Gehen Sie in Ihrer WordPress-Verwaltung zu **Plugins → Installieren → Plugin hochladen**.
3. Wählen Sie die ZIP-Datei, klicken Sie auf **Jetzt installieren** und aktivieren Sie das Plugin.
4. Ein neues Menü **Smart Bundles** erscheint in der Seitenleiste der Verwaltung.

**Voraussetzungen:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+. Die HPOS-Kompatibilität (High-Performance Order Storage) ist nativ deklariert.

Bei der Aktivierung erstellt das Plugin 4 eigene Tabellen (`df_sbe_cooccurrence`, `df_sbe_bundles`, `df_sbe_bundle_items`, `df_sbe_analysis_state`) und plant den Analyse-Cron.

## Schnellstart

1. Gehen Sie zu **Smart Bundles → Analyse** und klicken Sie auf **Analyse jetzt starten**.
2. Nach Abschluss der Analyse zeigt die Tabelle **Top-Kaufaffinitäten** die erkannten Paare mit ihren Metriken (Vorkommen, Konfidenz, Lift).
3. Wenn die automatische Erstellung aktiviert ist (Standard), werden die Bundles automatisch erstellt — prüfen Sie sie unter **Smart Bundles → Bundles**.
4. Besuchen Sie eine betroffene Produktseite im Shop: der Block „Häufig zusammen gekauft" erscheint unter der Produktzusammenfassung.

**Tipp:** Die Analyse benötigt mindestens einige Dutzend Bestellungen mit mehreren Produkten, um verwertbare Affinitäten zu liefern. Bei dünner Historie senken Sie den Mindest-Co-Occurrence-Schwellenwert vorübergehend auf 2 in den Einstellungen.

## Co-Occurrence-Analyse

Die Engine durchläuft **abgeschlossene und in Bearbeitung befindliche** Bestellungen innerhalb des konfigurierten Analysezeitraums (standardmäßig 180 Tage), in Stapeln zu 200 Bestellungen. Für jede Bestellung mit mehreren Produkten werden alle Paare extrahiert und gezählt.

### Die drei Metriken

- **Vorkommen** — Anzahl der Bestellungen, die das Paar A+B enthalten.
- **Konfidenz** — P(B|A) in Prozent: in welchem Anteil der Bestellungen mit A findet sich auch B. Eine Konfidenz von 20 bedeutet, dass B in 20 % der Bestellungen mit A vorkommt.
- **Lift** — Verhältnis zwischen der beobachteten Paar-Häufigkeit und der erwarteten Häufigkeit, wenn A und B unabhängig wären. Ein Lift über 1 zeigt eine echte Affinität; über 2 eine starke.

### Planung

Die Analyse läuft automatisch über WP-Cron (Hook `df_sbe_run_analysis`). Jeder Durchlauf verarbeitet bis zu 25 Stapel zu 200 Bestellungen und setzt beim nächsten Auslösen dank eines persistenten Cursors fort — keine Bestellung wird zweimal verarbeitet. Die Schaltfläche **Status zurücksetzen** leert die Analysetabellen und beginnt von vorn.

**Achtung:** Wenn WP-Cron auf Ihrem Server deaktiviert ist (`DISABLE_WP_CRON`), stellen Sie sicher, dass ein System-Cron `wp-cron.php` regelmäßig aufruft, sonst läuft die Analyse nur bei manueller Ausführung.

## Automatische Bundle-Erstellung

Nach jeder vollständigen Analyse wählt die Engine die Paare aus, die Ihre Schwellenwerte überschreiten, und erstellt die passenden Bundles. Drei Einstellungen steuern die Auswahl:

- **Mindest-Co-Occurrences** (standardmäßig 3) — Mindestanzahl Bestellungen mit dem Paar.
- **Mindestkonfidenz** (standardmäßig 10 %) — Schwelle, unter der das Paar ignoriert wird.
- **Max. Bundles pro Produkt** (standardmäßig 3) — verhindert die Übersättigung eines Produkts.

Die ausgewählten Paare werden nach Punktzahl (Lift × Vorkommen) sortiert. Automatisch erstellte Bundles erhalten die Herkunft „Auto"; bestehende Bundles mit denselben Produkten werden niemals dupliziert. Manuelle Bundles bleiben bei erneuten Analysen immer erhalten.

## Bundle-Verwaltung

Der Bildschirm **Smart Bundles → Bundles** listet alle Bundles mit ihren Produkten, Rabatt, Mindestmarge, Anzeigekontexten, Aufrufen und Conversions. Sie können nach Status, Herkunft (auto/manuell) oder Freitextsuche filtern.

### Bundle erstellen oder bearbeiten

1. Klicken Sie auf **Neues Bundle** oder **Bearbeiten** bei einem bestehenden Bundle.
2. Suchen und fügen Sie die Produkte hinzu (mindestens 2) — die Menge jedes Artikels ist anpassbar, die Reihenfolge per Drag-and-Drop veränderbar.
3. Legen Sie den Rabatt (Prozentsatz oder Festbetrag) und die Mindestmarge fest.
4. Haken Sie die gewünschten Anzeigekontexte an: Produktseite, Warenkorb, E-Mail.
5. Die **Priorität** bestimmt die Anzeigereihenfolge, wenn mehrere Bundles infrage kommen (höher = zuerst).

Bei einem bestehenden Bundle zeigt eine **Preisvorschau**-Tabelle live die Zwischensumme, die geschätzten Kosten, den angeforderten vs. angewendeten Rabatt, den Endpreis und die tatsächliche Marge.

## Margensteuerung

Jedes Bundle hat eine **Mindestmargen**-Schwelle (in % des Endpreises). Die Engine berechnet den entsprechenden Mindestpreis:

```
min_endpreis = gesamtkosten / (1 − mindestmarge / 100)
```

Würde der angeforderte Rabatt den Endpreis unter diese Schwelle drücken, wird er **automatisch begrenzt** auf den maximal kompatiblen Rabatt. Der im Shop angezeigte Rabatt ist somit immer sicher.

### Kostenquelle

Die Kosten jedes Produkts werden in dieser Reihenfolge bestimmt:

1. **Produkt-Meta** — standardmäßig der Schlüssel `_df_cost_price`, in den Einstellungen konfigurierbar (kompatibel mit Cost of Goods und anderen Einkaufspreis-Plugins).
2. **Ersatzquote** — für Produkte ohne hinterlegte Kosten wird ein Prozentsatz des Verkaufspreises angenommen (standardmäßig 50 %).

**Tipp:** Hinterlegen Sie zuerst die tatsächlichen Kosten Ihrer meistverkauften Produkte — die Margenbegrenzung ist dann bei den wichtigsten Bundles exakt.

## Anzeige im Shop

### Produktseite

Der Block wird am Hook `woocommerce_after_single_product_summary` mit konfigurierbarer Priorität eingefügt (standardmäßig 15, direkt vor den verwandten Produkten). Er zeigt die durch „+" verbundenen Produkt-Miniaturen, die durchgestrichene Zwischensumme, den Bundle-Preis und die Ein-Klick-Warenkorb-Schaltfläche.

### Warenkorb

Die Vorschläge erscheinen unter der Warenkorbtabelle (`woocommerce_after_cart_table`). Bundles, deren Produkte bereits alle im Warenkorb sind, werden automatisch ausgeblendet.

### Bestätigungsmail

Ein Vorschlagsblock wird in die E-Mails **Bestellung abgeschlossen** und **Bestellung in Bearbeitung** eingefügt (nur kundenseitig), in HTML- und Klartext-Varianten, mit direktem Rück-Link zum Shop.

Jeder Kontext lässt sich unabhängig aktivieren und sein Titel in den Einstellungen anpassen.

## Rabattanwendung

Das Plugin verändert niemals die Produktpreise. Wenn ein Bundle in den Warenkorb gelegt wird, trägt jeder Artikel einen internen Marker; sobald alle Bundle-Artikel vorhanden sind, wird der Rabatt als **negative Gebühr** in WooCommerce angewendet („Bundle-Rabatt"). Dieser Ansatz:

- erhält die Zeilenpreise und Verkaufsberichte;
- bleibt mit Steuern, Versand und Gutscheincodes kompatibel;
- entfernt den Rabatt automatisch, wenn ein Bundle-Artikel aus dem Warenkorb entfernt wird.

## Leistungsverfolgung

Jede Anzeige eines Bundles erhöht seinen **Aufruf**-Zähler; jede Bestellung mit einem vollständigen Bundle erhöht seine **Conversions** (beim Übergang in den Status „in Bearbeitung" oder „abgeschlossen", mit Schutz gegen Doppelzählung). Die Conversion-Rate pro Bundle wird in der Bundle-Liste angezeigt, und der Bildschirm **Analyse** zeigt die globalen Statistiken: analysierte Bestellungen, erkannte Paare, aktive Bundles, kumulierte Aufrufe und Conversions.

## Einstellungsreferenz

### Co-Occurrence-Analyse

- **Analysezeitraum (Tage)** — standardmäßig 180. Abgeschlossene und in Bearbeitung befindliche Bestellungen in diesem Zeitraum.
- **Mindest-Co-Occurrences** — standardmäßig 3.
- **Mindestkonfidenz (%)** — standardmäßig 10.
- **Automatische Bundle-Erstellung** — standardmäßig aktiviert.
- **Max. Bundles pro Produkt** — standardmäßig 3.

### Preise & Marge

- **Standardrabatt (%)** — 10, angewendet auf automatisch erstellte Bundles.
- **Standard-Mindestmarge (%)** — 20.
- **Meta-Schlüssel Einkaufspreis** — `_df_cost_price`.
- **Ersatz-Kostenquote (%)** — 50.

### Anzeige

- **Kontexte** — Produktseite / Warenkorb / E-Mail, separat aktivierbar.
- **Hook-Priorität Produktseite** — standardmäßig 15.
- **Titel** — ein anpassbarer Titel pro Kontext.

## Mehrsprachigkeit

Das Plugin wird mit 5 Sprachen (FR, EN, ES, DE, IT) als `.po`/`.mo`-Dateien plus einer `.pot`-Datei für eigene Übersetzungen ausgeliefert (Textdomain `df-smart-bundle`). Kompatibel mit Polylang und WPML — die angezeigte Sprache folgt der Website- oder Benutzer-Locale.

## Deinstallation

Die Deaktivierung des Plugins entfernt lediglich den geplanten Cron — Ihre Daten bleiben erhalten. Das **Löschen** des Plugins (über Plugins → Löschen) führt `uninstall.php` aus, das die 4 Tabellen, alle Optionen und die vom Plugin erstellten Bestell-Metadaten endgültig entfernt (HPOS-kompatibel).

## Fehlerbehebung

### Es werden keine Bundles erstellt

- Prüfen Sie, ob die Analyse gelaufen ist: **Smart Bundles → Analyse** muss eine Anzahl analysierter Bestellungen größer als null anzeigen.
- Senken Sie die Schwellenwerte (Mindest-Co-Occurrences, Mindestkonfidenz) bei kleiner Historie.
- Prüfen Sie, ob die automatische Erstellung in den Einstellungen aktiviert ist.

### Das Bundle erscheint nicht im Shop

- Das Bundle muss **aktiv** und der betreffende Kontext angehakt sein.
- Ein Bundle mit berechnetem Rabatt von null (vollständige Margenbegrenzung) wird auf der Produktseite ausgeblendet.
- Im Warenkorb wird ein bereits vollständiges Bundle absichtlich ausgeblendet.
- Leeren Sie den Seiten-Cache, wenn Sie ein Caching-Plugin verwenden.

### Der angewendete Rabatt ist geringer als konfiguriert

Das ist die Margenbegrenzung in Aktion: Die Gesamtkosten des Bundles erlauben den angeforderten Rabatt nicht, ohne die Mindestmarge zu unterschreiten. Prüfen Sie die Produktkosten oder passen Sie die Margenschwelle des Bundles an.

## FAQ

### Funktioniert das Plugin mit variablen Produkten?

Die Analyse und Bundles arbeiten auf Ebene des Elternprodukts. Variationen desselben Produkts werden zusammen gezählt.

### Kann ich bestimmte Produkte von der Analyse ausschließen?

Nicht in Version 1.0.0 — löschen oder deaktivieren Sie einfach unerwünschte Bundles; sie werden nicht neu erstellt, wenn Sie sie nach Deaktivierung der automatischen Erstellung löschen.

### Sind Bundles mit Gutscheincodes kompatibel?

Ja. Der Bundle-Rabatt ist eine negative Gebühr, unabhängig von WooCommerce-Gutscheinen; beide sind kumulierbar.

### Wie ist die Auswirkung auf die Performance?

Die Analyse läuft im Hintergrund in Stapeln. Im Shop sind die Bundle-Abfragen leichtgewichtig (indizierte Tabellen) und die Assets werden nur auf Produkt- und Warenkorbseiten geladen.