Technische Dokumentation: Bibliotheken für den Großhandel
- Florian Pieper
- Anna Janzen
- Philipp Kern
Beschreibung
Auf dieser Seite finden Sie die technischen Beschreibungen dazu, wie eine Bibliothek für den Großhandel integriert werden kann. Hier finden Sie auch Beschreibungen für Voraussetzungen sowie Beispielintegrationen. Auf den weiteren untergeordneten Seiten finden Sie dann die technischen Dokumentationen zu den spezifischen Integrationen von Dokumenten, der Deep Search uvm. Die Übersicht über diese Inhalte finden Sie hier aufgeführt:
Spezifische Widgetintegration
Die Übersicht der Inhalte dieser Seite finden Sie im folgenden Inhaltsverzeichnis:
Inhalt
Was ist ein Widget?
Ein Widget ist ein “CustomElement” das von der ITEK Technologie GmbH bereitgestellt wird, um Funktionen in Ihre bestehenden System zu integrieren. Diese Elemente basieren auf dem Web Components Standard Web Components - Web APIs | MDN und werden von alle aktuellen Browsern unterstützt.
Quelle: https://angular.io/guide/elements
Voraussetzung zum Ausführen des PHP Beispielcodes:
PHP Installiert
CURL in PHP installiert
Voraussetzungen am Anfragenden System (CORS)
Einbindende URL in .htaccess hinterlegen
Vor dem einbinden muss auf der entsprechenden Anlage die .htaccess Datei im Ordner /home/sportal/www angepasst werden. Hier muss die URL der Seite, unter der der Kunde das Widget einbinden will, unter Access-Control-Allow-Origin hinzugefügt werden. Dazu wird die Sektion <IfModule mod_headers.c> erweitert. Sollten die Einträge Header add Access-Control-Allow-Methods und Header add Access-Control-Allow-Headers fehlen, müssen diese auch hinzugefügt werden. Im folgenden Beispiel wird das Widget auf der Domain http://test.deepsearch.itek.de eingebettet:
# Add headers to all responses.
<IfModule mod_headers.c>
# Disable content sniffing, since it's an attack vector.
Header always set X-Content-Type-Options nosniff
Header add Access-Control-Allow-Origin "http://test.deepsearch.itek.de/"
Header add Access-Control-Allow-Methods "*"
Header add Access-Control-Allow-Headers "If-Modified-Since"
</IfModule>OAuth2 Anfrage
Diese Anfrage muss vor der Bereitstellung der HTML Seite als POST im Format “x-www-form-urlencoded” durchgeführt werden.
Url
[targetsystem]/oauth2/token
Beispiel: https://2.0.open-datacheck.de/oauth2/token
Parameter
Parameter | Pflicht | Beschreibung | Beispielwert |
|---|---|---|---|
grand_type | Ja | OAuth2 Grandtype. Für die aktuelle Integration des Widgets wird der Password Grant verwendet, hier wird immer der Wert “password” verwendet. | password |
client_id | Ja | ClientID die am System für die integration des Widgets eingestellt wurde. Es kann für alle Widgets der Wert “article_search_client” verwendet werden. | article_search_client |
username | Ja | Benutzername des Integrationsbenutzers |
|
password | Ja | Passwort des Integrationsbenutzers |
|
scope | Ja | Muss aktuell immer mit angegeben werden. Es kann für alle Widget der Wert ”customer_portal_view_article_data_30” eingetragen werden. | customer_portal_view_article_data_30 |
Antwort
{
"access_token": "963b779f70dc13c5cef6e0bded33b6cdb0be567c",
"expires_in": "360",
"token_type": "Bearer",
"scope": "customer_portal_view_article_data_30",
"refresh_token": "e33afb6b5a4c2f9f25ff4a5f370d5ed8edfac4f5"
}Beispielcode (PHP)
<?php
$targetURL = "TODO"; // URL der Anlage, von der das Widget eingebunden werden soll
$targetSystemUsername = "TODO"; // Benutzer auf der Anlage
$targetSystemPassword = "TODO"; // Passwort des Anlagen-Benutzeres
$params = array(
'grant_type' => 'password',
'client_id' => 'article_search_client',
'username'=> $targetSystemUsername,
'password' => $targetSystemPassword
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $targetURL . "/oauth2/token");
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
$json_result = json_decode($result, true);
?>Weiteren bzw. Beispielcode: https://oauth.net/code/
Integration der Widgets “xs-loader”
Funktionsweise “xs-loader”
Anfrage der Widgetversion am Zielsystem
Einbinden des Codes (JS) & der Styles (CSS)
Registrieren des Widgets im Browser
Rendern des Zielwidgets durch den Browser
Parameter Allgemein bzw. “xs-loader”
Zum Integrieren der Widgets werden folgende Parameter für jedes Widget zur Verfügung stehen.
Parameter | Pflicht | Beschreibung | Beispielwert |
|---|---|---|---|
accesstoken | Ja | OAuth2 Zugriffstoken für das Zielsystem. Dieses Token muss zuvor vom Integrierenden System am Zielsystem angefragt werden. |
|
refreshtoken | Ja | OAuth2 Refresktoken für das Zielsystem. Dieses Token muss zuvor vom Integrierenden System am Zielsystem angefragt werden. |
|
targeturl | Ja | URL des Zielsystems mit HTTPS.
| z.B: |
widget | Ja | Code für die Funktion die verwendet werden soll.
| z.B. xs-deepsearch |
widgetmode | Ja | Gibt an ob die “targeturl” als Basis-URL für die Anfragen an den Server verwendet werden soll. Wenn die Domain in der das Widget die gleich Domain wie das Zielsystem besitzt, wird der Widgetmode mit “false” angegeben. Ansonsten mit dem Wert “true” angeben. | true |
language | Ja | Sprachkürzel nach ISO 639-1. Die Anzahl und möglichen Sprachkürzel sind Systemabhängig. Deutsch und Englisch stehen auf jedem System zur Verfügung.
| de |
parameter | Ja | Base64 encodiertes JSON Objekt mit den widgetspezifischen Parametern. Details sind aus den Beschreibungstabellen zu entnehmen. |
|
Ausgang | |||
loadfinished | ja | Dieses Event nach dem Anfragen des Systems ausgegeben. Sobald diese Event “true” geliefert hat, das HTML Element des zu ladenden Widgets zur Verfügung. Ab diesem Zeitpunkt kann ein EventListener registriert werden.
|
|
Beispielintegration
Folgendes Codesnippet in den HTML DOM einbetten.
Integration Widget-Loader Version 1.x.x
targeturl = https://2.0.open-datacheck.de
Integration Widget-Loader Version 2.x.x
targeturl = https://2.0.open-datacheck.de