Magento-Integration – Produkte, Bestellungen und Kundengruppen

Verbinden Sie Ihren Magento-Shop (Magento Open Source oder Adobe Commerce 2.4) mit Personyze und halten Sie Personyze mit ihm synchron: Ihre Produkte im Katalog, aus dem die Empfehlungen schöpfen, Ihre Bestellungen als Kaufhistorie im Profil jedes Käufers und die Magento-Daten Ihrer Kunden in deren Besucherprofilen.

Was es tut

Drei Synchronisierungen, die Sie jeweils einzeln einschalten:

• Produkte in Ihren Katalog. Jedes aktivierte Produkt, das in Ihrem Katalog oder in der Suche sichtbar ist, alle 6 Stunden: Name, Beschreibung, Hauptbild, Preis und Sonderpreis, Marke, Kategorien sowie der Bestand mit Stückzahl. Empfehlungen, Produkt-Widgets und katalogbasiertes Targeting nutzen sie sofort. Ein Produkt, das aus Ihrem Shop verschwindet, wird im Katalog als nicht vorrätig geführt.
• Bestellungen in die Kaufhistorie. Die Produkte jeder Bestellung werden zu Käufen im Besucherprofil des Käufers, zugeordnet über seine E-Mail-Adresse – für einen Käufer, den Personyze noch nicht kennt, wird ein Profil angelegt, auch bei Gastbestellungen –, mit Datum und Betrag der Bestellung. Der erste Durchlauf liest die Bestellungen eines Jahres; danach kommen neue Bestellungen alle 15 Minuten hinzu.
• Kunden in Besucherprofile. Name, Kundengruppe und Registrierungsdatum jedes Kunden, stündlich in seinem Profil, zugeordnet über die E-Mail-Adresse. Sie erscheinen als Besucherattribute, auf die Sie zielen können: Magento customer group, Magento customer since und Magento customer ID. Zum Beispiel: Zeigen Sie Besuchern, deren Magento customer group „Wholesale“ ist, Händlerpreise.

Was Sie brauchen

• Magento Open Source oder Adobe Commerce 2.4 (oder Mage-OS).
• Einen Magento-Admin-Benutzer, der Integrationen anlegen darf (System → Extensions → Integrations).
• Ihren Shop unter einer öffentlichen https-Adresse. Personyze verbindet sich über das Internet mit der API Ihres Shops.

Schritt 1: Die Integration in Magento anlegen

1. Gehen Sie in Ihrem Magento-Admin zu System → Extensions → Integrations → Add New Integration.
2. Geben Sie ihr einen Namen (zum Beispiel „Personyze“) und bestätigen Sie mit Ihrem Admin-Passwort.
3. Öffnen Sie den Tab API, setzen Sie Resource Access auf Custom und kreuzen Sie an:
   • Catalog → Inventory – Produkte, Kategorien und Bestand. Kreuzen Sie Inventory selbst an, nicht nur Products darunter: Der Bestand wird darüber gelesen.
   • Sales → Operations → Orders → Actions → View – Bestellungen.
   • Customers – Kunden und Kundengruppen.
   • Stores → Settings → All Stores – die Adressen und die Währung Ihres Shops.
   • Stores → Attributes → Product – Markennamen.

   Personyze liest nur; es ändert nie etwas in Ihrem Shop.

4. Klicken Sie auf Save. Klicken Sie in der Liste „Integrations“ neben der Integration auf Activate und dann auf Allow.
5. Magento zeigt vier Werte: Consumer Key, Consumer Secret, Access Token und Access Token Secret. Alle vier tragen Sie in Schritt 2 in Personyze ein – lassen Sie dieses Fenster bis dahin geöffnet und bewahren Sie die Werte sicher auf.

Schritt 2: Die Integration in Personyze verbinden

1. Gehen Sie in Personyze zu Einstellungen → Integrationen und öffnen Sie Magento (unter Plattform & Entwickler).
2. Tragen Sie Folgendes ein:
   • Shop-Adresse – die Adresse, die Ihre Kunden aufrufen, zum Beispiel https://shop.example.com/. Ein Shop in einem Unterordner, etwa https://www.example.com/shop/, funktioniert ebenfalls. Nicht die Admin-Adresse.
   • Die vier Werte aus Schritt 1: Consumer Key, Consumer Secret, Access Token und Access Token Secret.
3. Klicken Sie auf Verbinden.

