Impostazioni di base
Di seguito sono riportati i passi di base per ottenere l'impostazione di un canale Web Oracle.
Di cosa hai bisogno?
- Un canale Web Oracle. La creazione del canale genera l'ID canale e la chiave segreta necessari per inizializzare l'applicazione chat.
- URL del server di chat Oracle.
- Oracle Web SDK (situato negli SDK client nativi Oracle per ambienti nativi OCI) dalla pagina di download di ODA e OMC di Oracle Technology Network. Scarica questo ZIP ed estrarlo sul sistema locale. Questo ZIP include una guida per l'utente che descrive le classi dell'SDK e un'app di esempio che illustra molte delle sue funzioni.
Configurare il canale Web Oracle
-
L'autenticazione viene applicata utilizzando i token Web JSON (JWT). Il server backend del cliente genera il token JWT, che viene quindi passato all'SDK Web Oracle. Questo token viene utilizzato per ogni richiesta a un server di sintesi vocale, di testo o di allegati ODA.NotaQuando l'applicazione Web deve connettersi a un server ODA, in primo luogo richiede il token dal server backend e quindi lo aggiunge all'intestazione di autorizzazione. Il server ODA convalida il token, valuta le richieste, quindi apre il socket o rifiuta la connessione.
Per proteggere l'accesso al canale, il token deve essere sempre generato da un server remoto. Non deve mai essere generato all'interno del browser client.Suggerimento
Questo articolo consente di eseguire l'SDK con un canale autenticato. - Modalità non autenticata: utilizzare la modalità non autenticata quando il client non è in grado di generare token JWT firmati, quando non è presente alcun meccanismo di autenticazione o quando il widget client è già protetto e visibile agli utenti autenticati.
- Scegliere Sviluppo, quindi Canali dal menu.
- Scegliere Utenti.
- Fare clic su Aggiungi canale, quindi su Oracle Web come tipo di canale.
- Completare la finestra di dialogo:
- Immettere il nome del canale.
- Per le connessioni autenticate:
- Attivare l'opzione Autenticazione client abilitata per determinare se l'SDK si sta connettendo a un canale abilitato all'autenticazione del client.
- Il canale comunicherà con i siti solo dai domini aggiunti come elenco separato da virgole. Ad esempio,
*.corp.example.com
,*.hdr.example.com
. L'immissione di un singolo asterisco (*) consente l'accesso illimitato al canale da qualsiasi dominio. In genere, durante lo sviluppo si immette un solo asterisco. Per la produzione, aggiungere una lista di inclusione di domini. - Nel Max. Campo Scadenza token (minuti), impostare la quantità massima di tempo per il token JWT.
- Per le connessioni non autenticate:
- Disattivare l'opzione Abilitazione autenticazione client.
- Immettere una lista separata da virgole di domini che possono accedere al canale. Se i domini in questa lista di inclusione includono asterischi (
*.hdr.example.com
) o se la lista di inclusione non è completamente nota, è possibile prendere in considerazione una connessione autenticata.
- Impostare l'ora di scadenza della sessione.
- Fare clic su Crea. Oracle Digital Assistant genererà l'ID canale e la chiave segreta necessari per inizializzare l'SDK. Tienili a portata di mano perché ne avrai bisogno durante la configurazione della pagina HTML per ospitare il widget di chat.
- Instrada il canale allo skill o all'assistente digitale.
- Attivare Canale abilitato.
Esercitazione: Proteggi la tua chat Oracle Web SDK
Puoi dare un'occhiata pratica alla protezione del widget Chat Web attraverso questa esercitazione: Proteggi la tua chat Oracle Web SDK.
Installare l'SDK
- Nel file ZIP estratto del kit Oracle Web SDK scaricato, individuare il file
web-sdk.js
(posizionato nella directorynative-client-sdk-js
). - Salvare
web-sdk.js
(posizionato nella directorynative-client-sdk-js
dello ZIP estratto) nella directory del progetto. Prendere nota della posizione del file, poiché sarà necessario definire la proprietà<WebSDK URL>
nel codice del tag<script>
. - Creare un file JavaScript con la funzione seguente che inizializza l'SDK. Questo file viene chiamato
settings.js
nell'esempio fornito con l'SDK.// 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); }
- Definire le proprietà descritte di seguito.
URI
: il nome host nell'URL dell'istanza di Oracle Digital Assistant. Solo il primo percorso (/
) deve essere passato qui. È possibile passare questo URL con o senza il protocollo (https://
).channelId
: l'ID canale generato quando si crea il canale Web Oracle. Questa proprietà è necessaria perché collega il widget allo skill sottostante.userId
: un ID utente. Quando si specifica questo valore, è possibile tenere traccia della base utenti per questo skill mediante le metriche utente univoche in Insights. Quando non si fornisce un ID utente, ma l'SDK ne genererà uno con ogni nuova sessione. Questa proprietà è opzionale per le connessioni non autenticate.
- Nella pagina HTML, fare riferimento alle posizioni sia del file JS (
setting.js
nell'esempio seguente) della libreriaweb-sdk.js
che dello spazio di nomi Web SDK, che in genere èBots
. Utilizzare questo spazio di nomi per richiamare le API pubbliche. Ad esempio, se si imposta lo spazio di nomi suBots
, le API vengono richiamate comeBots.<API>()
. Per ulteriori informazioni sulle varie funzioni ed eventi, fare riferimento al manuale utente (disponibile sia come file Readme che come documento HTML) incluso nel file ZIP di Oracle Web SDK.<script src="scripts/settings.js"></script> <script src="scripts/web-sdk.js" onload="initSdk('Bots')"></script>
Caricare l'SDK da una rete CDN
web-sdk.js
da soli.
Questo approccio semplifica la distribuzione scaricando l'hosting del file SDK Web su una rete CDN mentre si mantiene il controllo sulle configurazioni chat specifiche tramite il file
settings.js
.
web-sdk.js
.
- Creare il file
settings.js
: questo file conterrà la configurazione SDK e la funzioneinitSDK
. Lo scopo di questo file e il suo contenuto sono gli stessi di quelli descritti nella sezione HTML Script Tag. Si continua a ospitare questo filesettings.js
. - Collegare settings.js e
web-sdk.js
ospitato da CDN nel file HTML: nella sezione<head>
della pagina HTML, includere un tag script per il filesettings.js
ospitato localmente e un altro per l'SDK Web, puntando l'attributosrc
all'URL CDN.<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>
URL CDN
- Utilizzo del tag
latest
:https://static.oracle.com/cdn/oda/latest/web-sdk.js
Questo URL punta sempre alla release stabile più recente dell'SDK Web. È conveniente per lo sviluppo o se si desidera che l'applicazione riceva automaticamente le funzionalità e le correzioni più recenti man mano che vengono rilasciate.Nota
Prestare attenzione negli ambienti di produzione. Benché convenienti, gli aggiornamenti automatici possono introdurre modifiche. Quindi, per gli ambienti di produzione, prendere in considerazione l'utilizzo di una versione specifica per garantire stabilità e controllo sul processo di aggiornamento. - Utilizzo di una versione specifica:
https://static.oracle.com/cdn/oda/<VERSION>/web-sdk.js
Nota
Utilizzare un URL specifico per gli ambienti di produzione.Questo approccio consente di utilizzare una versione fissa e specifica dell'SDK Web, consigliata per gli ambienti di produzione. Ti dà il controllo su quando vengono applicati gli aggiornamenti e consente test approfonditi.
Per impostare una versione specifica, sostituire<VERSION>
con il numero di versione desiderato (ad esempio, 25.4.0). Le versioni stabili attualmente disponibili includono:- Versione 25.04: https://static.oracle.com/cdn/oda/25.4.0/web-sdk.js
- Versione 25.02: https://static.oracle.com/cdn/oda/25.2.0/web-sdk.js
- Versione 24.12: https://static.oracle.com/cdn/oda/24.12.0/web-sdk.js
- Versione 24.10: https://static.oracle.com/cdn/oda/24.10.0/web-sdk.js
- Versione 24.08: https://static.oracle.com/cdn/oda/24.8.0/web-sdk.js
- Versione 24.06: https://static.oracle.com/cdn/oda/24.6.0/web-sdk.js
- Versione 24.04: https://static.oracle.com/cdn/oda/24.4.0/web-sdk.js
- Versione 24.02: https://static.oracle.com/cdn/oda/24.2.0/web-sdk.js
Suggerimento:
Per l'elenco più aggiornato delle versioni CDN disponibili e informazioni dettagliate sulla release, consultare sempre le note di rilascio dell'SDK più recenti o la documentazione ufficiale di Oracle Digital Assistant.
Importazione della libreria mediante l'API di definizione del modulo asincrono
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();
});
Importare la libreria in modo dinamico con JavaScript
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, '');
Configura autenticazione client
Oltre a utilizzare liste di domini consentiti, l'autenticazione client viene applicata dai token JWT firmati.
La generazione e la firma del token devono essere eseguite dal client nel server backend (preferibilmente dopo l'autenticazione utente/client) in grado di mantenere la sicurezza keyId
e keySecret
.
Quando l'SDK deve stabilire una connessione con il server ODA, in primo luogo richiede un token JWT dal client e quindi lo invia insieme alla richiesta di connessione. Il server ODA convalida la firma del token e ottiene il set di richieste dal payload JWT per verificare il token per stabilire la connessione.
clientAuthEnabled: true
deve essere passato nel parametro delle impostazioni dell'SDK e una funzione generatore di token deve essere passata come secondo parametro. La funzione deve restituire una promessa, risolta per restituire una stringa di token JWT firmata.async function generateToken() {
const token = await fetch('https://yourbackend.com/endpointToGenerateJWTToken');
return token;
}
Bots.init({
URI: 'oda-instance.com',
clientAuthEnabled: true
}, generateToken);
Il token JWT
iat
- emesso in tempoexp
- tempo di scadenzachannelId
: ID canaleuserId
- ID utente
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NzY3NDcyMDUsImV4cCI6MTU3Njc1MTExNywiY2hhbm5lbElkIjoiNDkyMDU5NWMtZWM3OS00NjE3LWFmOWYtNTk1MGQ2MDNmOGJiIiwidXNlcklkIjoiSm9obiIsImp0aSI6ImQzMjFjZDA2LTNhYTYtNGZlZS05NTBlLTYzZGNiNGVjODJhZCJ9.lwomlrI6XYR4nPQk0cIvyU_YMf4gYvfVpUiBjYihbUQ
- Intestazione:
{ "typ": "JWT", "alg": "HS256" }
- Payload:
{ "iat": 1576747205, "exp": 1576748406, "channelId": "4920595c-ec79-4617-af9f-5950d603f8bb", "userId": "John" }