Installationsanleitung für OXID 4

Endereco Address Management Service Modul (AMS)
Für OXID 4.7.x – 4.10.x PE, bzw. 5.0.x – 5.3.x EE

Aktuelle Release Notes:

Aktuelle Release Notes findest du ganz einfach auf unserer GitHub Seite:

Funktionsbeschreibung

Die Endereco Address Management Services ermöglichen auf einfache und unkomplizierte Weise, die Qualität der Adressdaten, die von Ihren Kunden eingegeben werden, zu verbessern. Hierfür wird ein zweistufiger Prozess in die Adressformulare integriert, der eine korrekte Erfassung der Daten über nahezu alle Eingabegeräte sicherstellt.

Stufe 1

a) Input Assistant – Eingabehilfe

Vorschläge zu eingegebenen Adressfragmenten werden in einer Autocomplete Funktion von Straße, PLZ und Ort angezeigt. Dies funktioniert auf PCs, Tablets und Smartphones. Die Adresseingabe wird vereinfacht, beschleunigt und die Fehlerquote massiv reduziert.

b) Vornameprüfung – Passt die Anrede zum Vornamen?

Die Endereco Vornamendatenbank mit über 30.000 Einträgen kann geschlechtsspezifisch eindeutige Vornamen erkennen, und markiert das entsprechende Anredefeld ihres Webshops. Mehrdeutige oder unbekannte Namen werden ignoriert. Groß- und Kleinschreibung wird automatisch korrigiert.

c) E-Mail Prüfung

Eine eingegebene E-Mail-Adresse wird in Echtzeit auf verschiedene Merkmale geprüft:

  • Gültige Syntax der E-Mail-Adresse
  • Gültige Länderdomain
  • Ist das Postfach voll oder zustellbar?
  • Handelt es sich um eine Einweg-Adresse oder SPAM E-Mail-Adresse
d) Telefonnummern Normierung

Unterschiedliche Schreibweisen von Telefonnummern sind sehr verbreitet. Endereco räumt auf und gibt Telefonnummern eine einheitliche, normierte Schreibweise. Zusätzlich unterscheidet Endereco mobile Rufnummern und Festnetznummern und kann auf Wunsch dieses Merkmal mitgeben. Ungültige Vorwahlen werden erkannt und gekennzeichnet

Stufe 2

a) AddressCheck

Der Adresscheck validiert eingegebenen Felder auf Gültigkeit im Gesamtzusammenhang. Auf nicht plausible Eingaben werden automatisch valide Korrekturverschläge angeboten. Der Kunde kann zwischen seiner Eingabe und einem der Korrekturverschläge wählen.


Installation

2.1 Installation des Moduls

Um das Modul in einem Onlineshop zu installieren, muss zuerst der Quellcode heruntergeladen werden. Hierfür steht die Auflistung der Releases zur Verfügung.

Jeder Release enthält eine herunterladbare Datei, einen ZIP Archiv, die alle notwendige Dateien des Moduls beinhaltet.

Nachdem der Quellcode der Datei heruntergeladen wurde, soll der Archiv entpackt werden (falls als Archiv heruntergeladen) und der ganze Quellcode im Onlineshop im folgenden Verzeichnis abgelegt werden:

%SHOP_ROOT%/modules/endereco-oxid4-client

D.h. der ganze Pfad zu metadata.php wäre zum Beispiel %SHOP_ROOT/modules/endereco-oxid4-client/metadata.php

Ist dies gemacht, soll das Modul in der Auflistung der Module im Backend von Onlineshop sichtbar sein. Modul ist somit installiert.

Alternativ kann man gewünschte Version über git clone herunterladen.

Falls vor der Installation noch irgendwelche Anpassungen an JS Logik des Moduls gewünscht sind, soll der npm-Buildskript ausgeführt werden: npm install && npm run build. Im Normalfall ist dieses jedoch nicht notwendig.

In Onlineshops mit individuell entwickelten Themes ist es sehr empfehlenswert die Feldreihenfolge manuell anzupassen (siehe Kap. 2.3)

2.2 Update des Moduls

Um Endereco Client für OXID auf neuesten Stand zu bringen, laden Sie bitte die neueste Version von GitHub herunter und folgen Sie die Installationsanweisungen aus dem Kapitel 2.1

2.3 Anpassung der Feldreihenfolge

Die Anpassung der Feldreihenfolge muss ab der Version 4.* nicht mehr manuell angepasst werden. Es ist aber empfehlenswert die Feldreihenfolge manuell anzupassen, vor allem in Shops mit individuell entwickelten Themes. Wenn Sie die neuere Version des Moduls haben, können Sie diesen Kapitel überspringen.

Wenn Sie manuelle Anpassung der Feldreihenfolge trotzdem selber vornehmen wollen, sollen Sie hierfür folgendes in den Template Dateien anpassen:

