Basisinstallation
Im Folgenden werden die grundlegenden Schritte zum Einrichten eines Oracle-Webkanals beschrieben.
Voraussetzungen
- Ein Oracle-Webkanal. Wenn Sie den Kanal erstellen, werden die Kanal-ID und der Secret Key generiert, die Sie zur Initialisierung der Chat-App benötigen.
- Die URL des Oracle-Chatservers.
- Das Oracle-Web-SDK (unter Oracle Native Client SDKs for OCI Native Environments) von der ODA- und OMC-Downloadseite von Oracle Technology Network. Laden Sie diese ZIP-Datei herunter, und extrahieren Sie sie in Ihr lokales System. Diese ZIP-Datei enthält ein Benutzerhandbuch, in dem die SDK-Klassen und eine Beispiel-App beschrieben werden, die viele der Features demonstriert.
Oracle-Webkanal konfigurieren
-
Authentifizierung wird mit JSON Web Token (JWT) durchgesetzt. Der Backend-Server des Kunden generiert das JWT-Token, das dann an das Oracle-Web-SDK übergeben wird. Dieses Token wird für jede Anforderung an einen ODA-Sprach-, Text- oder Anhangsserver verwendet.HinweisWenn die Webanwendung eine Verbindung zu einem ODA-Server herstellen muss, fordert sie zuerst das Token vom Backend-Server an und fügt es dann dem Autorisierungsheader hinzu. Der ODA-Server validiert das Token, wertet die Claims aus und öffnet dann entweder das Socket oder lehnt die Verbindung ab.
Um den Zugriff auf den Kanal zu schützen, muss das Token immer von einem Remoteserver generiert werden. Es darf nie im Clientbrowser generiert werden.Tipp:
In diesem Artikel werden die Schritte zur Ausführung des SDK mit einem authentifizierten Kanal beschrieben. - Nicht authentifizierter Modus: Verwenden Sie den nicht authentifizierten Modus, wenn der Client keine signierten JWT-Token generieren kann, wenn kein Authentifizierungsverfahren vorhanden ist oder wenn das Clientwidget bereits gesichert und für authentifizierte Benutzer sichtbar ist.
- Wählen Sie im Menü die Option Entwicklung und anschließend Kanäle aus.
- Wählen Sie Benutzer aus.
- Klicken Sie auf Kanal hinzufügen und dann auf Oracle Web als Kanaltyp.
- Nehmen Sie die gewünschten Änderungen im Dialogfeld vor:
- Geben Sie den Kanalnamen ein.
- Bei authentifizierten Verbindungen:
- Aktivieren Sie den Schalter Clientauthentifizierung aktiviert, um zu bestimmen, ob das SDK eine Verbindung zu einem für die Clientauthentifizierung aktivierten Kanal herstellt.
- Der Kanal kommuniziert nur mit den Sites aus den Domains, die Sie als durch Komma getrennte Liste hinzufügen. Beispiel:
*.corp.example.com
,*.hdr.example.com
. Wenn Sie ein einzelnes Sternchen (*) eingeben, wird uneingeschränkter Zugriff auf den Kanal von jeder beliebigen Domain aus ermöglicht. In der Regel geben Sie während der Entwicklung nur ein einzelnes Sternchen ein. Für die Produktion fügen Sie eine Ausnahmeliste für Domains hinzu. - Legen Sie im Feld "Max. Tokenablauf (Minuten)" die maximale Zeit für das JWT-Token fest.
- Bei nicht authentifizierten Verbindungen:
- Deaktivieren Sie den Schalter Clientauthentifizierung aktiviert.
- Geben Sie eine durch Komma getrennte Liste der Domains ein, die auf den Kanal zugreifen können. Wenn die Domains in dieser Ausnahmeliste Sternchen (
*.hdr.example.com
) enthalten oder die Ausnahmeliste nicht vollständig bekannt ist, müssen Sie eventuell eine authentifizierte Verbindung verwenden.
- Legen Sie die Sessionablaufzeit fest.
- Klicken Sie auf Erstellen. Oracle Digital Assistant generiert die Kanal-ID und den Secret Key, die Sie zur Initialisierung des SDK benötigen. Bewahren Sie diese Daten griffbereit auf, da Sie sie beim Konfigurieren der HTML-Seite zum Hosten des Chatwidgets benötigen.
- Leiten Sie den Kanal an Ihren Skill oder digitalen Assistenten weiter.
- Aktivieren Sie das Steuerelement Kanal aktiviert.
Tutorial: Oracle-Web-SDK-Chat sichern
In diesem Tutorial erhalten Sie eine praktische Einführung, wie Sie das Webchatwidget sichern: Oracle-Web-SDK-Chat sichern.
SDK installieren
- Suchen Sie in der extrahierten ZIP-Datei des heruntergeladenen Oracle-Web-SDK die Datei
web-sdk.js
(im Verzeichnisnative-client-sdk-js
). - Speichern Sie
web-sdk.js
(im Verzeichnisnative-client-sdk-js
der extrahierten ZIP-Datei) in Ihrem Projektverzeichnis. Notieren Sie sich den Dateispeicherort, da Sie ihn zum Definieren der Eigenschaft<WebSDK URL>
im Code des<script>
-Tags benötigen. - Erstellen Sie eine JavaScript-Datei mit der folgenden Funktion, die das SDK initialisiert. Diese Datei wird im Beispiel, das mit dem SDK geliefert wird, als
settings.js
bezeichnet.// settings.js const chatSettings = { URI: '<Server URI>', channelId: '<Channel ID>', userId: '<User ID>' }; function initSDK(name) { // If WebSDK is not available, reattempt later if (!document || !WebSDK) { setTimeout(function() { initSDK(name); }, 2000); return; } // Default name is Bots if (!name) { name = 'Bots'; } setTimeout(function() { const Bots = new WebSDK(chatSettings); // Initiate library with configuration let isFirstConnection = true; Bots.on(WebSDK.EVENT.WIDGET_OPENED, async () => { if (isFirstConnection) { try { await Bots.connect(); // Connect to server console.log('Connection Successful'); } catch (error) { console.log('Connection failed'); console.log(error); } isFirstConnection = false; } }); window[name] = Bots; }, 0); }
- Definieren Sie die folgenden Eigenschaften:
URI
: Der Hostname in der Oracle Digital Assistant-Instanz-URL. Hier muss nur der erste Pfad (/
) übergeben werden. Sie können diese URL entweder mit oder ohne das Protokoll (https://
) übergeben.channelId
: Die Kanal-ID, die beim Erstellen des Oracle-Webkanals generiert wird. Diese Eigenschaft ist erforderlich, da sie das Widget mit dem zugrunde liegenden Skill verbindet.userId
: Eine Benutzer-ID. Wenn Sie diesen Wert angeben, kann die Benutzerbasis für diesen Skill von den eindeutigen Benutzermetriken in Insights verfolgt werden. Wenn Sie keine Benutzer-ID angeben, das SDK jedoch eine mit jeder neuen Session generiert. Diese Eigenschaft ist bei nicht authentifizierten Verbindungen optional.
- Verweisen Sie auf Ihrer HTML-Seite auf die Speicherorte der JS-Datei (
setting.js
im folgenden Beispiel) derweb-sdk.js
-Bibliothek und des Web-SDK-Namespace, der in der RegelBots
lautet. Verwenden Sie diesen Namespace, um die öffentlichen APIs aufzurufen. Beispiel: Wenn Sie den Namensraum aufBots
setzen, rufen Sie die APIs alsBots.<API>()
auf. Weitere Informationen zu den verschiedenen Funktionen und Ereignissen finden Sie im Benutzerhandbuch (sowohl als Readme-Datei als auch als HTML-Dokument verfügbar), das in der ZIP-Datei des Oracle-Web-SDK enthalten ist.<script src="scripts/settings.js"></script> <script src="scripts/web-sdk.js" onload="initSdk('Bots')"></script>
SDK von einem CDN laden
web-sdk.js
nicht selbst hosten müssen.
Dieser Ansatz vereinfacht das Deployment, indem das Hosting der Web-SDK-Datei auf ein CDN ausgelagert wird, während Sie die Kontrolle über Ihre spezifischen Chatkonfigurationen über die Datei
settings.js
behalten.
web-sdk.js
ist.
- Erstellen Sie die Datei
settings.js
: Diese Datei enthält Ihre SDK-Konfiguration und die FunktioninitSDK
. Der Zweck dieser Datei und ihr Inhalt sind die gleichen wie im Abschnitt HTML-Skript-Tag beschrieben. Sie hosten diesesettings.js
-Datei weiterhin selbst. - Verknüpfen Sie settings.js und die CDN-gehostete
web-sdk.js
in Ihrer HTML-Datei: Fügen Sie im Abschnitt<head>
der HTML-Seite ein Skripttag für die lokal gehostetesettings.js
-Datei und ein anderes für das Web-SDK ein, und weisen Sie das Attributsrc
auf die CDN-URL.<head> <!-- 1. Your custom settings --> <script src="settings.js" defer></script> <!-- 2. Web SDK from CDN --> <script src="https://static.oracle.com/cdn/oda/<VERSION>/web-sdk.js" onload="initSDK('<WebSDK namespace>')" defer></script> <!-- Option A: Example with a specific version <script src="https://static.oracle.com/cdn/oda/25.4.0/web-sdk.js" onload="initSDK('Bots')" defer></script> Option B: Latest Stable Version (Convenient for always getting updates) <script src="https://static.oracle.com/cdn/oda/latest/web-sdk.js" onload="initSDK('Bots')" defer></script> --> <!-- Important Notes for the CDN script tag (choose one option from above): - Replace 'https://static.oracle.com/cdn/oda/<VERSION>/web-sdk.js' with the actual CDN URL provided for the Oracle Web SDK. - For Option A: Replace '<VERSION>' in the URL with the specific SDK version number you need (e.g., '25.4.0'). - For Option B: Using 'latest' instead of a specific version number will always load the most recent stable release. - See the 'Oracle CDN URLs' section below for a list of available versions and more details. - Replace '<WebSDK namespace>' (e.g., 'Bots' in the examples) with your chosen name for the SDK instance. --> </head>
CDN-Adressen
- Verwenden Sie das Tag
latest
:https://static.oracle.com/cdn/oda/latest/web-sdk.js
Diese URL verweist immer auf das neueste stabile Release des Web-SDK. Es ist praktisch für die Entwicklung oder wenn Sie möchten, dass Ihre Anwendung automatisch die neuesten Funktionen und Fixes erhält, sobald sie veröffentlicht werden.Hinweis
Seien Sie in Produktionsumgebungen vorsichtig. Während es praktisch ist, können automatische Updates Änderungen einführen. Für Produktionsumgebungen sollten Sie daher eine bestimmte Version verwenden, um Stabilität und Kontrolle über den Aktualisierungsprozess sicherzustellen. - Verwenden einer bestimmten Version:
https://static.oracle.com/cdn/oda/<VERSION>/web-sdk.js
Hinweis
Verwenden Sie eine bestimmte URL für Produktionsumgebungen.Mit diesem Ansatz können Sie eine feste, spezifische Version des Web-SDK verwenden, die für Produktionsumgebungen empfohlen wird. Es gibt Ihnen die Kontrolle darüber, wann Updates eingespielt werden, und ermöglicht gründliche Tests.
Um eine bestimmte Version festzulegen, ersetzen Sie<VERSION>
durch die gewünschte Versionsnummer (z.B. 25.4.0). Derzeit verfügbare stabile Versionen umfassen:- Version 25.04: https://static.oracle.com/cdn/oda/25.4.0/web-sdk.js
- Version 25.02: https://static.oracle.com/cdn/oda/25.2.0/web-sdk.js
- Version 24.12: https://static.oracle.com/cdn/oda/24.12.0/web-sdk.js
- Version 24.10: https://static.oracle.com/cdn/oda/24.10.0/web-sdk.js
- Version 24.08: https://static.oracle.com/cdn/oda/24.8.0/web-sdk.js
- Version 24.06: https://static.oracle.com/cdn/oda/24.6.0/web-sdk.js
- Version 24.04: https://static.oracle.com/cdn/oda/24.4.0/web-sdk.js
- Version 24.02: https://static.oracle.com/cdn/oda/24.2.0/web-sdk.js
Tipp:
Die aktuelle Liste der verfügbaren CDN-Versionen und detaillierten Releaseinformationen finden Sie in den neuesten SDK-Versionshinweisen oder in der offiziellen Oracle Digital Assistant-Dokumentation.
Library mit der AMD-API importieren
requirejs.config({
paths: {
WebSDK: '<path of the web-sdk>' // replace this with actual library path
} });
define(['WebSDK'], function(WebSDK)
{ const settings = {
URI: '<Server URI>',
channelId: '<Channel ID>',
userId: '<User ID>'
};
Bots = new WebSDK(settings);
Bots.connect();
});
Library dynamisch mit JavaScript importieren
function fetchSDK(src, onloadFunction, name) {
const script = document.createElement('script');
script.type = 'application/javascript';
script.async = true; // load the script asynchronously
script.defer = true; // fallback support for browsers that does not support async
script.onload = function() {
onloadFunction(name);
};
document.head.appendChild(script);
script.src = src;
}
fetchSDK('', initSDK, '');
Clientauthentifizierung konfigurieren
Neben der Verwendung von Listen zulässiger Domains wird die Clientauthentifizierung durch signierte JWT-Token erzwungen.
Die Tokengenerierung und -signatur muss vom Client auf dem Backend-Server (vorzugsweise nach der Benutzer-/Clientauthentifizierung) ausgeführt werden, der keyId
und keySecret
sichern kann.
Wenn das SDK eine Verbindung mit dem ODA-Server herstellen muss, fordert es zunächst ein JWT-Token vom Client an und sendet dieses dann zusammen mit der Verbindungsanforderung. Der ODA-Server validiert die Tokensignatur und ruft das Claimset aus der JWT-Payload ab, um das Token zum Herstellen der Verbindung zu prüfen.
clientAuthEnabled: true
muss im SDK-Einstellungsparameter übergeben werden, und eine Tokengeneratorfunktion muss als zweiter Parameter übergeben werden. Die Funktion muss einen Promise zurückgeben, der aufgelöst wird, um eine signierte JWT-Tokenzeichenfolge zurückzugeben.async function generateToken() {
const token = await fetch('https://yourbackend.com/endpointToGenerateJWTToken');
return token;
}
Bots.init({
URI: 'oda-instance.com',
clientAuthEnabled: true
}, generateToken);
Das JWT Token
iat
: Ausstellungszeitexp
: AblaufzeitchannelId
: Kanal-IDuserId
: Benutzer-ID
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NzY3NDcyMDUsImV4cCI6MTU3Njc1MTExNywiY2hhbm5lbElkIjoiNDkyMDU5NWMtZWM3OS00NjE3LWFmOWYtNTk1MGQ2MDNmOGJiIiwidXNlcklkIjoiSm9obiIsImp0aSI6ImQzMjFjZDA2LTNhYTYtNGZlZS05NTBlLTYzZGNiNGVjODJhZCJ9.lwomlrI6XYR4nPQk0cIvyU_YMf4gYvfVpUiBjYihbUQ
- Header:
{ "typ": "JWT", "alg": "HS256" }
- Payload:
{ "iat": 1576747205, "exp": 1576748406, "channelId": "4920595c-ec79-4617-af9f-5950d603f8bb", "userId": "John" }