Personyze prüft die vier Werte bei Ihrem Shop, bevor es sie speichert – Werte, die nicht funktionieren, werden nie gespeichert – und ermittelt, welche der drei Synchronisierungen die Integration lesen darf. Die drei geheimen Werte werden verschlüsselt aufbewahrt und nie wieder angezeigt: Ihre Felder zeigen von da an „(unverändert)“. Der Seitenbereich zeigt dann Verbunden mit Ihrem Shop.

Um später etwas zu ändern, bearbeiten Sie die Felder und klicken auf Prüfen und speichern. Bei gleichem Shop und gleichem Consumer Key können Sie die geheimen Felder leer lassen, um die gespeicherten Werte zu behalten.

Personyze signiert jede Anfrage mit den vier Werten der Integration (OAuth 1.0a), so wie Magento es von einer Integration erwartet. Sie müssen in den OAuth-Einstellungen von Magento nicht „Allow OAuth Access Tokens to be used as standalone Bearer tokens“ einschalten.

Schritt 3: Einschalten, was synchronisiert wird

Schalten Sie unter Was synchronisiert wird jede gewünschte Synchronisierung ein: Produkte in Ihren Katalog, Bestellungen in die Kaufhistorie und Kunden in Besucherprofile. Jede Zeile zeigt, was sie von der Integration benötigt – Produkte, Bestellungen oder Kunden –, in Grün, wenn die Integration es lesen darf, und in Rot mit „Für die Integration nicht freigegeben“, wenn nicht (siehe Fehlerbehebung).

Eine Synchronisierung, die Sie einschalten, zeigt „Startet innerhalb von 5 Minuten“. Nach einem Durchlauf zeigt jede Zeile, was sie getan hat, zum Beispiel „7 Produkte · 1. Okt.“, „8 Käufe seit 1. Okt.“ oder „3 Profile · 1. Okt.“. Jetzt synchronisieren führt eine Synchronisierung beim nächsten Durchlauf aus, innerhalb von 5 Minuten, ohne auf ihren Zeitplan zu warten.

Wie die Daten verwendet werden

Produkte

Jedes Produkt ist ein Katalogelement, identifiziert durch seine Magento-Produkt-ID. Sein Link setzt sich zusammen aus der Adresse Ihres Shops, dem URL-Key des Produkts und Ihrem Produkt-URL-Suffix (.html sofern Sie es nicht geändert haben).

• Preise: Ein Sonderpreis gilt, solange das heutige Datum innerhalb seines Von-/Bis-Zeitraums liegt, und nur, wenn er niedriger als der Preis ist – dann ist der Preis der reguläre Preis und der Sonderpreis der Angebotspreis. Katalogpreisregeln werden auf die synchronisierten Preise nicht angewendet.
• Konfigurierbare Produkte (zum Beispiel ein T-Shirt in mehreren Größen) sind ein Katalogelement, mit dem niedrigsten Preis ihrer aktivierten Varianten und dem addierten Bestand ihrer Varianten. Die Varianten selbst („Not Visible Individually“) werden nicht als eigene Produkte synchronisiert.
• Bestand: Ein Produkt ist vorrätig, wenn Magento es sagt; die Stückzahl wird nur übernommen, wenn Magento den Bestand des Produkts verwaltet.
• Marke: das Attribut brand oder manufacturer Ihres Shops.
• Kategorien: die Namen der Kategorien des Produkts.
• Deaktivierte Produkte, nicht einzeln sichtbare Produkte und Produkte ohne URL-Key werden nicht synchronisiert.
• Es werden bis zu 50.000 Produkte synchronisiert. Bei einem größeren Shop werden die ersten 50.000 synchronisiert, und die Zeile „Produkte“ weist darauf hin.

Käufe

Die Käufe einer Bestellung sind ihre Produkte (ein konfigurierbares Produkt zählt als das Produkt, nicht als seine Variante). Stornierte oder erstattete Mengen werden ausgelassen, und der Rabatt jeder Position wird von ihrem Betrag abgezogen. Stornierte Bestellungen, vollständig erstattete (geschlossene) Bestellungen und Bestellungen ohne E-Mail-Adresse ergeben keine Käufe.

Produkt-Feeds

Wenn Ihr Konto zusätzlich einen Produkt-Feed importiert, kann ein Produkt, das in beiden vorkommt, doppelt im Katalog erscheinen. Verwenden Sie pro Produkt nur eine Quelle – die Zeile „Produkte“ warnt Sie, wenn das Konto einen Feed hat.

Trennen

Klicken Sie im Seitenbereich auf das Papierkorb-Symbol neben „Verbunden mit …“. Die Synchronisierung stoppt; bereits synchronisierte Produkte, Käufe und Profile bleiben erhalten. Die Integration bleibt in Ihrem Magento-Admin – löschen Sie sie dort, wenn Sie sie nicht mehr brauchen.