„application/views/MYTHEME/tpl/form/fieldset/user_billing.tpl“

„application/views/MYTHEME /tpl/form/fieldset/user_shipping.tpl“

die Reihenfolge der Eingabefelder an, indem Sie einfach die Blockreihenfolge in den beiden Dateien ändern. Die korrekte Reihenfolge in Rechnungsadresse und Lieferadresse lautet

LAND
PLZ / Ort
Straße / Hausnummer

Im Code müssen daher folgende Blöcke vertauscht werden:

Vorher Nacher
Additional Info “div” Element Additional Info
StreetAndNo “div” Element Country + State (Block Element)
PostcodeAndCIty “div” Element PostcodeAndCIty “div” Element
Country + State (Block Element) StreetAndNo “div” Element
VatIdNo VatIdNo

Beispiel: Vertauschen von „Straße“ und „Postleitzahl“:

Vorher Nacher

Nach dem anpassen der Feldreihenfolge sollten die Adressfelder wie folgt aussehen:

2.4 Aktivieren des Moduls im Admin Backend

  • Im Backend einloggen
  • Erweiterung → Module → „Endereco AMS“ anklicken.
  • Auf den Tab „Stamm“ klicken.
  • Auf die Schaltfläche rechts namens „Aktivieren“ klicken.

Zugangsdaten anfordern

3.1 Test Zugangsdaten

Das Modul funktioniert nur mit gültigen Zugangsdaten.Diese können Sie auf unsere Webseite unter //www.endereco.de/oxid-eshop/ oder direkt per E-Mail an info@endereco.de kostenfrei beantragen.

Sie können dann das Modul inklusive alle Services 30 Tage unverbindlich testen.

3.2 Live Zugangsdaten

Für die Live Zugangsdaten benötigen wir zwei unterschriebene und freigegebene Verträge, nämlich Providervertrag und Datenverarbeitungsvertrag. Beide Verträge bekommen Sie per E-Mail zugeschickt zusammen mit den Zugangsdaten.

Zur Datenverarbeitungsvertrag: Für einige Services, in denen wir laut DSGVO persönliche Daten des Kunden verarbeiten oder an Dritte über Schnittstellen weitergeben, benötigen wir einen Datenverarbeitungsvertrag. Zum Beispiel wenn es um eine E-Mail Zustellbarkeitsprüfung oder Telefonnummern-Normierung geht. Diesen finden Sie ebenfalls im Installationspaket.

Bitte senden Sie beide unterschriebene Verträge an
info@endereco.de oder per Fax an: 0931 6639839-9 oder per Post an uns.
Wir benötigen eine Freigabe der Deutschen Post, die ca. 2-3 Tage dauern kann.

Endereco UG (haftungsbeschränkt)
Robert Rieser
Balthasar-Neumann-Str. 4b,
97236 Randersacker

3.3 Eingabe der Zugangsdaten

  • Im Shop Backend auf Endereco – Adressvalidierung klicken
  • Einstellungen auswählen
  • API-Key eingeben, Service-Endpoint auswählen
  • Einträge speichern

Trägt man den API-Key in Einstellungen ein und klickt auf “Aktivieren”, ist das Modul sofort aktiviert und einsatzbereit.

Es ist jedoch empfehlenswert sich die Einstellungen nochmal genauer anzuschauen und Feature zu aktivieren/deaktivieren, die man braucht.


Konfiguration des Moduls 

4.1 Wahl des Prüfmodus

