Questo articolo guiderà l’integrazione dei Twin nelle applicazioni sviluppate con il game engine Unity3D.
L’SDK è alle fasi iniziali dello sviluppo, le feature per ora supportate sono:
- Apertura e chiusura sessione con un Twin
- Comunicazione col Twin, anche in lingue diverse
- Ricezione di link e media dai Twin
- Impostazione di variabili di contesto
Scaricare il progetto di esempio
Per testare le funzionalità dell’SDK forniamo una scena di esempio di una chat in stile Whatsapp, tramite la quale si può aprire una sessione e comunicare con un Twin.
Il progetto è disponibile al seguente link https://github.com/memori-ai/Aisuru-SDK, richiede Unity in versione 2021.3. Non è stato ancora testato con versioni più recenti.
Testare la comunicazione con un Twin
Una volta aperto il progetto Unity, aprire la scena SDKTest_GUI. Premendo play si può iniziare la comunicazione con un Twin già configurato, come nella schermata seguente:
Prima di iniziare, l’utente può impostare la lingua nel campo Language e la domanda iniziale nel campo Question, all’interno del componente SDKTest.
Premere play in Unity per iniziare. Per parlare con un Twin c’è bisogno di una sessione aperta, quindi premere il tasto Open in alto a destra per aprire una nuova sessione, all’apertura della sessione è legata una prima domanda introduttiva, che nell’SDK è modificabile cambiando il campo Question impostato in precedenza.
Apparirà in basso un campo di testo che permetterà di fare domande al Twin, il tasto Invia conferma la domanda. Il Twin risponderà e la conversazione può essere seguita al centro dello schermo con a destra le domande dell’utente e a sinistra le risposte del Twin.
Se una risposta del Twin contiene un allegato media o link, apparirà un pulsante Open Media sotto al messaggio di risposta. Cliccandolo si aprirà l’allegato nel browser web.
Alla fine della conversazione premere Close per chiudere la sessione, tutti gli URL degli allegati mandati nella conversazione verranno invalidati.
Configurare un nuovo Twin
Per cambiare il Twin con cui si vuole avviare la conversazione, bisogna configurare 2 scriptable objects: ServerData e Memori
ServerData contiene, tra gli altri, i dati dell’utente proprietario del Twin. L’istanza di ServerData è una e si trova nella cartella ScriptableObject del progetto.
Per ricavare i dati dell’utente da impostare in ServerData, andare nella pagina web https://www.aisuru.com/ e selezionare il pulsante Gestisci nel widget del Twin che si vuole configurare. Sulla sinistra apparirà una voce nella sidebar col nome del Twin selezionato, per accedere alle info che servono, espandere la voce del Twin, cliccare su Impostazioni e, in seguito, nella scheda Twin ID e Password in alto. Ora espandere Altri riferimenti e copiare il campo ID Utente Proprietario, lasciare la pagina web aperta visto che ci servirà in seguito.
Incollare ora il dato nel campo Owner ID dello scriptable object ServerData ed inserire il proprio username nel campo User Name. Lo user name è ricavabile anche dall’URL della pagina web aperta, appena dopo la parte https://www.aisuru.com/.
Si può procedere aggiungendo uno Scriptable Object per il nuovo Twin. Duplicare l’istanza presente nella cartella Scriptable Object/Memori e modificare 2 campi con dati ricavati dalla pagina web lasciata aperta in precedenza.
- Il campo Memori (Twin) ID bisogna copiarlo ed incollarlo nel campo ID Engine Memori in Unity
- Il campo Memori (Twin) ID secondario bisogna copiarlo ed incollarlo in ID Memori in Unity
- Impostare Memori Name col nome completo del Twin, spazi compresi
Per configurare la scena della chat col nuovo Twin bisogna trascinare lo scriptable object appena creato e configurato nel campo Twin Desc del componente SDKTest
Il nuovo Twin è ora disponibile per la conversazione e, alla pressione del tasto play, risponderà alle domande dell’utente, come nel paragrafo precedente.
Integrare l’SDK in un progetto Unity
L’SDK include un package Aisuru che contiene le classi che comunicano con i server Memori per le feature principali di comunicazione. Il package è presente nella cartella Packages del progetto e bisogna copiarlo nel progetto in cui si vuole integrare l’SDK. Insieme al package, copiare anche il contenuto di Assets, che contiene le scene di esempio, gli script e gli scriptable object che consentono una facile integrazione con i Twin.
Le funzionalità implementate sono tutte incluse nel componente SDKTest, nel dettaglio:
- OpenSession apre una nuova sessione e permette di indicare una domanda iniziale ed un dizionario con il contesto iniziale.
- SendRequest invia una domanda al Twin con la sessione aperta e prende come parametro la domanda da fare al Twin stesso.
- CloseCurrentSession chiude la sessione corrente.
OpenSession e SendRequest gestiscono automaticamente la traduzione di domande e risposte dalla lingua dell’utente alla lingua del Twin e viceversa.
SDKTest contiene anche una serie di callback per gestire le risposte dal server:
- OnSessionOpened quando una sessione con un Twin viene aperta con successo
- OnResponseGiven quando il Twin risponde
- OnMediaReceived chiamato per ogni allegato alla risposta del Twin
- OnSessionClosed quando la sessione viene chiusa
Un esempio di come utilizzare metodi e callback per integrare la comunicazione con i Twin è il codice presene nella classe SDKTestUI, che implementa tutte le funzionalità della chat stile Whatsapp usando le funzionalità di SDKTest.
Per integrare l’SDK in una scena Unity esistente eseguire questi step:
- Copiare ed incollare i GameObject API e SDK dalla scena di esempio
- Configurare gli scriptable object ServerData e Memori per la comunicazione con un proprio Twin
- Chiamare i metodi e registrarsi alle callback della classe SDKTest per integrare la comunicazione col Twin