Fehlerbehebung

“There is no Magento API at …”

Die Adresse ist nicht die des Shops selbst. Geben Sie die Adresse ein, die Ihre Kunden aufrufen, etwa https://shop.example.com/ – nicht die Admin-Adresse.

“Magento did not accept these keys.”

Prüfen Sie, ob die Integration in Magento Active ist, und geben Sie alle vier Werte erneut aus den Details der Integration ein. Wenn Sie in Magento auf Reauthorize geklickt haben, hat es ein neues Access Token und ein neues Access Token Secret ausgestellt – tragen Sie diese ein.

“The integration may read nothing Personyze syncs.”

Die Integration hat keine der Ressourcen aus Schritt 1. Bearbeiten Sie sie in Magento → API, kreuzen Sie die Ressourcen an, klicken Sie auf Save, dann auf Reauthorize und Allow, und tragen Sie die neuen Werte in Personyze ein.

Eine Synchronisierungszeile ist rot und zeigt „Für die Integration nicht freigegeben“

Bearbeiten Sie in Magento die Integration → API, kreuzen Sie die Ressource an, die die Zeile nennt (siehe Schritt 1), klicken Sie auf Save, dann auf Reauthorize und Allow. Tragen Sie das neue Access Token und Access Token Secret in Personyze ein und klicken Sie auf Prüfen und speichern.

“Personyze cannot connect to …”

Personyze erreicht Ihren Shop über das Internet, und zwar nur per https. Ein Shop in einem privaten Netzwerk oder unter einfachem http kann nicht verbunden werden.

“The signature is invalid”, obwohl die vier Werte stimmen

Magento prüft die Signatur jeder Anfrage gegen die Adresse, unter der es seiner Meinung nach aufgerufen wurde. Steht Ihr Shop hinter einem Proxy, Load Balancer oder CDN, der https beendet und einfaches http an Magento weiterreicht, muss Magento mitgeteilt bekommen, dass die Anfrage per https kam – über seinen Offloader-Header, meist X-Forwarded-Proto: https, den der Proxy setzt. Ein Shop, dessen sichere Seiten normal funktionieren, hat das bereits. Beim Verbinden erscheint dies als “Magento did not accept these keys.”; während einer Synchronisierung stehen Magentos eigene Worte – “The signature is invalid” – in dem Grund, den der Seitenbereich anzeigt.

“The store redirected to …”

Die eingegebene Adresse leitet Besucher an eine andere weiter (zum Beispiel von example.com zu www.example.com). Geben Sie die Adresse ein, auf die sie weiterleitet.

Der Seitenbereich zeigt die Ablehnung von Magento statt „Verbunden mit“

Magento hat die Schlüssel während einer Synchronisierung abgelehnt – die Integration wurde deaktiviert, gelöscht oder neu autorisiert. Personyze verwendet die Verbindung sofort nicht mehr, statt es erneut zu versuchen, und der Seitenbereich zeigt den Grund von Magento dort, wo „Verbunden mit“ stand. Tragen Sie die aktuellen vier Werte der Integration ein und klicken Sie auf Verbinden. Ein wieder verbundener Shop behält seine Synchronisierungen, wie sie waren.

Jedes Produkt erscheint als vorrätig, ohne Stückzahl

Die Integration darf den Bestand nicht lesen: Kreuzen Sie Catalog → Inventory selbst an (Schritt 1), autorisieren Sie die Integration neu und tragen Sie die neuen Werte in Personyze ein.

Preise weichen von der Storefront ab

Katalogpreisregeln werden auf synchronisierte Preise nicht angewendet; Sonderpreise schon.

Die Firewall des Shops blockiert die Verbindung

Steht Ihr Shop hinter einer Firewall, die automatisierte Anfragen blockiert, erlauben Sie Anfragen mit dem User-Agent Personyze/1.0 (+https://www.personyze.com).

Verwandte Themen

• Integrationen — alle anderen Verbindungen.
• Shopify-Integration (Verbindung per API) – dieselben drei Synchronisierungen für einen Shopify-Shop.
• Personyze installieren – der Tracking-Code, den Ihre Storefront braucht.
• Empfehlungen: der Einstieg – Widgets auf Basis des synchronisierten Katalogs und der Käufe.
• Den Produkt-/Content-Feed einrichten – der andere Weg, den Katalog zu füllen.
• Targeting-Regeln – Targeting nach der Magento customer group.
• Fehlerbehebung: Eine Integration synchronisiert nicht