Endereco Modul wird mit einer Standardkonfiguration ausgeliefert, daher ist es nicht notwendig diese anzupassen. Lediglich der API-Key muss eingetragen werden. Sie haben die Möglichkeit verschiedene Services ein- und auszuschalten:

  1. API-Schlüssel: über diesen Schlüssel identifizieren wir Anfragen aus dem Shop in unserer Schnittstelle. Jeder Nutzer hat einen individuellen Schlüssel.
  2. Status der Verbindung: Wenn die Server von Endereco erreichbar sind und der API Schlüssel korrekt ist, dann erscheint hier eine grüne Meldung. Sonst eine rote.
  3. Service URL: URL des Servers, an den die Anfragen gehen. Dieses Feld ist vorkonfiguriert und muss nicht angepasst werden, aber manchmal können wir einen Nutzer bitten dort einen anderen Server einzutragen.
  4. Aktivierung von Adressdiensten: falls man Adressen in Echtzeit prüfen lassen möchte, soll diese Einstellung aktiv bleiben. Somit werden Adressvervollständigung und Adresskorrektur aktiviert.
  5. Standardland vorauswählen: bei manchen Eingabemasken ist das Zielland oft nicht ausgewählt. Diese Einstellung erkennt ein nicht ausgewähltes Land und füllt es voraus. Das erhöht die Qualität der Eingabe.
  6. Standard: hier wird eingestellt, welches Land vorausgewählt werden muss. In der Regel ist das Deutschland, kann aber auch ein anderes sein.
  7. Bestandskunden prüfen: Wenn Bestandskunden bestellen, müssen sie in der Regel ihre Adresse nicht mehr eingeben. Somit können wir sie auch nicht prüfen. Mit dieser Einstellung werden ihre Adresse zum Zeitpunkt des Login einmalig geprüft. Später im Checkout bekommen sie einen Korrekturvorschlag, falls die Adresse Fehler enthält.
  8. Adressprüfung nach dem Verlassen des Hausnummer Felder auslösen: Mit dieser Einstellung wird es konfiguriert, wann die Adresse von unserem Modul geprüft wird. Ist die Einstellung aktiv, so wird sie geprüft sobald der Nutzer die Adresse eingegeben hat und in ein Nicht-Adress-Feld geht (i.d.R verlässt er dabei Hausnummernfeld). Das ist eine UX Einstellung, die eine sofortige Korrektur ermöglicht, während der Kunde noch gedanklich bei der Adresse ist.
  9. Absenden des Formulars nach der Adressauswahl fortsetzen: Wird die Adresse beim Speichern oder klicken auf “Weiter” geprüft, so beschließt diese Einstellung ob der Kunde nach der Korrektur auf der gleichen Seite bleibt oder ob das Absenden mittels JavaScript automatisch nochmal geschieht. Diese Einstellung ist interessant, wenn man noch weitere Prüfungen in der Eingabemaske hat oder man eine eigene Absenderlogik implementiert hat.
  10. SmartAutocomplete: Füllt Felder während der Eingabe voraus, wenn die Eingabe eindeutig vorhergesagt werden kann.
  11. Feldreihenfolge optimieren: Ändert die Eingabereihenfolge der Adresse so: Land -> Postleitzahl -> Ort -> Straße -> Hausnummer -> Adresszusatz. (siehe Kap. 2.3) Diese Reihenfolge ermöglicht relevantere Adressvorschläge während der Eingabe.
  12. E-Mail Prüfung aktivieren: Bestimmt, ob E-Mails auf Zustellbarkeit und Syntax geprüft werden sollen.
  13. Statusmeldungen für E-Mail: Bestimmt, ob gefundene Fehler unter der E-Mail Eingabe als Text angezeigt werden sollen.
  14. Anredeprüfung: Bestimmt, ob Andere geprüft werden soll. Wenn die Anrede zum Vornamen nicht passt, dann wird sie orange markiert. Falls keine Anrede ausgewählt ist, aber der Vorname eingegeben ist, dann wird die Anrede automatisch ausgewählt (nur wenn eindeutig aus dem Vornamen erkennbar ist)
  15. Standard CSS nutzen: Endereco Modul stellt für das Shopsystem optimierte Styles bereit. Falls man jedoch selber alles gestalten möchte, kann man diese Styles hier deaktivieren.
  16. Farben: einfache Farbeineinstellungen für das Korrekturmodul.
  17. Whitelist für Controller: Erweiterte Einstellung. Im Normalfall baut sich Endereco Modul auf jeder Seite, außer der 404-Seite ein. Über diese Einstellung kann man das Endereco Modul nur auf bestimmten Seiten erlauben. Hilft bei Modul Kollisionen und um Performance zu optimieren.
  18. Adressprüfung beim Absenden des Formulars: Löst die Adressprüfung, wenn man auf “Enter” oder Submit-Button klickt. Falls man eine eigene Logik dafür nutzt, kann man es hier deaktivieren.
  19. Debug Infos: erlaubt dem JS-Client Debuginfos in der Browser-Console auszugeben. Ist manchmal hilfreich, um ein Problem zu analysieren.

Funktionstest 

Nun sollten Sie nach Auswahl des Landes „Deutschland“ und der Eingabe einer PLZ passende Vorschläge für den Ort erhalten. Ebenso sollten Suggests bei der Eingabe der Straße erscheinen.

Viel Freude beim Einsatz unseres Moduls. Über Feedback, Anregungen und Rückmeldungen freuen wir uns. Nur so können wir unsere Services für Sie optimieren!

Bei Fragen helfen wir gerne weiter!
Einfach per E-Mail an: info@endereco.de oder Tel: 0931 66 39 839 – 0
Dein Endereco Team


Robert Rieser
CEO – Ansprechpartner für deine Anfragen

Du hast noch Fragen oder möchtest besondere Anforderungen besprechen?

Du kannst ein kostenfreies Meeting mit unseren Experten vereinbaren!

Auszug unserer Kunden

    Referenzen

    © Endereco UG (haftungsbeschränkt) - Gesellschaft für Master Data Quality Management - 2014 - 2021- Made with ♥ in Franconia