Installation Guide for OXID 4

Endereco Address Management Service Module (AMS)
For OXID 4.7.x - 4.10.x PE, or 5.0.x - 5.3.x EE

Current release notes:

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

Functional description

Endereco Address Management Services provide a simple and straightforward way to improve the quality of the address data entered by your customers. To this end, a two-step process is integrated into the address forms to ensure that data is captured correctly on virtually all input devices.

Level 1

a) Input Assistant - Input help

Suggestions for entered address fragments are displayed in an autocomplete function of street, postcode and city. This works on PCs, tablets and smartphones. Address entry is simplified, accelerated and the error rate is massively reduced.

b) First name check - Does the form of address match the first name?

The Endereco first name database with over 30,000 entries can recognise gender-specific first names and marks the corresponding salutation field of your webshop. Ambiguous or unknown names are ignored. Upper and lower case is automatically corrected.

c) E-mail verification

An entered e-mail address is checked for various characteristics in real time:

  • Valid syntax of the e-mail address
  • Valid country domain
  • Is the mailbox full or deliverable?
  • If it is a one-way address or SPAM e-mail address
d) Telephone numbers Standardisation

Different ways of writing telephone numbers are very common. Endereco tidies up and gives telephone numbers a uniform, standardised spelling. In addition, Endereco distinguishes between mobile numbers and landline numbers and can include this feature if desired. Invalid prefixes are recognized and marked

Level 2

a) AddressCheck

The address check validates entered fields for validity in the overall context. Valid correction proposals are automatically offered for entries that are not plausible. The customer can choose between his entry and one of the correction codes.


Installation

2.1 Installation of the module

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 of the module

To update Endereco Client for OXID, please download the latest version of GitHub herunter und folgen Sie die Installationsanweisungen aus dem Kapitel 2.1

2.3 Adjusting the field order

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"

the order of the input fields by simply changing the block order in the two files. The correct order in billing address and delivery address is

COUNTRY
Postcode / City
Street / House number

Therefore the following blocks in the code must be swapped:

Before After
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

Example: Swap "street" and "postal code":

Before After

After adjusting the field order, the address fields should look like this:

2.4 Activating the module in the admin backend

  • Log in to the backend
  • Extension → Click on the module → "Endereco AMS".
  • Click on the "Trunk" tab.
  • Click on the button to the right called "Activate".

Request access data

3.1 Test access data

The module only works with valid access data, which you can download from our website at //www.endereco.de/oxid-eshop/ or directly by e-mail to info@endereco.de free of charge.

You can then test the module including all services for 30 days without obligation.

3.2 Live access data

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.

About the data processing contract: For some services in which we process personal data of the customer or pass them on to third parties via interfaces according to the DSGVO, we need a data processing contract. For example, when it comes to an e-mail deliverability check or telephone number standardization. You will also find this in the installation package.

Please send both signed contracts to
info@endereco.de or by fax to: 0931 6639839-9 or by mail to us.
We need a release from the German Post, which can take about 2-3 days.

Endereco UG (limited liability)
Robert Rieser
Balthasar-Neumann-Str. 4b,
97236 Edge bag

3.3 Entering the access data

  • In the shop backend click on Endereco - address validation
  • Select settings
  • Enter API key, select service endpoint
  • Save entries

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.


Configuration of the module 

4.1 Selecting the test mode

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. Salutation check: 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. Use standard CSS: 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.

Functional test 

Now, after selecting the country "Germany" and entering a postcode, you should receive suitable suggestions for the city. Suggestions should also appear when you enter the street.

Have fun using our module. We are looking forward to your feedback, suggestions and feedback. This is the only way we can optimize our services for you!

If you have any questions we will be happy to help you!
Simply send an e-mail to: info@endereco.de or Tel: 0931 66 39 839 - 0
Your Endereco Team


Robert Rieser
CEO - Contact person for your inquiries

You still have questions or would like to discuss special requirements?

You can arrange a free meeting with our experts!

Extract of our customers

    References

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